Los encabezados son la columna vertebral de cualquier documento Markdown. Definen la estructura, permiten la navegación, afectan la accesibilidad e influyen SEO. Esta guía abarca todo lo relacionado con Markdown rótulos sintaxis, reglas de jerarquía, diferencias de plataformas y mejores prácticas.
Syntax de encabezado
Markdown los encabezados utilizan el # símbolo (estilo ATX). El número de # los caracteres determinan el nivel de la rúbrica:
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6También hay el estilo Setext (sólo H1 y H2):
Heading 1
=========
Heading 2
---------Modelo ATX (#) es preferible es más explícito y funciona para los seis niveles.
Lo que significa cada uno de los niveles
| Nivel de trabajo | HTML Etiquetado | El objetivo |
|---|---|---|
| H1 | <h1> | Título de la página o del documento |
| H2 | <h2> | Sección principal |
| H3 | <h3> | Subsección dentro de H2 |
| H4 | <h4> | Subsección dentro de H3 |
| H5 | <h5> | Raramente utilizado en la práctica |
| H6 | <h6> | Casi nunca se necesita |
La mayoría de los documentos usan sólo H1H3. H4H6 suele indicar que la estructura del documento es demasiado profunda.
H1: Una por página
Un encabezado H1 debe aparecer exactamente una vez por documento Markdown. Representa el título del documento o el tema principal de la página.
Qué bueno .
# How to Convert Word to MarkdownEvitar los siguientes:
# Section One
...
# Section Two ← Don't use multiple H1sLos motores de búsqueda y las herramientas de accesibilidad esperan un solo H1 por página. Múltiples H1 confunden ambos.
Reglas de jerarquía de los títulos
Siempre avanzaremos en dirección a la secuencia. No se salten los niveles:
Correcto:
# Document Title
## Section
### Subsection
#### DetailIncorrecto:
# Document Title
#### Jumped to H4 ← Skips H2 and H3La omisión de los niveles de encabezado viola el esquema del documento y no cumple con las directrices de accesibilidad de la WCAG.
Convertir los encabezados de Word a Markdown
Cuando se convierte un documento Word con WordToMD, Words está integrado en los estilos de encabezado mapa directamente:
| Estil Word | Markdown Producción |
|---|---|
| Sección 1 | # Heading |
| Sección 2 | ## Heading |
| Sección 3 | ### Heading |
| Normal + en negrita | **Bold text** (Ningún encabezado) |
El problema más común: los escritores aumentan manualmente el tamaño de la fuente en lugar de aplicar el estilo de encabezado. Esto crea texto que parece un encabezado en Word pero se convierte en texto en negrita en Markdown. No se puede hacer. Word a Markdown Guía de formato para cómo arreglar esto.
Identificadores de encabezado y enlaces de anclaje
La mayoría de los procesadores Markdown generan automáticamente IDs a partir del texto del encabezado:
## Getting StartedGeneradores: <h2 id="getting-started">Getting Started</h2>
Se puede enlazar a ella:
See the [Getting Started section](#getting-started).Reglas para los identificadores generados automáticamente:
- Todos los caracteres en minúsculas
- Sustituir los espacios por guiones
- Descargar los caracteres especiales excepto los guiones
Ejemplos:
## API Reference→#api-reference## What's New?→#whats-new## Step 1: Install→#step-1-install
Cuadros de contenido
Para documentos largos, generar un TOC utilizando enlaces de anclaje de encabezado:
## Table of Contents
- [Installation](#installation)
- [Configuration](#configuration)
- [Basic Settings](#basic-settings)
- [Advanced Options](#advanced-options)
- [Usage](#usage)
- [FAQ](#faq)GitHub genera automáticamente un TOC en la esquina superior izquierda de cualquier archivo Markdown con encabezados.
SEO Consideraciones
Para Markdown utilizado en sitios estáticos (Jekyll, Hugo, Astro) y publicado en la web:
- H1 = título de la página Incluya su palabra clave principal. Una por página.
- H2s = secciones principales Incluir palabras clave secundarias de forma natural
- H3s = subsecciones Temas más específicos
- Mantenga los títulos descriptivos Cómo instalar dependencias beats Instalación
- Los encabezados son indexados por los motores de búsqueda hacen que sean escaneables
No se puede hacer. Word al generador de sitio estático para la publicación de documentos Markdown en la web.
Accesiblidad
Los lectores de pantalla utilizan la jerarquía de encabezados para ayudar a los usuarios a navegar. Las directrices:
- No salte los niveles de dirección (H1 → H3 sin H2)
- No use encabezados solo para el formato visual (use en negrita o CSS en su lugar)
- Hacer que el texto del encabezado tenga sentido evitar la sección 1, la parte A
- Mantenga los títulos concisos pero descriptivos
Rendición de encabezados por plataforma
| Plataforma de trabajo | H1 y H6 | Identificación automática | Auto-TOC |
|---|---|---|---|
| GitHub | ✅ | ✅ | ✅ (a través del botón) |
| Obsidian | ✅ | ✅ | A través del complemento |
| GitBook | ✅ | ✅ | ✅ (cuadro lateral) |
| Notion | Sólo H1-H3 | ❌ | ❌ |
| Vista previa del código VS | ✅ | ✅ | ❌ |
| ¿Qué es eso? | ✅ | ✅ | ✅ |
Notion solo admite tres niveles de encabezado (llamados encabezados 1, 2 y 3 en su editor, que se asignan a H1H3).
Errores comunes
Olvidando el espacio después #
#Not a heading ← Missing space
# This is correctEl espacio entre # y se requiere el texto del encabezado en CommonMark.
El uso de encabezados para el estilo, no para la estructura
El uso de ### hacer que el texto sea ligeramente más pequeño sin que sea una subsección real rompe la estructura del documento. Utilice texto con estilo o clases CSS en su lugar.
Anidación excesiva Si necesita H5 y H6, considere si el contenido debe dividirse en páginas separadas.
FAQ
¿Cuál es la diferencia entre los estilos de encabezado ATX y Setext?
Utilizaciones de ATX # personajes. Se subraya el uso del Setexto (=== para el H1, --- para el H2). Se prefiere el ATX porque es inequívoco y funciona para el H1H6.
¿Puedo tener varios H2s? Sí, ese es el punto. H2 define las secciones principales, y un documento generalmente tiene varias.
¿El salto de los niveles de dirección afectará a SEO? Afecta la accesibilidad más que SEO directamente, pero una estructura semántica limpia es una señal positiva. Los motores de búsqueda prefieren el contenido bien estructurado.
Mi documento convertido tiene todos los encabezados en el mismo nivel. ¿Qué fue lo que salió mal? El documento Word usó formato manual en lugar de estilos de encabezado. No se puede hacer. Word a Markdown Guía de formato para la solución.
Conclusión
Markdown los encabezados son sencillos en sintaxis pero importantes en impacto. Utilice H1 una vez como título del documento, H2 para las secciones principales y H3 para las subsecciones. Mantenga la jerarquía limpia, no salte los niveles y escriba el texto del encabezado descriptivo. Al convertir documentos Word con WordToMD, asegúrese de que la fuente utiliza los estilos de encabezado integrados de Word para una conversión limpia.