TOC automático en github-con sabor-markdown

¿Es posible generar una tabla de contenido automática usando Github Flavored Markdown ?

Creé dos opciones para generar un toc para github-flavored-markdown:

DocToc Command Line Tool ( fuente ) requiere node.js

npm install doctoc

npx doctoc . agregar tabla de contenido a todos los archivos de rebajas en el actual y todos los subdirectorios.

DocToc WebApp

Si primero desea probarlo en línea, vaya al sitio de doctoc , pegue el enlace de la página de rebajas y generará una tabla de contenido que puede insertar en la parte superior de su archivo de rebajas.

Github Wikis y Anclas

Como Matthew Flaschen señaló en los comentarios a continuación, para sus páginas wiki, GitHub no generó previamente los anclajes de los que doctocdepende.

ACTUALIZACIÓN: Sin embargo, solucionaron este problema .

Parece que GitHub Pages (que básicamente es un contenedor para Jekyll) usa kramdown , que implementa todo Maruku , y por lo tanto tiene soporte para una tabla de contenido generada automáticamente a través de un tocatributo:

* auto-gen TOC:
{:toc}

La primera línea simplemente comienza una lista desordenada y en realidad se descarta.

Esto da como resultado un conjunto anidado de listas desordenadas, utilizando los encabezados del documento.

Nota: esto debería funcionar para las páginas de GitHub, no para GitHub Flavored Markdown (GFM) como se usa en comentarios o páginas wiki. AFAIK no existe una solución para eso.

Si edita archivos Markdown con Vim, puede probar este complemento vim-markdown-toc .

El uso es simple, simplemente mueva el cursor al lugar donde desea agregar la Tabla de contenido y ejecute :GenTocGFM, ¡listo!

Capturas de pantalla

caracteristicas:

1. Generar toc para archivos Markdown. (Soporta GitHub con sabor Markdown y Redcarpet)

2. Actualizar toc existente

3. Actualización automática toc al guardar.

No es automático, pero usa expresiones regulares de Notepad ++:

Reemplace todo primero por el segundo (elimina todas las líneas que no tienen encabezados)

^##(#?)(#?)(.*?)$(.|\r|\n)*?(?=^##|\z)
-\1\2 [\3](#\3)\n

Luego (convierte los encabezados III en espacios)

-##
        -

Luego (convierte los encabezados II en espacios)

-#
    -

Luego (elimine los caracteres no utilizados al principio y al final del título del enlace)

\[ *((?:(?![ .:#!\?;]*\])[^#])*)[ #:!\?;]*\]
[\1]

Luego (convierta los últimos tokens en minúsculas y guiones en lugar de espacios)

\]([^ \r\n]*) ([^\r\n ]*)
]\L\1-\2

Elimine las libras finales no utilizadas y los guiones iniciales:

(?:()[-:;!\?#]+$|(\]#)-)
\1\2

Eliminar caracteres inútiles en enlaces:

(\].*?)(?:\(|\))
\1

Y finalmente agregue paréntesis alrededor de los enlaces finales:

\](?!\()(.*?)$
\]\(\1\)

¡Y voilá! Incluso puede poner esto en una macro global si lo repite el tiempo suficiente.

No es posible, excepto por las soluciones propuestas.

Me propuse extensión Kramdown TOC y otras posibilidades para [email protected] y Steven! Ragnarök respondió con lo habitual:

Gracias por la sugerencia y enlaces. Lo agregaré a nuestra lista de solicitudes de funciones internas para que el equipo las vea.

Vamos a votar esta pregunta hasta que suceda.

Otra solución es usar Asciidoc en lugar de Markdown, que representa TOC . Me he movido a este enfoque para mi contenido hoy en día.

Github Flavored Markdown usa RedCarpet como su motor de Markdown. Del repositorio de RedCarpet :

: with_toc_data - agrega anclajes HTML a cada encabezado en el HTML de salida, para permitir el enlace a cada sección.

Parece que necesitarías llegar al nivel de renderizador para establecer esta bandera, lo que obviamente no es posible en Github. Sin embargo, la última actualización de Github Pages, parece que el anclaje automático está activado para los encabezados, creando encabezados enlazables. No es exactamente lo que desea, pero podría ayudarlo a crear un TOC para su documento un poco más fácil (aunque manualmente).

Una forma muy conveniente de lograr una tabla de contenido para un archivo mardown cuando se trabaja con Visual Studio Code es la extensión Markdown-TOC .

Puede agregar un toc a los archivos de rebajas existentes e incluso mantener el toc actualizado al guardar.

Es posible generar una página web automáticamente con http://documentup.com/ desde el README.mdarchivo. No está creando una TOC, pero para muchos podría resolver la razón por la que desea crear una TOC.

Otra alternativa a Documentup es Flatdoc: http://ricostacruz.com/flatdoc/

Gitdown es un preprocesador de rebajas para Github.

Usando Gitdown puedes:

• Generar tabla de contenido
• Encuentra URLs muertos e identificadores de fragmentos
• Incluir variables
• Incluir archivos
• Obtener tamaño de archivo
• Generar insignias
• Fecha de impresion
• Imprimir información sobre el repositorio en sí

Gitdown simplifica las tareas comunes asociadas con el mantenimiento de una página de documentación para un repositorio de GitHub.

Usarlo es sencillo:

var Gitdown = require('gitdown');

Gitdown
    // Gitdown flavored markdown.
    .read('.gitdown/README.md')
    // GitHub compatible markdown.
    .write('README.md');

Puede tenerlo como un script separado o como parte de la rutina del script de compilación (como Gulp ).

Use coryfklein / doctoc , un tenedor de thlorenz / doctoc que no agrega " generado con DocToc " a cada tabla de contenido.

npm install -g coryfklein/doctoc

Mi colega @schmiedc y yo hemos creado un script de GreaseMonkey que instala un nuevo TOCbotón a la izquierda del h1botón que utiliza la excelente markdown-jsbiblioteca para agregar / actualizar una tabla de contenido.

La ventaja sobre soluciones como doctoc es que se integra en el editor wiki de GitHub y no necesita que los usuarios trabajen en su línea de comandos (y requiere que los usuarios instalen herramientas como node.js ). En Chrome, funciona arrastrando y soltando en la página Extensiones, en Firefox necesitará instalar la extensión GreaseMonkey.

Funcionará con Markdown simple (es decir, no maneja los bloques de código correctamente, ya que es una extensión de GitHub para Markdown). Contribuciones bienvenidas.

Esta no es una respuesta directa a esta pregunta, ya que muchas personas han proporcionado soluciones alternativas. No creo que generar un TOC haya sido oficialmente respaldado por Github hasta la fecha. Si desea que GitHub presente una tabla de contenido en sus páginas de vista previa de GFM automáticamente, participe en la discusión sobre el tema oficial de solicitud de características .

Actualmente no es posible usar la sintaxis de rebajas (vea la discusión en curso en GitHub ), sin embargo, puede usar algunas herramientas externas como:

• Tabla en línea del generador de contenido ( raychenon / play-table-of-contents )
• arthurhammer / github-toc : extensión del navegador que agrega una tabla de contenido a los repositorios de GitHub

Alternativamente, use AsciiDocen su lugar (por ejemplo README.adoc), por ejemplo

:toc: macro
:toc-title:
:toclevels: 99
# Title

## A

### A2

## B

### B2

como se sugiere en este comentario . Mira la demo aquí .

Para el Atom Texteditor de Github, consulte este impresionante complemento (o "paquete" en Atom-lingo), que genera "TOC (tabla de contenido) de titulares de archivos analizados" :

markdown-toc

Una vez instalado como paquete Atom, puede usar el acceso directo ctrl-alt-cpara insertar una tabla de contenido basada en su estructura markdown-doc en la posición actual del cursor ...

Capturas de pantalla

Atom Keybindings

markdown-toc le ofrece las siguientes combinaciones de teclas predeterminadas para controlar el complemento en Atom:

• ctrl-alt-c => crear TOC en la posición del cursor
• ctrl-alt-u => actualizar TOC
• ctrl-alt-r => eliminar TOC

Características del complemento (del archivo README del proyecto)

• Enlace automático a través de etiquetas de anclaje, p. Ej. # A 1→#a-1
• Control de profundidad [1-6] con depthFrom:1ydepthTo:6
• Habilitar o deshabilitar enlaces con withLinks:1
• Actualizar lista al guardar con updateOnSave:1
• Utilice la lista ordenada (1. ..., 2. ...) con orderedList:0

Aquí hay un script de shell que creé hoy para esto. Puede que tenga que ajustarlo para sus necesidades, pero debería ser un buen punto de partida.

cat README.md \
    | sed -e '/```/ r pf' -e '/```/,/```/d' \
    | grep "^#" \
    | tail -n +2 \
    | tr -d '`' \
    | sed 's/# \([a-zA-Z0-9`. -]\+\)/- [\1](#\L\1)/' \
    | awk -F'(' '{for(i=2;i<=NF;i++)if(i==2)gsub(" ","-",$i);}1' OFS='(' \
    | sed 's/^####/      /' \
    | sed 's/^###/    /' \
    | sed 's/^##/  /' \
    | sed 's/^#//'

Si alguien conoce una mejor manera de hacer esos # reemplazos finales, agregue un comentario. Intenté varias cosas y no estaba contento con ninguna, así que simplemente lo forcé.

Ahora hay una Acción GitHub logrando esto:

https://github.com/marketplace/actions/toc-generator

1. Especifique la ubicación de TOC (opción), por ejemplo README.md

<!-- START doctoc -->
<!-- END doctoc -->

2. Configurar el flujo de trabajo, por ejemplo .github/workflows/toc.yml

on: push
name: TOC Generator
jobs:
  generateTOC:
    name: TOC Generator
    runs-on: ubuntu-latest
    steps:
      - uses: technote-space/toc-generator@v2

La mayoría de las otras respuestas requieren instalar alguna herramienta. Encontré una solución en línea rápida y fácil https://imthenachoman.github.io/nGitHubTOC .

Para cualquier entrada de descuento, genera una tabla de salida de contenido. Puede especificar el nivel de encabezado mínimo y máximo.

El código fuente se encuentra en https://github.com/imthenachoman/nGitHubTOC