¿Cómo vincular a parte del mismo documento en Markdown?


541

Estoy escribiendo un gran documento de Markdown y me gustaría colocar una tabla de contenido al principio que proporcione enlaces a varias ubicaciones en el documento. ¿Cómo puedo hacer esto?

Traté de usar

[a link](# MyTitle)

donde MyTitlehay un título dentro del documento y esto no funcionó.



1
El único problema que tuvo es que MyTitle no debería ser un título, sino el nombre de un ancla en ese documento (como <a name="MyTitle"> </a>). Entonces podrá usar su enlace original, en cualquier parte del documento.
userfuser

77
La respuesta aceptada no es realmente relevante para la mayoría de las personas. En cambio, vea la segunda respuesta: stackoverflow.com/a/16426829/398630
BrainSlugs83

Respuestas:


37

En pandoc , si usa la opción --tocpara producir html, se generará una tabla de contenido con enlaces a las secciones y de regreso a la tabla de contenido desde los encabezados de sección. Es similar a los otros formatos que escribe pandoc, como LaTeX, rtf, rst, etc. Así que con el comando

pandoc --toc happiness.txt -o happiness.html

este bit de rebaja:

% True Happiness

Introduction
------------

Many have posed the question of true happiness.  In this blog post we propose to
solve it.

First Attempts
--------------

The earliest attempts at attaining true happiness of course aimed at pleasure. 
Soon, though, the downside of pleasure was revealed.

producirá esto como el cuerpo del html:

<h1 class="title">
    True Happiness
</h1>
<div id="TOC">
    <ul>
        <li>
            <a href="#introduction">Introduction</a>
        </li>
        <li>
            <a href="#first-attempts">First Attempts</a>
        </li>
    </ul>
</div>
<div id="introduction">
    <h2>
        <a href="#TOC">Introduction</a>
    </h2>
    <p>
        Many have posed the question of true happiness. In this blog post we propose to solve it.
    </p>
</div>
<div id="first-attempts">
    <h2>
        <a href="#TOC">First Attempts</a>
    </h2>
    <p>
        The earliest attempts at attaining true happiness of course aimed at pleasure. Soon, though, the downside of pleasure was revealed.
    </p>
</div>

1
Gracias, esto era exactamente lo que necesitaba. Estaba usando Textmate para convertir Markdown a HTML, cambiará a pandoc.
recipriversexclusion

1
Puede probar la demostración Pandoc tmbundle en Github (también hay modo emacs pandoc, etc.) El tmbundle reutiliza el resaltador de sintaxis específico de MultiMarkdown, por lo que hay algunas (muy) pocas rarezas. Además, muchos de los scripts asociados están altamente personalizados, por ejemplo, Context, no LaTeX, etc., pero la idea es que los usuarios los modifiquen a su antojo, lo que me pareció bastante simple. Probablemente debería estar git cloneen el directorio tmbundle más bajo o más externo, ~/Library/Application\ Support/TextMate/Bundlespara simplificar la integración.
aplicativo

2
Se añade -1a la primera repetición del ello, -2para el segundo, etc.
aplicativo

66
Descubrí que tenía que agregar la opción --standalone al comando pandoc para hacer que realmente muestre la tabla de contenido en la salida. Sin ese modificador, los encabezados se convertirían en enlaces de regreso al ancla con nombre #toc, pero en realidad no generaría el ancla con nombre y la lista de similares.
Duncan Lock

44
Esto podría responder a la pregunta del OP, pero para el resto de nosotros que queremos saber cómo hacerlo en Markdown , es bastante inútil. - La siguiente respuesta es mucho más útil.
BrainSlugs83

936

Github analiza automáticamente las etiquetas de anclaje de sus encabezados. Entonces puedes hacer lo siguiente:

[Custom foo description](#foo)

# Foo

En el caso anterior, el Fooencabezado ha generado una etiqueta de anclaje con el nombrefoo

Nota : solo uno #para todos los tamaños de encabezado, sin espacio entre el #nombre de anclaje , los nombres de etiqueta de anclaje deben estar en minúsculas y delimitados por guiones si tienen varias palabras .

[click on this link](#my-multi-word-header)

### My Multi Word Header

Actualizar

Funciona fuera de la caja con pandoctambién.


54
Si su encabezado contiene varias palabras, "Como esta", reemplace los espacios con guiones en el ancla [just](#like-this-one).
Mogsdad

3
¿Esto solo funciona para los encabezados H1? Si se vincula a un encabezado H2 (es decir, ## Foo), ¿también necesito poner dos signos de número en el enlace, es decir, [Foo] (## foo)? No puedo hacer que su sintaxis o la mía funcionen (con el signo de número adicional).
GrayedFox

77
@GrayedFox, si desea crear un enlace para el encabezado ab H2 ## Foo, intente [este es mi enlace a Foo] (# foo) ... es decir: hash único , sin espacio entre hash y minúsculas-kebab-case-name- de cabecera
Abdull

44
Como consejo: revise el ancla que se muestra junto a su encabezado en Github para obtener el enlace respectivo, es decir, si contiene caracteres especiales, se eliminan automáticamente y se muestra el enlace correcto allí.
Alexander Pacha

2
¿Qué pasa cuando los títulos tienen número? # 3. Tercer punto [Tercer punto] (# 3.-tercer.punto) no funciona
Aditya

118

Experimentando, encontré una solución usando, <div…/>pero una solución obvia es colocar su propio punto de anclaje en la página donde lo desee, por lo tanto:

<a name="abcde">

antes y

</a>

después de la línea a la que desea 'enlazar'. Luego un enlace de descuento como:

[link text](#abcde)

cualquier parte del documento te lleva allí.

La <div…/>solución inserta una división "ficticia" solo para agregar la idpropiedad, y esto es potencialmente perjudicial para la estructura de la página, pero la <a name="abcde"/>solución debería ser bastante inocua.

(PD: podría estar bien colocar el ancla en la línea a la que desea vincular, de la siguiente manera:

## <a name="head1">Heading One</a>

pero esto depende de cómo Markdown trate esto. Noto, por ejemplo, que el formateador de respuestas Stack Overflow está contento con esto)


2
Si hace esto, debe tener en cuenta que el div elimina otros formatos de reducción, como ## headers.
2rs2ts

@ user691859 ¿Puedes dar más detalles? Quizás podamos actualizar una respuesta para que funcione mejor. Vi que TextMate suprime el resaltado, hasta que sangré el div, pero no hubo ningún problema con la reducción procesada vista desde un navegador.
Steve Powell

En WriteMonkey descubrí que si precedo cualquier texto con las <div/>varias líneas siguientes se ven afectadas. En cambio, tengo que ajustar el texto que estoy vinculando en una divcláusula de etiqueta completa y tengo que volver a ESPECIFICAR el comportamiento desde cero usando HTML real. Abucheo.
2rs2ts

66
Esto funciona bien, gracias. Para cualquiera que se pregunte, esto también funciona con los archivos Markdown alojados y mostrados por GitHub.
Alex Dean

2
Para ser compatible con HTML5 , me gustaría recomendar reemplazarlo <a name="head1"/>por <a id="head1"/>.
binki

74

Esto puede ser fuera de fecha hilo, pero para crear enlaces de documentos internos en rebajas en el uso de Github ...
(NOTA: minúsculas #title)

    # Contents
     - [Specification](#specification) 
     - [Dependencies Title](#dependencies-title) 

    ## Specification
    Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. 

    ## Dependencies Title
    Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. 

Se hizo una buena pregunta, así que he editado mi respuesta;

Un enlace interno puede hacerse a cualquier tamaño usando título - #, ##, ###, #### creé un ejemplo rápido abajo ... https://github.com/aogilvie/markdownLinkTest


En su ejemplo, las etiquetas de enlace solo tienen un #, pero los encabezados que deben enlazar tienen dos ##; ¿No deberían ser lo mismo?
Karim Bahgat

3
Buena pregunta. La respuesta es no. el # en (#dependencies-title)le dice a Github Markdown que este es un enlace interno. El texto que sigue puede tener cualquier tamaño de título. Aquí hay un ejemplo de prueba que hice ... https://github.com/aogilvie/markdownLinkTest
Ally

1
¿Eso depende del sabor del descuento? Parece que funciona bien en el editor de rebajas, pero cuando guardo en html o pdf, los identificadores no se agregan a las etiquetas apropiadas. Estaría bien simplemente arrojando un ancla allí, pero parece que su método es mucho más limpio y rápido.
meteorainer

21

Sí, Markdown hace esto, pero debe especificar el nombre de anclaje <a name='xyx'>.

un ejemplo completo

esto crea el enlace
[tasks](#tasks)

más adelante en el documento, crea el ancla con nombre (como se llame).

<a name="tasks">
   my tasks
</a>

tenga en cuenta que también podría envolverlo alrededor del encabezado también.

<a name="tasks">
### Agile tasks (created by developer)
</a>

13

El manual de pandoc explica cómo vincular a sus encabezados, utilizando su identificador. No verifiqué el soporte de esto por otros analizadores, pero se informó que no funciona en github .

El identificador se puede especificar manualmente:

## my heading text {#mht}
Some normal text here,
including a [link to the header](#mht).

o puede usar el identificador generado automáticamente (en este caso #my-heading-text). Ambos se explican en detalle en el manual de pandoc .

NOTA : Esto solo funciona cuando se convierte a HTML , LaTex , ConTeXt , Textile o AsciiDoc .


9

Algunas cosas adicionales a tener en cuenta si alguna vez te apetece usar símbolos dentro de los encabezados por los que quieras navegar ...

# What this is about


------


#### Table of Contents


- [About](#what-this-is-about)

- [&#9889; Sunopsis](#9889-tldr)

- [:gear: Grinders](#it-grinds-my-gears)

- [Attribution]


------


## &#9889; TLDR


Words for those short on time or attention.


___


## It Grinds my :gear:s


Here _`:gear:`_ is not something like &#9881; or &#9965;


___


## &#9956; Attribution


Probably to much time at a keyboard



[Attribution]: #9956-attribution

... cosas como #, ;, &, y :dentro de la partida cuerdas están generalmente son ignorados / rayas en lugar de escapar, y también se pueden utilizar citación de enlaces de estilo para hacer un uso más fácil rápida.

Notas

GitHub es compatible con la :word:sintaxis en confirmaciones, archivos readme, etc. ver lo esencial (de rxaviers) si using'em es de interés allí.

Y para casi cualquier otro lugar se puede usar decimal o hexadecimal para los navegadores modernos; la hoja de trucos de w3schools es muy útil , especialmente si usar CSS ::beforeo ::afterpseudoelementos con símbolos es más su estilo.

¿Puntos extra?

Por si alguien se preguntaba cómo las imágenes y otros enlaces dentro de un encabezado se analizan en un id...

- [Imaged](#alt-textbadge__examplehttpsexamplecom-to-somewhere)


## [![Alt Text][badge__example]](https://example.com) To Somewhere


[badge__example]:
  https://img.shields.io/badge/Left-Right-success.svg?labelColor=brown&logo=stackexchange
  "Eeak a mouse!"

Advertencias

La representación de MarkDown difiere de un lugar a otro, por lo que cosas como ...

## methodName([options]) => <code>Promise</code>

... en GitHub tendrá un elemento con id...

id="methodnameoptions--promise"

... donde el saneamiento de vainilla resultaría en un id...

id="methodnameoptions-codepromisecode"

... lo que significa que escribir o compilar archivos MarkDown a partir de plantillas requiere apuntar a una forma de slugifeing , o agregar configuraciones y lógica con secuencias de comandos para las diversas formas inteligentes en las que lugares como limpiar el texto del encabezado.


9

Soluciones universales

Esta pregunta parece tener una respuesta diferente según la implementación del descuento.
De hecho, la documentación oficial de Markdown no dice nada sobre este tema.
En tales casos, y si desea una solución portátil, puede usar HTML.

Antes de cualquier encabezado, o en la misma línea de encabezado, defina una ID usando alguna etiqueta HTML.
Por ejemplo: <a id="Chapter1"></a>
verá esto en su código pero no en el documento representado.

Ejemplo completo:

Vea un ejemplo completo (en línea y editable) aquí .

## Content

* [Chapter 1](#Chapter1)
* [Chapter 2](#Chapter2)

<div id="Chapter1"></div>
## Chapter 1

Some text here.  
Some text here.
Some text here.

## Chapter 2 <span id="Chapter2"><span>

Some text here.  
Some text here.
Some text here.

Para probar este ejemplo, debe agregar algo de espacio adicional entre la lista de contenido y el primer capítulo o reducir la altura de la ventana.
Además, no use espacios en el nombre de los identificadores.


Uh ... parecía agradable. Probado, dos problemas: (1). ## Chapter 1necesita una línea abierta sobre ella. (2) El enlace no funciona ...
musicformellons

Ah, no funciona en el complemento intellij markdown que utilicé; pero funciona en el editor de marcado de Macdown.
musicformellons

Aún así, probado en github: se requiere una línea abierta sobre el encabezado, pero funciona.
musicformellons

@musicformellons, ¿puede intentarlo sin la línea de apertura pero cerrando correctamente la etiqueta span? <br><span id="Chapter1"><span>
ePi272314

si, funciona!
musicformellons

7

No existe tal directiva en la especificación Markdown. Lo siento.


¡UH oh! ¿Sabes si MultiMarkdown o Textile lo admiten? Estaba pensando en migrar a MD para toda mi documentación, pero esto es un factor decisivo. ¡Gracias por la ayuda!
recipriversexclusion

55
¿Qué quieres decir con "directiva"? Otras soluciones para exactamente el problema se han publicado aquí.
Zelphir Kaltstahl el

4

Gitlab utiliza GitLab Flavored Markdown (GFM)

Aquí "todos los encabezados procesados ​​por Markdown obtienen ID automáticamente"

Se puede usar el mouse para:

  • mover el mouse sobre el encabezado
  • mueva el mouse sobre el selector de desplazamiento que se hace visible a la izquierda desde el encabezado
  • copie y guarde el enlace con el botón derecho del mouse

    Por ejemplo, en el archivo README.md tengo encabezado:

## series expansion formula of the Boettcher function

que da un enlace:

https://gitlab.com/adammajewski/parameter_external_angle/blob/master/README.md#series-expansion-formula-of-the-boettcher-function

El prefijo se puede eliminar, por lo que el enlace aquí es simplemente

file#header

que aquí significa:

README.md#series-expansion-formula-of-the-boettcher-function

Ahora se puede usar como:

[series expansion formula of the Boettcher function](README.md#series-expansion-formula-of-the-boettcher-function)

También se puede hacer manualmente: reemplazar espacios con un signo de guión.

El ejemplo en vivo está aquí


1

Usando kramdown, parece que esto funciona bien:

[I want this to link to foo](#foo)
....
....
{: id="foo"}
### Foo are you?

Veo que se ha mencionado que

[foo][#foo]
....
#Foo

funciona de manera eficiente, pero la primera podría ser una buena alternativa para elementos además de encabezados o encabezados con varias palabras.


1

Dado que MultiMarkdown fue mencionado como una opción en los comentarios.

En MultiMarkdown, la sintaxis de un enlace interno es simple.

Para cualquier encabezado en el documento simplemente dé el nombre del encabezado en este formato [heading][]para crear un enlace interno.

Lea más aquí: MultiMarkdown-5 Referencias cruzadas .

Referencias cruzadas

Una característica solicitada con frecuencia era la capacidad de hacer que Markdown manejara automáticamente los enlaces dentro del documento tan fácilmente como manejaba los enlaces externos. Para este objetivo, agregué la capacidad de interpretar [Some Text] [] como un enlace cruzado, si existe un encabezado llamado "Some Text".

Como ejemplo, [Metadata] [] lo llevará a # Metadata (o cualquiera de ## Metadata, ### Metadata, #### Metadata, ##### Metadata, ###### Metadata).

Alternativamente, puede incluir una etiqueta opcional de su elección para ayudar a desambiguar casos en los que varios encabezados tienen el mismo título:

### Descripción general [MultiMarkdownOverview] ##

Esto le permite usar [MultiMarkdownOverview] para referirse específicamente a esta sección, y no a otra sección llamada Descripción general. Esto funciona con encabezados de estilo atx o settext.

Si ya ha definido un ancla usando la misma identificación que usa un encabezado, entonces el ancla definida tiene prioridad.

Además de los encabezados dentro del documento, puede proporcionar etiquetas para imágenes y tablas que luego también pueden usarse para referencias cruzadas.


0

Algunos giros más en el <a name="">truco:

<a id="a-link"></a> Title
------

#### <a id="a-link"></a> Title (when you wanna control the h{N} with #'s)

0

Además de las respuestas anteriores,

Al configurar la opción number_sections: trueen el encabezado YAML:

number_sections: TRUE

RMarkdown numerará automáticamente sus secciones.

Para hacer referencia a esas secciones numeradas automáticamente, simplemente ponga lo siguiente en su archivo R Markdown:

[My Section]

¿Dónde My Sectionestá el nombre de la sección?

Esto parece funcionar independientemente del nivel de sección:

# My section

## My section

### My section

Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.