Generador de tabla de contenidos Markdown: navegación automática para tus docs

Todo desarrollador ha pasado por esto: estás escribiendo un README largo y en algún punto te das cuenta de que necesitas una tabla de contenidos. Así que pasas veinte minutos creándola manualmente — convirtiendo cada encabezado a minúsculas, reemplazando espacios por guiones, eliminando caracteres especiales, construyendo los enlaces uno a uno. Luego cambia un encabezado y la mitad de los enlaces se rompen.

Es uno de esos problemas pequeños pero genuinamente molestos que tiene una solución completamente mecánica. El algoritmo de generación de IDs de ancla para GitHub-Flavored Markdown es determinista y está bien documentado. No hay razón para hacerlo a mano.

El Generador de tabla de contenidos Markdown automatiza todo el proceso. Pega tu Markdown, obtén una tabla de contenidos correctamente indentada con los enlaces correctos, lista para insertar directamente en el documento.

Por qué las tablas de contenidos importan más de lo que parece

Una tabla de contenidos no es decorativa. En un documento largo, cumple una función de navegación real: los lectores la escanean primero para entender qué cubre el documento, luego saltan directamente a la sección que les interesa. Sin ella, desplazan la página manualmente o se rinden.

Para archivos README en GitHub, esto es especialmente cierto. Cuando un desarrollador llega por primera vez a un repositorio que está evaluando, escanea el README. Si el README es largo y no tiene tabla de contenidos, construir el modelo mental del proyecto cuesta más. Una tabla de contenidos clara comunica la estructura de inmediato.

La documentación técnica tiene la misma dinámica. Referencias API, guías de arquitectura, docs de incorporación — los lectores casi nunca los leen linealmente. Buscan algo específico. La tabla de contenidos es su mapa.

Cómo funciona el algoritmo de anclas

GitHub genera los IDs de ancla a partir del texto de los encabezados mediante un proceso simple:

1. Eliminar todas las etiquetas HTML
2. Convertir todo el texto a minúsculas
3. Eliminar toda la puntuación excepto guiones y espacios
4. Reemplazar espacios por guiones
5. Deduplicación: si un texto de encabezado aparece más de una vez, se añade -1, -2, etc.

Así, ## Referencia API (v2) se convierte en #referencia-api-v2. ## Primeros pasos se convierte en #primeros-pasos.

Para el español con tildes y eñes: GitHub preserva estos caracteres en los IDs de ancla. Un encabezado como ## Configuración avanzada da #configuración-avanzada. Funciona correctamente, aunque la URL puede parecer extraña con la codificación de porcentaje.

La diferencia entre GitHub y GitLab

GitHub y GitLab siguen el mismo algoritmo básico pero difieren ligeramente en ciertos caracteres. Para la mayoría de la documentación en español, los resultados son idénticos. Las diferencias aparecen con:

• Paréntesis y algunos signos de puntuación: GitHub los elimina, GitLab los puede tratar diferente
• Emoji en los encabezados: el comportamiento es inconsistente en ambas plataformas

El consejo práctico si publicas en ambas plataformas: mantén los textos de los encabezados simples — palabras ordinarias, poca puntuación.

Ejemplo práctico

Esta es una estructura típica de README:

# Mi librería

## Instalación

### macOS

### Linux

## Inicio rápido

## Referencia API

### Opciones de configuración

### Métodos

## Contribuir

## Licencia

El generador produce:

## Tabla de contenidos

- [Instalación](#instalación)
  - [macOS](#macos)
  - [Linux](#linux)
- [Inicio rápido](#inicio-rápido)
- [Referencia API](#referencia-api)
  - [Opciones de configuración](#opciones-de-configuración)
  - [Métodos](#métodos)
- [Contribuir](#contribuir)
- [Licencia](#licencia)

Hay que notar algunos detalles. Primero, # Mi librería en H1 se excluye de la tabla de contenidos — H1 es el título del documento, no un destino de navegación. Segundo, la jerarquía se refleja correctamente: H2 al nivel superior, H3 con una indentación.

Casos especiales y limitaciones reales

Mejor ser directo sobre algunas situaciones.

Emoji en los encabezados — Popular en archivos README: ## 🚀 Primeros pasos. El comportamiento de las anclas varía según el renderer. Si tus encabezados contienen emoji, verifica los enlaces generados directamente en la plataforma donde publicarás.

Spans de código en los encabezados — ## La función `render()` — los backticks se eliminan, dando #la-función-render. Generalmente es el resultado deseado.

Paréntesis y caracteres especiales — ## Referencia API (v2) — los paréntesis se eliminan, dando #referencia-api-v2. Funciona bien, pero si tienes varias secciones con nombres similares, el ancla puede tener una forma inesperada.

Integración en el flujo de trabajo

El flujo de trabajo típico es sencillo:

1. Escribe primero el documento, sin preocuparte por la tabla de contenidos
2. Cuando la estructura esté estabilizada, pega el Markdown en el Generador de tabla de contenidos
3. Copia la tabla de contenidos generada
4. Pégala al principio del documento, después del párrafo de introducción

Mantener la sincronización

La limitación principal es que el generador no actualiza automáticamente la tabla de contenidos cuando modificas el documento. Si cambias o añades encabezados, necesitas regenerarla y reemplazar la anterior.

Para documentos pequeños, no es un problema. Para proyectos de documentación que cambian frecuentemente, hay opciones de automatización:

• doctoc (paquete npm): actualiza la tabla de contenidos en el lugar, ideal como hook pre-commit
• Extensiones de VS Code: varias extensiones actualizan la tabla de contenidos automáticamente al guardar
• GitHub Actions: workflow configurable para ejecutar doctoc en cada push

El Generador de tabla de contenidos es ideal para generación puntual o cuando quieres verificar exactamente cómo quedará el resultado antes de integrarlo.

Herramientas complementarias

Si trabajas mucho con Markdown, vale la pena conocer estas otras herramientas disponibles en este sitio.

La herramienta Vista previa de Markdown renderiza cualquier documento Markdown en tiempo real, para confirmar visualmente cómo se verán los encabezados y la tabla de contenidos antes de copiarlos al repositorio.

El conversor Markdown a HTML es útil cuando necesitas la salida HTML real — por ejemplo, al pegar en un CMS que acepta HTML pero no Markdown en bruto.

El Generador de tablas Markdown crea la sintaxis de tabla separada por pipes, notoriamente tediosa de escribir a mano. Si tu documentación incluye tablas de datos, ahorra mucho tiempo.

Consejos prácticos de uso real

Comienza con una jerarquía de encabezados limpia. Si tu documento mezcla H2 y H3 sin una estructura clara, la tabla de contenidos generada reflejará esa confusión. El proceso de generación a menudo revela problemas estructurales que antes eran invisibles.

Las estructuras planas están bien. Un documento con solo encabezados H2 produce una tabla de contenidos simple sin anidamiento — eso es a menudo exactamente lo correcto. No añadas H3 innecesarios solo para que la tabla de contenidos parezca más elaborada.

Considera el patrón de lectura de tu audiencia. Para documentación de referencia API que los desarrolladores consultan repetidamente, una tabla de contenidos completa con anidamiento completo es útil. Para un README que un nuevo usuario leerá de arriba a abajo la primera vez, a menudo basta con una tabla de contenidos más corta con solo las secciones principales.

Automatizar las partes mecánicas — generación de IDs de ancla, formato de enlaces, sangría — te permite concentrarte en el contenido real. Para eso existe esta herramienta.

Prueba el Generador de tabla de contenidos Markdown en tu próximo README o archivo de documentación.