¿Cómo creo algún tipo de tabla de contenido en la wiki de GitHub?

Respuestas:

111

Está bien demostrado en la tabla de contenido de la hoja de referencia de Markdown .

##### Table of Contents  
[Headers](#headers)  
[Emphasis](#emphasis)  
...snip...    
<a name="headers"/>
## Headers

Si pasa el cursor sobre un encabezado en un archivo de GitHub Markdown, verá un pequeño enlace simple a la izquierda, también puede usar ese enlace. El formato de ese enlace es <project URL#<header name>. El <header name>debe ser todo en minúsculas.

RyPeck
fuente
36
Seguramente hay una manera de generarlo automáticamente como _ _ TOC _ _ de MediaWiki.
LB--
17
@ LB--: Si editas una página wiki de GitHub y cambias el menú desplegable "estilo de edición" a "MediaWiki", puedes usar MediaWiki __TOC__directamente. Claramente, la lógica de autogeneración subyacente está ahí. Pero la funcionalidad no parece estar expuesta en su estilo de edición Markdown. Muy desafortunado. Comencemos todos a enviar solicitudes de funciones y tal vez lo activen.
Andrew Janke
3
Me retracto de que la "lógica de autogeneración subyacente" esté ahí; parece que los diferentes "estilos de edición" pasan por diferentes renderizadores. Aún así, sería genial tener esto en la versión MD, ya que es bastante popular y no podría ser difícil de agregar.
Andrew Janke
5
@AndrewJanke Lo investigué más, parece que el formato MarkDown no tiene soporte para la generación automática de tablas de contenido, y están orgullosos de ello.
LB--
6
Hay un problema al crear enlaces. Tienen que estar en minúsculas. No sabía eso y me preguntaba por qué mi TOC no funciona. Usé en #Headerslugar de #headers. Pensé que era un error tipográfico en tu respuesta. Quizás pueda agregar a su respuesta esta información.
t3chb0t
20

Una posible solución (semiautomatizada) es la de Eugene Kalinin github-markdown-toc. Básicamente, esta herramienta README.mdanaliza su archivo y extrae #los encabezados para crear un TOC.

  1. Descarga el script https://github.com/ekalinin/github-markdown-toc
  2. Alimenta tu README.mdguión (como se indica en el de Eugene README.md)

    cat README.md | bash github-markdown-toc

  3. Corta y pega el TOC generado y colócalo en la parte superior de tu README.mdarchivo

Tenga en cuenta que esta bashimplementación solo funciona en Linux (por lo que puedo decir).

Como nota al margen, hay una implementación de golang y probablemente sea más complicado ponerse a trabajar.

John Tran
fuente
14

https://github.com/jonschlinkert/markdown-toc

  • git clone your-repo.wiki.git(agregue el .wikiderecho antes .gitpara clonar el wiki
  • npm i -g markdown-toc
  • Inserte <!-- toc -->( distingue entre mayúsculas y minúsculas) en la rebaja de su wiki
  • markdown-toc -i my-wiki-markdown.md( -ilo editará en su lugar)
  • Lucro

Actualización: creo que quizás https://github.com/thlorenz/doctoc sea ​​más popular ahora.

corysimmons
fuente
12

Actualmente no es posible hacer eso usando la sintaxis de rebajas ( .md). Existe una discusión no oficial en curso sobre la generación automática de tabla de contenido TOC en archivos de rebajas renderizados como el README.mdque enumera algunas de las ideas.

Sin embargo, existen otras soluciones como:

Kenorb
fuente
1
Sí, me he convertido a asciidoc en gran parte para el ToC y para vincular a los encabezados. Me cansé de esperar a que Markdown se pusiera al día.
Ciro Santilli 郝海东 冠状 病 六四 事件 法轮功
8

Si no está en condiciones de seguir con Markdown , puede hacer lo siguiente:

  • en GitHub / wiki : cambie Markdown a MediaWiki . Utilice la __TOC__sintaxis. Ver muestra .
  • en GitHub / repo : cambie Markdown a AsciiDoc . Utilice la :toc:sintaxis. Ver demo .

Sin embargo, al usar archivos Markdown en GitHub / repo , puede obtenerlo en las páginas de GitHub como en Wikipedia

  • cuando Jekyll está activado, genera páginas de GitHub usando Kramdown por defecto
  • Kramdown viene con Table Of Content. Utilice la {:toc}sintaxis. Vea la explicación .
Chetabahana
fuente
5

Código de Visual Studio

Si usa Visual Studio Code , existe una extensión fácil de usar llamada Markdown All in One que puede hacer el TOC para cualquier archivo .md en un instante.

ingrese la descripción de la imagen aquí

Simplemente abra Command Palette ( Ctrl-Shift-P) ->Markdown: Create Table of Contents

MD original Después de la inserción automática de TOC

¿La actualización automática estropea su TOC editado?

Como consejo adicional, es posible que desee desactivar las "actualizaciones automáticas de la tabla de contenido al guardar" utilizando

  "markdown.extension.toc.updateOnSave": false,

en la configuración de Visual Studio (Command Palette -> Preferences: Open Settings (JSON)).

np8
fuente
2

Debido al hecho de que github tiene su propia forma de generar atributos id = ".." en h1, h2, h3, etc ... encabezados en la versión html después de procesar Markdown (por ejemplo, Bitbucket usa un patrón poco diferente de títulos de encabezados lentos para id = "slug") es útil no reinventar la rueda y usar la biblioteca que realizó ingeniería inversa en este proceso.

Encontré una biblioteca bastante buena para esta tarea llamada markdown-toc .

Para mí parece la mejor solución porque siempre he instalado el nodo en mi máquina.

Sólo hay que ejecutar npx rebaja -i-toc file.md .

Y parece que es una de las herramientas más populares para esta tarea, al menos en el ecosistema node.js.

ls
cat <<EOF >> test.md | tee 
## Table of Contents

<!-- toc -->
- old toc 1
- old toc 2
- old toc 3
<!-- tocstop -->

## abc
This is a b c.

## xyz
This is x y z.
EOF
ls
cat test.md
npx markdown-toc -i test.md
cat test.md

salida:

ingrese la descripción de la imagen aquí

stopsopa
fuente