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

Si miras aquí: http://en.wikipedia.org/wiki/Stack_Overflow

Notarás que hay una pequeña sección de "Contenido", si haces clic en uno de los enlaces, te enviará a una sección específica de la página.

¿Cómo hago esto en la wiki de GitHub? ¿Con Markdown o lo que sea que usen?

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.

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.

Dado que github no se puede usar TOCdirectamente, tenemos otras alternativas.

Puede generar TOC automáticamente a través de la herramienta en línea:

Generar tabla de contenido TOC desde GitHub Markdown o Wiki Online

oa través de la herramienta local:

github-markdown-toc

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.

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:

• Úselo en su AsciiDoclugar según la sugerencia de este comentario . Por ejemplo:

  :toc: macro
  :toc-title:
  :toclevels: 99
  # Title
  
  toc::[]
  
  ## A
  
  ### A2
  
  ## B
  
  ### B2
  

  Consulte el ejemplo en littlebits/react-popover( README.adoc) .

• Línea Tabla de contenido Generador ( raychenon / play-tabla-de-contenido )

• arthurhammer / github-toc : extensión del navegador que agrega una tabla de contenido a los repositorios de GitHub

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 .

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.

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

¿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)).

Puede elegir el modo de edición "MediaWiki" que generará un toc para los encabezados, por ejemplo

== First ==

== Second ==

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: