Saltar al contenido
Volver al Blog
miércoles, 18 de noviembre de 2026

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.

Cómo crear un índice Markdown para un README de GitHub

Pon 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

Copia un README completo con índice

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.

Obtén el ancla real del encabezado

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).

Corrige los enlaces que llevan al lugar equivocado

Qué ocurreQué revisar
El enlace se queda al principio del archivoComprueba la almohadilla y compara el fragmento con el ancla del encabezado renderizado.
Las dos entradas abren la primera sección ExamplesCopia el fragmento del segundo encabezado. En la plantilla termina en -1.
El salto dejó de funcionar tras un cambioVerifica el ancla después de renombrar o mover un encabezado y actualiza los enlaces antiguos.
La entrada secundaria queda al nivel de la principalAplica 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 otraCopia 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.

Comparte la estructura como imagen

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

README renderizado con índice, entrada secundaria y dos secciones Examples

Abrir el PNG original