Cómo crear un índice Markdown para un README de GitHub
Crea un índice con enlaces para un README de GitHub. Copia un ejemplo con subapartados, revisa títulos repetidos y corrige enlaces tras editar.
En esta página
01Copia un README completo con índice02Obtén el ancla real del encabezadoPon una lista con viñetas al principio del README. Un enlace como [Quick start](#quick-start) lleva al encabezado ## Quick start. Los corchetes contienen el texto visible. Lo que va después de la almohadilla identifica el encabezado de destino.
GitHub también crea un esquema a partir de los encabezados del archivo Markdown renderizado. Sirve para recorrer el README de otro proyecto. Si quieres que las secciones más consultadas se vean al abrir el tuyo, escribe un índice al principio del archivo. Guía de archivos README de GitHub
La plantilla incluye una entrada secundaria y dos encabezados con el mismo nombre. Copia el bloque en un archivo Markdown y prueba los cuatro enlaces.
# Field Notes
## Contents
- [Quick start](#quick-start)
- [Import a notebook](#import-a-notebook)
- [Examples for writers](#examples)
- [Examples for reviewers](#examples-1)
## Quick start
Open a notebook and add your first entry.
### Import a notebook
Choose an existing folder of Markdown notes.
## Examples
Writers can group entries by trip.
## Examples
Reviewers can scan entries by date.
Import a notebook lleva sangría debajo de Quick start, igual que el H3 depende del H2 en el cuerpo del documento. Las dos secciones Examples conservan su nombre. El texto de cada enlace explica a quién va dirigido el ejemplo, y los fragmentos llevan a destinos distintos.
Para un encabezado sencillo, GitHub convierte las letras a minúsculas, sustituye los espacios por guiones y quita marcas de formato y signos como el de interrogación. Cuando un ancla se repite, añade un sufijo numérico. En la plantilla, los destinos son #examples y #examples-1. Reglas de enlaces a secciones de GitHub
Para comprobar un encabezado con puntuación, formato en línea o caracteres fuera de ASCII, abre el archivo renderizado en GitHub. Pasa el cursor por el título, pulsa el icono de enlace y copia el fragmento de la barra de direcciones. Si enlazas desde otro archivo Markdown de la misma carpeta, antepón el nombre del archivo, como en [Quick start](README.md#quick-start).
| Qué ocurre | Qué revisar |
|---|---|
| El enlace se queda al principio del archivo | Comprueba la almohadilla y compara el fragmento con el ancla del encabezado renderizado. |
| Las dos entradas abren la primera sección Examples | Copia el fragmento del segundo encabezado. En la plantilla termina en -1. |
| El salto dejó de funcionar tras un cambio | Verifica el ancla después de renombrar o mover un encabezado y actualiza los enlaces antiguos. |
| La entrada secundaria queda al nivel de la principal | Aplica sangría a la viñeta. El nivel del encabezado y la sangría de la lista se controlan por separado. |
| Funciona en una plataforma y falla en otra | Copia el ancla de la plataforma donde se leerá el archivo. |
Tras editar el README, pulsa cada entrada del índice y comprueba el destino, sobre todo si cambió el orden de títulos duplicados. Empieza por las secciones que ayudan a actuar, como instalación, uso y resolución de problemas. Añade subapartados cuando permitan saltarse una sección larga.
El PNG se descargó del editor de Markdown2Image con la misma fuente. Muestra los niveles de encabezado y la lista con sangría. Si lo usas en una diapositiva, pon al lado el enlace del README para que los lectores abran el archivo y salten a la sección. Previsualizar la plantilla en Markdown2Image