La primera vez que un README mío cruzó mil líneas, hice lo que todos hacen: me desplazé. Luego me desplazé un poco más. En algún lugar alrededor del cuarto pase buscando "Despliegue" sección, me di por vencido y comencé a escribir a mano una tabla de contenidos en la parte superior del archivo. Eso funcionó hasta que cambié el nombre de un encabezado, olvidé actualizar el enlace y envié un README donde "Configuración" no señaló nada. Un enlace roto en la página de su propia documentación es algo pequeño, pero es el tipo de cosa pequeña que le dice al lector que a nadie le importa la tienda.
Construyo [Toolz.dev](/, una colección de utilidades para desarrolladores basadas en navegador, y mantengo muchos Markdown: guías de herramientas, archivos README, especificaciones internas y los documentos que estás leyendo ahora mismo. Una tabla de contenidos que tengo que mantener a mano es una tabla de contenidos que eventualmente desaparecerá. Entonces construí el Generador TOC Markdown hacer la parte aburrida correctamente cada vez, y esta guía es todo lo que aprendí sobre los enlaces de anclaje mientras los construía.
TL;Dr: Una tabla de contenido de Markdown es una lista anidada de enlaces que saltan a encabezados en la misma página. Los enlaces funcionan porque cada encabezado obtiene una identificación de anclaje automática y el slug que asigna GitHub sigue una regla específica: baje el texto en minúsculas, elimine la puntuación que no sea guiones y convierta espacios en guiones. Pegue su Markdown en el generador, elija qué niveles de encabezado incluir y copie la lista. La herramienta calcula las representaciones exactas de slugs GitHub, incluido el
-1sufijo para títulos duplicados, por lo que nada se rompe al volver a pegarlo.
¿qué es una tabla de contenido de Markdown?
Una tabla de contenidos en Markdown no es una sintaxis especial. marcar con común no define tal construcción, ni tampoco GitHub Flavored Markdown. Es una lista ordinaria donde cada elemento es un enlace y cada enlace apunta a un ancla dentro del mismo documento. Cuando un renderizador de Markdown como GitHub convierte un encabezado en HTML, también le da a ese encabezado un id atributo. Un título escrito como ## Getting Started se vuelve aproximadamente <h2 id="getting-started">Getting Started</h2>. Una vez que esa identificación exista, un enlace escrito como [Getting Started](#getting-started) desplaza la página hasta él.
Entonces, una tabla de contenido es solo una colección de esos enlaces, sangrados para reflejar la jerarquía de encabezados:
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
Todo el truco vive en una palabra de ese ejemplo: el ancla. Si el ancla se equivoca, el enlace falla silenciosamente y no se desplaza a ninguna parte. Hazlo bien y el bloque de contenidos funciona en GitHub, en la mayoría de los generadores de sitios estáticos y dentro de plataformas de documentación que siguen la misma convención. La parte difícil no es escribir la lista. La parte difícil es predecir la identificación exacta que asignará cada renderizador, razón por la cual hacerlo a mano es un juego perdido en cualquier documento que cambie.
¿cómo se generan realmente los anclajes de encabezado?
GitHub's El algoritmo slug es determinista y vale la pena memorizarlo, porque una vez que lo conozcas puedes predecir cada ancla en la página. Los pasos, en orden, son: convertir el texto del encabezado a minúsculas, eliminar cualquier carácter que no sea una letra, un número, un espacio o un guión, y luego reemplazar cada espacio con un guión. Esa es toda la regla.
Las consecuencias son donde la gente tropieza. Considere un rumbo como ## Set Up & Config. Cajarea mai jos da set up & config. Quitar el signo comercial (pero dejar los espacios a su alrededor) da set up config con dos espacios donde el & solía ser. Convertir espacios en guiones produce set-up--config, con un guión doble. Ese guión doble parece un error, pero es exactamente lo que representa GitHub, por lo que es exactamente lo que su enlace necesita. Una herramienta que " limpia y quot; el guión doble produciría un enlace que no se resuelve.
Los títulos con mucha puntuación colapsan más de lo esperado. ## C++ Guide se convierte en c-guide, porque ambos signos más se eliminan y el espacio sobrante se convierte en un solo guión. ## What's New? se convierte en whats-new, porque el apóstrofe y el signo de interrogación desaparecen. Los emoji y la mayoría de los símbolos desaparecen por completo. El Generador TOC Markdown aplica este carácter de regla para el carácter, por lo que slug le muestra que es la identificación que GitHub creará, sin que haya conjeturas.
¿qué sucede cuando dos encabezados son iguales?
Los documentos repiten títulos. Un registro de cambios puede tener tres secciones, todas tituladas ### Fixed. Si cada uno de ellos produjera el slug fixed, sólo funcionaría el primer enlace. GitHub resuelve esto numerando los duplicados: el primero Fixed consigue fixed, el segundo consigue fixed-1, el tercero lo consigue fixed-2, y así sucesivamente en el orden de los documentos. El sufijo se agrega después de la base slug con un guión.
Esta es una de las razones más comunes por las que una tabla de contenidos escrita a mano no se sincroniza. Agregas una segunda sección con un nombre que ya usaste, el ancla se convierte silenciosamente -1, y su antiguo enlace ahora apunta al lugar equivocado o a ninguna parte. El generador rastrea cada slug que ha emitido y aplica el mismo sufijo numérico, por lo que los encabezados repetidos se vinculan a la ocurrencia correcta.
¿Qué tipo de títulos lee la herramienta?
Markdown tiene dos estilos de encabezado y un generador completo tiene que leer ambos. El común es ATX, donde una línea comienza del uno al seis # caracteres seguidos del texto del encabezado. El recuento de hashes es el nivel, entonces # es un H1 y ###### es un H6. El segundo estilo es Setext, donde una línea de texto está subrayada en la siguiente línea con signos iguales para un H1 o guiones para un H2:
Document Title
==============
A Section
---------
Ambos estilos producen encabezados con identificadores de anclaje, por lo que ambos pertenecen a una tabla de contenidos. La parte complicada con Setext es distinguir un encabezado real subrayado de una regla horizontal, porque una línea de guiones puede significar cualquiera de los dos. La regla que utiliza el generador es que un guión subrayado sólo cuenta como un encabezado cuando la línea directamente encima es un texto de párrafo ordinario, no una línea en blanco, un elemento de lista, una cita en bloque u otra construcción de bloque. Un --- sentarse solo con líneas en blanco a su alrededor es una ruptura temática y se ignora correctamente.
Hay una categoría más que manejar, y es la que arruina silenciosamente las herramientas ingenuas: encabezados dentro del código. Si su documento contiene un bloque de código cercado que muestra comandos de shell, algunas de esas líneas comenzarán con # como comentarios. Esos no son encabezados y nunca deben aparecer en el contenido. El generador rastrea bloques de código cercados (los delimitados por triples retrocesos o triples tildes) y omite cualquiera # línea dentro de ellos. Un comentario de shell como # install dependencies en un ejemplo permanece donde pertenece, en el ejemplo.
¿Cómo controlo la profundidad del índice?
Una tabla de contenidos que enumera todos los títulos hasta H6 no es una tabla de contenidos, es una segunda copia del documento. La mayoría de los README leen mejor cuando el contenido cubre solo H2 y H3, brindando a los lectores las secciones principales y sus hijos inmediatos sin ahogarlos en detalle. El generador te permite establecer un nivel mínimo y máximo, e incluye solo los encabezados que caen en ese rango.
El comportamiento sutil aquí es la sangría. Si incluye H2 a H4, el rumbo menos profundo que mantuvo es un H2, y debe quedar al ras contra el margen izquierdo en lugar de sangrar como si un H1 invisible estuviera encima de él. El generador mide la profundidad de anidamiento en relación con el rumbo menos profundo que realmente incluye, por lo que un bloque de contenido que comienza en H2 comienza sin sangría. Esta es la diferencia entre una lista que parece intencional y una que parece haber perdido su primera columna.
También puedes elegir el marcador de lista. Una lista desordenada usa una viñeta para cada entrada, que es la búsqueda convencional de un README. Una lista ordenada numera las entradas y el generador reinicia el recuento dentro de cada nivel de anidamiento para que un esquema numerado lea correctamente en lugar de contar directamente del uno al cincuenta. La sangría puede ser de dos espacios, cuatro espacios o una pestaña, dependiendo de lo que utilice el resto de su documento.
¿qué pasa con los títulos acentuados y no latinos?
No todos los títulos son en inglés sencillo y la regla slug tiene que hacer frente. GitHub mantiene letras de otros alfabetos en lugar de eliminarlas, por lo que es un título como ## Configuración mantiene sus caracteres acentuados y se vuelve configuración, y un título en cirílico o griego también conserva esas letras. Lo que se elimina son la puntuación y los símbolos, no las letras, independientemente del guión. El generador sigue el mismo principio al tratar cualquier letra o dígito Unicode como un carácter slug válido, por lo que un documento multilingüe produce anclajes que coinciden con lo que representa GitHub en lugar de una fila de enlaces vacíos.
Esto importa más de lo que parece a primera vista. Los equipos que escriben documentación en español, alemán o japonés a menudo descubren que las ingenuas herramientas slug destrozan sus encabezados en anclajes inutilizables, porque esas herramientas asumen ASCII. Si sus enlaces alguna vez no apuntaron a nada en un README traducido, es casi seguro que un slug que descartó silenciosamente las letras que no son ASCII es la razón. Generar el bloque de contenido con una herramienta compatible con Unicode elimina toda esa clase de enlace roto y significa que el mismo documento puede contener encabezados en más de un idioma sin que ninguno de ellos pierda sus anclajes.
¿cuándo debo utilizar un TOC generado versus uno automático?
Algunas plataformas crean una tabla de contenidos para usted. GitLab admite a [[_TOC_]] token, algunos wikis inyectan un cuadro de contenido automáticamente y los marcos de documentación como Docusaurus representan un esquema en la página de sus encabezados sin que usted escriba nada. Cuando trabajas dentro de uno de esos sistemas, utiliza la función incorporada. Se mantiene actualizado sin esfuerzo porque la plataforma lo regenera en cada renderizado.
El generador gana su lugar en cualquier otro lugar, y " en todos los demás lugares" es un lugar grande. Los README de GitHub no generan automáticamente un bloque de contenido, por lo que una página de inicio del repositorio necesita una lista real de Markdown comprometida en el archivo. Markdown que se convierte en otra cosa, se envía por correo electrónico, se pega en un problema o se representa mediante un visor mínimo necesita un bloque de contenido estático porque no hay un motor para construir uno sobre la marcha. La siguiente tabla establece dónde encaja cada enfoque.
| colocación | Mejor enfoque | porque |
|---|---|---|
| GitHub LÉAME | Lista estática generada | GitHub representa identificadores de encabezado pero no inserta automáticamente un TOC |
| Wiki o documentos de GitLab | [[_TOC_]] ficha |
Nativo, siempre actual |
| Página de Docusaurus / MkDocs | Esquema incorporado | Framework lo representa a partir de encabezados |
| Archivo de rebajas simple para exportación | Lista estática generada | No hay renderizador para crear uno a la vista |
| Emitir o extraer descripción de la solicitud | Lista estática generada | Los anclajes funcionan, pero nada genera automáticamente la lista |
La regla general: si lo que muestra su Markdown puede crear el contenido por sí solo, déjelo. Si su Markdown puede leerse en algún lugar que no pueda, genere la lista y confíela. Cuando estás convirtiendo entre formatos, el Convertidor de reducción a HTML y el Convertidor de HTML a Markdown combínelo naturalmente con un bloque de contenido generado, porque los anclajes sobreviven al viaje de ida y vuelta.
¿cómo se ajusta esto al resto de un flujo de trabajo de Markdown?
Una tabla de contenido es una pieza para mantener legibles los documentos largos y funciona mejor junto con algunos hábitos. Mantenga estable el texto de su encabezado una vez que haya publicado enlaces, porque cambiar el nombre de un encabezado cambia su slug y rompe todos los enlaces que lo apuntan. Cuando cambia de nombre, regenere el contenido en lugar de editar el enlace que recuerda, ya que un cambio de nombre a menudo desplaza la numeración de sufijos duplicados más abajo en el archivo.
El contenido estructurado se beneficia de otras herramientas de la misma familia. Cuando un documento se apoya en datos tabulares, el Generador de mesa de descuento crea tablas de tuberías correctamente alineadas que una tabla escrita a mano casi nunca acierta. Cuando hereda HTML desordenado que necesita convertirse en Markdown limpio, o Markdown limpio que necesita convertirse en HTML, los convertidores manejan la traducción preservando la estructura del encabezado. Y si está auditando un documento para determinar la longitud o el equilibrio de palabras clave, el Contador de palabras le proporciona los números sin pegar su borrador en nada basado en la nube.
Todo se ejecuta en el navegador, lo cual importa más de lo que parece. README a menudo contiene nombres de funciones inéditos, URL internas o detalles del cliente, y nada de eso debe cargarse en un servidor de terceros solo para crear una lista de enlaces. El generador analiza su Markdown con JavaScript del lado del cliente, por lo que el documento nunca sale de su máquina. Si lo que piensa es privacidad en las herramientas del desarrollador, el artículo sobre Privacidad de datos y herramientas en línea cubre por qué el procesamiento local es el valor predeterminado correcto y el Kit de herramientas para desarrolladores web resume el resto de los servicios públicos a los que accedo a diario.
Un ejemplo trabajado rápidamente
Supongamos que tiene este documento:
# Payment Service
## Getting Started
### Requirements
### Local Setup
## API Reference
### Authentication
### Errors
## Deployment
Establezca el rango de H2 a H3, elija una lista con viñetas y deje los enlaces de anclaje activados. El generador produce:
- [Getting Started](#getting-started)
- [Requirements](#requirements)
- [Local Setup](#local-setup)
- [API Reference](#api-reference)
- [Authentication](#authentication)
- [Errors](#errors)
- [Deployment](#deployment)
El título H1 está excluido porque se encuentra por encima del rango, las secciones H2 están al ras a la izquierda y sus hijos H3 tienen una sangría de un nivel. Pegue ese bloque justo debajo del título en su README y cada entrada saltará a su sección en GitHub. Ese es todo el trabajo, realizado en el tiempo que lleva leer esta oración, y sigue siendo correcto porque una máquina calculó el slugs en lugar de usted.
Preguntas frecuentes
¿cómo funciona una tabla de contenidos de Markdown?
Una tabla de contenido de Markdown es una lista de enlaces que apuntan a anclajes de encabezado dentro de la misma página. A cada encabezado de un documento de Markdown se le asigna una identificación automática y un enlace escrito como Sección salta hacia él. Esta herramienta lee sus títulos, crea los anclajes correspondientes y reúne la lista anidada para usted.
¿cómo se generan los enlaces ancla?
Los anclajes siguen la regla slug de GitHub: el texto del encabezado está en minúsculas, se elimina la puntuación distinta de los guiones y los espacios se convierten en guiones. " Configurar & Config" se convierte en el id set-up-config. Cuando dos encabezados producen el mismo slug, el segundo obtiene un sufijo -1, el tercero -2, y así sucesivamente, coincidiendo con la forma en que GitHub los representa.
¿funciona con archivos README de GitHub?
Sí. El algoritmo slug refleja el que utiliza GitHub para representar identificadores de encabezado, por lo que los enlaces de la tabla de contenido se resuelven correctamente dentro de un README en github.com. Pegue su README, elija sus niveles de encabezado y elimine la lista generada debajo del título.
¿Puedo elegir qué niveles de encabezado aparecen?
Sí. Establezca un nivel mínimo y máximo, por ejemplo H2 a H4, y solo se incluyen títulos en ese rango. La profundidad de anidación se mide en relación con el rumbo incluido más poco profundo, por lo que el contorno nunca comienza con una gran sangría vacía.
¿se incluyen encabezados dentro de bloques de código?
No. Las líneas que comienzan con # dentro de un bloque de código cercado (delimitadas por triple backticks o triple tildes) se tratan como código, no como encabezados, por lo que los fragmentos de ejemplo y los comentarios de shell nunca aparecen en la tabla de contenido.
¿cuál es la diferencia entre un TOC ordenado y un TOC desordenado?
Una tabla de contenido desordenada utiliza marcadores de viñetas, como un guión, para cada entrada, mientras que una ordenada utiliza números que se incrementan dentro de cada nivel de anidamiento. Elija ordenado cuando los lectores se beneficien de un contorno numerado y desordenado para un bloque de contenido más ligero y convencional.
¿la herramienta admite encabezados Setext?
Sí. Lee los encabezados ATX que comienzan con # y los encabezados Setext, donde una línea de texto está subrayada con signos iguales para H1 o guiones para H2. Ambos estilos se convierten en enlaces de anclaje de la misma manera.
¿el generador Markdown TOC es gratuito y privado?
Sí. Es completamente gratuito, sin registro ni límites. Todo el análisis se realiza en su navegador mediante JavaScript del lado del cliente, por lo que el Markdown que pegue nunca sale de su dispositivo y la herramienta sigue funcionando sin conexión una vez que se ha cargado la página.
