Qué es un encabezado y por qué importa su estructura

Los encabezados son los títulos y subtítulos que dividen un documento en secciones. En Markdown se escriben con almohadillas (# Título, ## Subtítulo) o con la sintaxis Setext (una línea de texto subrayada con === o ---); en HTML son las etiquetas <h1> a <h6>. Su nivel (del 1 al 6) define una jerarquía: el H1 es el título del documento, los H2 son las secciones principales, los H3 son subsecciones, y así sucesivamente.

Esa jerarquía no es decorativa. La usan:

• Los lectores de pantalla, que permiten a las personas con discapacidad visual saltar de encabezado en encabezado para navegar por la página.
• Los buscadores como Bing y Google, que interpretan la estructura de encabezados para entender de qué trata cada parte del contenido.
• Los generadores de índices (GitHub, GitLab, wikis, generadores de sitios estáticos), que construyen la tabla de contenidos y los enlaces de anclaje a partir de los encabezados.
• Los sistemas de documentación, que numeran las secciones automáticamente.

Reconocimiento de encabezados

La herramienta detecta los tres estilos habituales:

Con la opción activada, los encabezados que estén dentro de un bloque de código delimitado por ``` se ignoran, porque ahí una almohadilla suele ser un comentario, no un título. También puedes pedir que se elimine el formato en línea del texto del encabezado (negrita, código, enlaces) para quedarte con el texto limpio.

Formatos de salida

• Lista indentada por nivel: cada encabezado con una sangría proporcional a su nivel. Ideal para ver la estructura de un vistazo.
• Lista plana: solo el texto de los encabezados, uno por línea.
• Lista numerada jerárquica: numeración del tipo 1, 1.1, 1.2, 2, como en un documento técnico.
• Árbol ASCII: con conectores ├─ y └─, como la salida del comando tree.
• Markdown con anclajes: - [Texto](#slug), listo para usar como índice.
• CSV: columnas nivel, texto, línea, slug, para abrir en una hoja de cálculo.
• JSON: un array de objetos, para procesar el resultado con un script.

Slugs de anclaje: GitHub, GitLab y simple

Cada plataforma genera de forma distinta el identificador (slug) que convierte un encabezado en un destino enlazable:

• GitHub: pasa a minúsculas, elimina la puntuación, sustituye los espacios por guiones y conserva los caracteres Unicode (tildes, eñes).
• GitLab: similar, pero además translitera los acentos y colapsa los guiones repetidos.
• Simple: solo letras a–z y dígitos, todo lo demás se convierte en un guion. Es el formato más portable.

Cuando dos encabezados tienen el mismo texto, sus slugs colisionarían; la herramienta añade un sufijo -1, -2 al segundo y siguientes, igual que hace GitHub.

Auditoría de jerarquía

Esta es la función que distingue al extractor de un simple listado. Con la validación activada, la herramienta revisa el documento entero (no solo el rango de niveles filtrado) y avisa de:

1. Cero o varios H1: un documento debe tener exactamente un título de nivel 1. Cero H1 deja el contenido sin título principal; varios confunden a los buscadores y a los lectores de pantalla.
2. Niveles saltados: pasar de un H2 a un H4 sin un H3 intermedio rompe la jerarquía. Los lectores de pantalla lo anuncian como un error de estructura.
3. Encabezados vacíos: una almohadilla sin texto detrás.
4. Títulos duplicados: dos secciones con el mismo texto generan anclajes que colisionan, de modo que un enlace del índice llevará siempre al primero.

Ejemplo

Entrada:

# Guía

# Segunda guía

### Salto directo a H3

## Configuración

## Configuración

Avisos: «2 encabezados H1: debería haber solo uno», «Salto de nivel: de H1 a H3», «Título duplicado: Configuración; los anclajes colisionan».

Casos de uso

• Revisar un README antes de subirlo, para comprobar que la estructura es correcta y que el índice funcionará.
• Auditoría SEO on-page: ver de un vistazo la jerarquía de encabezados de un artículo y detectar los H1 múltiples o los saltos.
• Migración de contenido: extraer el esquema de un documento para reconstruirlo en otro sistema.
• Documentación técnica: generar una lista numerada de secciones para un anexo o un control de versiones.
• Accesibilidad: verificar que un HTML cumple el criterio de encabezados anidados correctamente.

Herramientas relacionadas en porcentaje.net

• Generador de Tabla de Contenidos desde Texto: crea el índice con enlaces para pegar en el documento.
• Extractor de Metadatos de Texto: front matter, entidades y estadísticas del documento.
• Contador de Líneas de Texto: mide la extensión del documento.
• Convertidor de BBCode a HTML: para contenido de foros.
• Eliminar Código HTML de un Texto: deja solo el contenido textual.

Preguntas Frecuentes (FAQ)