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.

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