Generador de índice Markdown
Pega tu README o cualquier archivo Markdown y obtén una tabla de contenidos anidada y enlazada a partir de sus encabezados. Las anclas siguen las reglas de GitHub o GitLab (incluidos los duplicados), así que cada enlace salta a la sección correcta, y puedes insertar el índice directamente en el documento.
Última actualización:
Cómo usar Generador de índice Markdown
- Pega tu Markdown o abre un archivo .md. Se carga un README de ejemplo para que veas el resultado enseguida.
- Elige los niveles de encabezado que quieres incluir. Muchos README omiten el título H1 y listan las secciones H2 y H3.
- Elige las reglas de anclas según dónde se mostrará el archivo (GitHub o GitLab) y el estilo de viñeta y sangría.
- Copia el índice y pégalo debajo de tu título, o usa Insertar en el documento para añadirlo entre los marcadores <!-- toc -->.
- Vuelve a generarlo cuando quieras: pega el archivo actualizado e inserta de nuevo; el índice anterior entre los marcadores se reemplaza.
Cómo se generan las anclas de los encabezados
Tanto GitHub como GitLab convierten el texto visible de un encabezado en un id que puedes enlazar con #ancla. Los pasos son:
- Se toma solo el texto renderizado:
**negrita**,[enlaces](url)y el HTML en línea se reducen a su texto, las imágenes desaparecen y`código`conserva su contenido. - Se pasa a minúsculas.
- Se eliminan la puntuación y los símbolos. Se conservan las letras (incluidas las acentuadas y las no latinas), los dígitos, los espacios, los guiones y los guiones bajos.
- Cada espacio se reemplaza por un guion. GitLab además une los guiones repetidos en uno solo.
- Si el ancla ya existe antes en el documento, se añade
-1,-2, … en orden.
| Encabezado | Ancla de GitHub | Ancla de GitLab |
|---|---|---|
## Getting Started | #getting-started | #getting-started |
## What's New in v2.0? | #whats-new-in-v20 | #whats-new-in-v20 |
## Options & Flags | #options--flags | #options-flags |
## Config file (`.acmerc`) | #config-file-acmerc | #config-file-acmerc |
## snake_case_names | #snake_case_names | #snake_case_names |
## Usage (segunda vez) | #usage-1 | #usage-1 |
## Café Menü | #café-menü | #café-menü |
Consejos para una buena tabla de contenidos en un README
- Omite el H1. El título ya está arriba de la página, así que la mayoría de los índices empiezan en H2. Ir más allá de H3 suele hacer la lista demasiado larga para recorrerla.
- No te saltes niveles. Pasar de H2 directamente a H4 rompe el esquema; el generador igualmente anida la entrada bajo su padre más cercano y te avisa.
- Los índices numerados necesitan más sangría. En CommonMark un elemento anidado debe alinearse con el texto que va después de
1., así que las listas numeradas llevan al menos 3 espacios de sangría aunque elijas 2. - Usa los marcadores.
<!-- toc -->y<!-- tocstop -->son los mismos marcadores que usa la popular CLI markdown-toc, así que el bloque generado también se puede actualizar con esa herramienta en un hook de pre-commit. - Cambiar el nombre de un encabezado cambia su ancla y rompe los enlaces desde otras páginas. Vuelve a generar el índice después de editar y revisa los enlaces externos.
¿Estás escribiendo el README? Empieza con el Generador de README y da formato a los datos con el Generador de tablas Markdown.
Preguntas frecuentes
¿Cómo crea GitHub las anclas de los encabezados?
GitHub toma el texto del encabezado, lo pasa a minúsculas, elimina la puntuación y los símbolos (se conservan letras, números, espacios, guiones y guiones bajos) y reemplaza cada espacio por un guion. Así, ## What's New? se convierte en #whats-new. Antes se elimina el formato, como la negrita o los enlaces, y solo se usa el texto visible.
¿Qué pasa con los encabezados duplicados?
El primer encabezado conserva el ancla simple y los siguientes reciben -1, -2, etc. Dos secciones llamadas Usage se convierten en #usage y #usage-1. El generador numera los duplicados en el orden del documento, exactamente como GitHub y GitLab.
¿Las anclas de GitLab son distintas de las de GitHub?
Son casi iguales, con una diferencia práctica: GitLab une los guiones seguidos en uno solo, así que A - B se convierte en #a-b en GitLab pero en #a---b en GitHub. Elige la opción GitLab si tu README está alojado allí.
¿Por qué faltan algunos encabezados en mi índice?
Las líneas que empiezan con # dentro de bloques de código delimitados (``` o ~~~) son código, no encabezados, así que se omiten. Los encabezados fuera del rango de profundidad elegido se dejan fuera, y en CommonMark un # debe ir seguido de un espacio para contar como encabezado.
¿Cómo mantengo actualizada la tabla de contenidos?
Inserta el índice con los marcadores <!-- toc --> y <!-- tocstop -->. La próxima vez, pega el archivo editado y vuelve a hacer clic en Insertar en el documento: todo lo que hay entre los marcadores se reemplaza por un índice nuevo. Los marcadores son comentarios HTML, así que no se ven en GitHub.
¿GitHub genera una tabla de contenidos automáticamente?
GitHub muestra un menú de esquema para los archivos README y Markdown en el visor de archivos, pero no añade un índice a la página renderizada. Escribir el índice en el archivo hace que sea visible en la página, en npm, en los editores y en los documentos exportados.
¿Se prueban todas las herramientas de FreeToolCabin para comprobar su calidad y precisión?
Sí. Cada herramienta del sitio pasa pruebas automáticas en navegadores reales para comprobar que el resultado es correcto y que no hay errores. Si encuentras un fallo o tienes una sugerencia, escríbenos a [email protected] y lo revisaremos.