Generador de Tabla de Contenido Markdown

Generador de Tabla de Contenido Markdown

Analiza cualquier documento Markdown y emite una Tabla de Contenido navegable — formateada exactamente como esperan GitHub, GitLab o tu generador de sitios estáticos. Configura qué niveles incluir, el estilo de bullet, indentación y cómo generar los slugs. La salida es Markdown plano para pegar al inicio del README, o deja que la herramienta lo inyecte en el placeholder [TOC] / <!-- toc -->. Todo el procesamiento ocurre en tu navegador; el documento nunca sale del dispositivo.

¿Qué es una Tabla de Contenido Markdown y dónde se usa?

Una TOC en Markdown es una lista de enlaces a los headings dentro del mismo documento. Cuando se renderiza en GitHub, GitLab, GitBook, MkDocs, Docusaurus, Jekyll, Hugo, Notion, Obsidian, o cualquier visor que añada anchors a los headings, la TOC se convierte en un mapa navegable de la página.

Los lectores miran la TOC para encontrar lo que necesitan sin hacer scroll. Los mantenedores la usan como herramienta de revisión estructural — un vistazo revela si la jerarquía del documento es razonable.

Lugares habituales para incrustar una TOC:

- Al inicio de un README.md largo, después de la descripción.
- Encima de la sección API en documentación técnica.
- En un ADR (architecture decision record) cuando hay muchas alternativas.
- En notas de reunión o design docs con muchas secciones.

¿Cómo detecta el parser los headings?

El parser maneja los dos estilos de heading que admite Markdown:

1. ATX: 1–6 # al inicio de la línea, espacio, texto. Los # finales opcionales se eliminan.

# Título H1
## Sección H2
### Subsección H3

2. Setext: el texto en una línea y otra línea de = (H1) o - (H2) debajo. El estilo setext es más antiguo y menos común, pero válido en Markdown.

Cuando 'Ignorar bloques de código' está activado (por defecto), el parser rastrea bloques con cerca (``` y ~~~) y bloques indentados (4 espacios), y omite las líneas que parecen headings dentro. Esto evita que 'parece código Python: # comentario' se interprete como heading.

Texto tras # sin espacio (`#hashtag`) no es heading, según CommonMark. Headings con más de 3 espacios de indent tampoco se reconocen como ATX — son texto de párrafo.

¿Diferencia entre estilos de slug?

Distintos renderizadores convierten el texto del heading en ID de anchor de forma ligeramente diferente. Elige el estilo del destino:

- GitHub: minúsculas, espacios a guiones, puntuación eliminada, letras Unicode conservadas. 'Introduction!' → introduction; 'API V2.0' → api-v20. Es el estándar de facto en GitHub, gists, GitLab, Notion y muchos generadores estáticos (Eleventy, Astro).

- GitLab: similar a GitHub pero permite underscores. 'two_words and three' → two_words-and-three.

- CommonMark / Pandoc: ASCII estricto, quita dígitos y puntuación iniciales. '1. Background' → background. Usar para Pandoc o renderizadores CommonMark estrictos.

- Texto plano (sin enlaces): solo el texto sin anchor. Útil cuando el destino no soporta anchors (algunas apps de chat, email en texto plano).

¿Cómo funciona la deduplicación de anchors?

Cuando dos headings tienen el mismo texto, los slugs chocan y solo funciona el primero. La herramienta rastrea todos los slugs emitidos en la TOC actual y añade `-1`, `-2`, etc. a los duplicados:

## Ejemplos
### Setup → setup
## Otro Tema
### Setup → setup-1
### Setup → setup-2

Coincide con el comportamiento real de GitHub para headings repetidos. GitLab usa el mismo patrón. Pandoc descarta el duplicado salvo que actives el mismo esquema con `pandoc --slugify`.

Si cambias el origen y regeneras, los sufijos se asignan en el nuevo orden. Guarda el archivo con la TOC insertada si quieres URLs estables entre ejecuciones.

¿Por qué la herramienta a veces salta el H1?

El Nivel Mínimo por defecto es H2. Es la convención más común en Markdown: el primer H1 es el título del documento y la TOC describe las secciones dentro de ese título.

Repetirías el título si incluyeras H1 en la TOC, así que la mayoría de proyectos empieza la TOC en H2.

Si tu documento usa H1 para secciones (sin título superior), pon Nivel Mínimo en H1.

El Nivel Máximo controla la profundidad. H2–H3 da una vista plana. H2–H4 añade el sub-nivel. H2–H6 da jerarquía completa — útil para docs técnicas largas pero puede saturar.

¿Qué hace 'Insertar en origen'?

Tres comportamientos según el origen:

1. Si el documento tiene el placeholder [TOC], lo sustituye. Convención de Pandoc / Python-Markdown / WordPress.
2. Si contiene el comentario HTML <!-- toc -->, lo sustituye. Convención de doctoc / markdown-toc-cli.
3. Si no, inserta la TOC justo después del primer H1 (o al inicio si no hay), separada por líneas en blanco.

Es ejecución manual — la herramienta no sigue el documento ni actualiza la TOC automáticamente al editar headings. Para mantenimiento automático, usa doctoc (paquete npm) o un pre-commit hook que ejecute esta lógica al guardar.

La TOC insertada es Markdown plano — sin wrapper HTML salvo que actives 'Envolver con heading', que añade una línea `## Tabla de Contenido` encima.

¿Funciona con headings que no son en inglés?

Sí. Los generadores de slug conservan letras y dígitos Unicode — 'Câu hỏi thường gặp', 'Préférences', 'Configuración', '常见问题' producen slugs válidos compatibles con GitHub.

GitHub mantiene los caracteres Unicode en el slug; el fragmento URL los contendrá codificados como bytes %XX al seguir el enlace. Los navegadores lo manejan transparentemente.

Si cambias a CommonMark, las reglas son más estrictas — letras Unicode fuera de [a-z0-9] se eliminan. Para documentos multilingües en GitHub, GitLab o Notion, prefiere GitHub o GitLab.

El texto bidireccional (árabe, hebreo) funciona tanto en el texto visible como en el slug. La TOC se lee de izquierda a derecha en el origen, pero se renderiza correcta en navegadores que manejan bidi.

¿Qué reporta el Chequeo de Anclas?

El chequeo es un linter previo a publicar que se ejecuta en cada tecla y detecta tres problemas que doctoc y markdown-toc nunca reportan:

1. Anclas duplicadas: dos headings que generan el mismo slug. El segundo recibe un sufijo de colisión -1, -2, así que su enlace NO es el que adivinarías por el texto — un #setup copiado caerá en la sección equivocada. El chequeo muestra el slug base y el ancla real con sufijo a la que se resolvió.

2. Niveles de heading saltados: un H2 que salta directo a un H4 sin H3 en medio. Esto rompe el esquema del documento del que dependen los lectores de pantalla y la navegación de los generadores de sitios (un asunto de WCAG 1.3.1) y hace engañosa la indentación de la TOC.

3. Headings vacíos: una línea `## ` sin texto. Producen un ancla vacía y una entrada en blanco en la TOC.

Cuando todo está limpio obtienes un visto verde. Corrige los problemas en tu origen y la TOC y el reporte se actualizan juntos. Esta es justo la validación que un mantenedor de docs quiere antes de hacer commit de un README.

¿Por qué no funciona mi enlace de ancla en GitHub?

Los culpables habituales, todos los cuales esta herramienta maneja correctamente:

- Underscores: GitHub MANTIENE los underscores en las anclas, así que un heading `hello_world` se convierte en #hello_world, no en #helloworld. Selecciona el estilo GitHub y la herramienta los conserva.

- Símbolos eliminados entre palabras: GitHub quita la puntuación pero NO colapsa los espacios que quedan. 'foo & bar' se vuelve #foo--bar (dos guiones), porque el '&' se borra y cada espacio vecino pasa a ser su propio guion. Un enlace a #foo-bar dará 404. La herramienta reproduce este comportamiento exacto de gh-slugger.

- Mayúsculas: las anclas se ponen en minúsculas. #Introduction no coincide; usa #introduction.

- Los emojis y casi toda la puntuación se eliminan; el texto circundante sí se convierte en slug.

- Los headings duplicados reciben un sufijo -1/-2 (ver el Chequeo de Anclas), así que el segundo 'Setup' es #setup-1, no #setup.

Si un enlace aún falla, pega aquí el heading, elige el estilo GitHub y copia el ancla que genera la herramienta — coincide con lo que renderiza GitHub.

¿Cómo se compara con doctoc o markdown-toc?

doctoc y markdown-toc son CLIs que editan tus ficheros Markdown in situ. Geniales para repos — corre en un pre-commit hook o CI y tendrás TOCs actualizadas en control de versiones.

Esta página es lo contrario: una versión en navegador, sin instalación, de la misma funcionalidad. Trade-offs:

- Uso puntual rápido, sin instalar Node/npm, sin permisos.
- Varios estilos de slug en una UI; doctoc solo emite estilo GitHub.
- 'Insertar en origen' es una escritura única en el textarea — luego copias/guardas el archivo.
- Todo el procesamiento es local — el contenido no se sube.
- Para mantenimiento continuo del repo, doctoc o markdown-toc siguen siendo la respuesta; para generación manual ocasional, esto es más rápido.

El parser maneja bloques con cerca, headings setext y Unicode de forma comparable a esas CLIs.

Características Principales

• Parsea headings Markdown ATX (#) y Setext (=== / ---)
• Rango de niveles configurable (H1–H6 min, H2–H6 max)
• Estilos GitHub, GitLab, CommonMark + modo texto plano
• De-duplicación de slugs con sufijo -1, -2 (coincide con GitHub)
• Chequeo de anclas: detecta anclas duplicadas, niveles saltados y headings vacíos antes de publicar
• Unicode: conserva diacríticos, alfabetos no latinos, sin emojis en salida
• Salta headings dentro de bloques con cerca (``` / ~~~) e indentados
• Elimina bold / italic / inline-code / sintaxis de link en etiquetas TOC
• Estilos de bullet: -, *, + o numerado (1.)
• Tamaño de indent: 2, 4 o Tab
• Inserta en lugar de [TOC] o <!-- toc -->, o tras el primer H1
• Vista previa muestra la TOC renderizada como lista clicable
• Copia la TOC al portapapeles
• Markdown de muestra para probar al instante
• 100% en el cliente — tu documento no sale del navegador
• JavaScript puro — funciona offline tras la primera carga