Respuesta rápida: la sintaxis marca la jerarquía; el texto sigue las reglas del español
En Markdown y HTML, los signos o etiquetas indican que una línea es un encabezado, pero no deciden cómo se capitaliza su contenido. En español, lo normal es escribir con mayúscula inicial la primera palabra y los nombres propios: Cómo configurar el entorno de desarrollo, no Cómo Configurar El Entorno De Desarrollo.
La jerarquía debe ser semántica: un título principal, secciones y subsecciones ordenadas. No elijas h3 porque se vea más pequeño ni añadas almohadillas para simular tamaño. El nivel comunica estructura a navegadores, índices y tecnologías de asistencia.
Tabla rápida de decisión
| Elemento | Ejemplo recomendable | Qué controla |
|---|---|---|
| Markdown | ## Configurar la cuenta | ## crea el nivel; el texto sigue el español. |
| HTML | <h2>Configurar la cuenta</h2> | h2 expresa una subsección. |
| Título visible | Configurar la cuenta | Mayúscula inicial y nombres propios. |
| Nombre técnico | API de Google Maps | Conserva siglas, marcas e identificadores. |
| CSS visual | text-transform: uppercase | Modifica la apariencia, no la jerarquía ni el texto fuente. |
Encabezados en Markdown
En la sintaxis ATX de CommonMark, entre una y seis almohadillas iniciales representan niveles de encabezado. La secuencia debe ir seguida de un espacio o del final de línea. Por ejemplo, ### Límites conocidos crea un encabezado de tercer nivel; las almohadillas no forman parte del título visible.
La caja del texto no cambia por usar Markdown. Escribí # Guía de instalación y no conviertas cada palabra a mayúscula por influencia del inglés. Conservá nombres propios, siglas y fragmentos técnicos: ## Integración con GitHub Actions, ## Respuesta de la API.
Encabezados en HTML
Los elementos h1 a h6 representan niveles de encabezado. El estándar HTML relaciona el número con la profundidad de la sección: h1 para el nivel principal, h2 para una subsección, h3 para una subsección de esta y así sucesivamente.
Para una página independiente, un h1 descriptivo y una progresión clara de h2 y h3 constituyen una convención robusta. W3C recomienda anidar los rangos y evitar saltos confusos cuando sea posible. Volver de h3 a h2 es correcto al cerrar una subsección; pasar de h2 a h4 sin una razón estructural suele ser difícil de interpretar.
h1 Guía de despliegueh2 Preparar el proyectoh3 Variables de entornoh2 Publicar
h1 Guía de despliegueh4 Preparar el proyectoh2 Variables de entorno
Capitalización española frente al estilo inglés
Los encabezados de documentación no dejan de ser títulos en español. Por regla general, solo la primera palabra y los nombres propios reciben mayúscula: Configurar una cuenta de Google, Errores frecuentes de JavaScript, Publicar el sitio en Cloudflare Pages.
Un equipo puede adoptar una convención editorial distinta, pero debe documentarla y aplicarla con coherencia. No presentes una capitalización de palabras significativas como la norma general del español. Si el material se traduce, cada idioma necesita su propio criterio.
El nivel importa más que el tamaño visual
Los encabezados permiten recorrer la estructura de una página. W3C explica que navegadores y tecnologías de asistencia pueden utilizarlos para la navegación interna. Un texto grande dentro de un div no sustituye esa semántica; del mismo modo, un h2 no debe elegirse solo porque su diseño parezca adecuado.
Usá CSS para controlar tipografía, espacio y color, y HTML para expresar la organización. Un encabezado debe describir el contenido que sigue: Requisitos del sistema resulta más informativo que Importante o Más información.
text-transform no corrige el texto
CSS puede mostrar un encabezado en mayúsculas, minúsculas o con la primera letra de cada palabra transformada. Esa presentación no reescribe el contenido fuente ni añade criterio lingüístico. Además, text-transform: capitalize capitaliza palabras y no reproduce la regla española de títulos.
Guardá el texto con la caja editorial correcta y reservá la transformación visual para decisiones de diseño justificadas. Así, el contenido seguirá siendo claro al copiarse, indexarse, leerse sin estilos o reutilizarse en otros formatos.
Código, comandos y nombres exactos dentro de un encabezado
Un título puede contener elementos que no deben normalizarse: npm install, snake_case, iOS, eBay, una URL o el nombre de una opción de interfaz. Mantené la grafía oficial y usá code cuando el fragmento deba reproducirse literalmente.
- Correcto: Instalar paquetes con
npm. - Correcto: Convertir nombres a
snake_case. - Correcto: Configurar el botón Guardar como.
- Riesgoso: INSTALAR PAQUETES CON NPM, si la mayúscula se usa solo para llamar la atención.
Flujo práctico para revisar una documentación
- Identificá el título principal y las secciones reales.
- Asigná niveles por jerarquía, no por apariencia.
- Escribí los encabezados con estilo español.
- Conservá marcas, siglas, comandos e identificadores.
- Comprobá que cada encabezado describa el bloque siguiente.
- Revisá la estructura sin CSS o mediante el panel de accesibilidad.
- Aplicá estilos visuales después de fijar el texto y la semántica.
Consejo: si recibiste una documentación con todos los encabezados en mayúsculas, convertí una copia y revisá uno por uno los nombres propios y los tokens técnicos.
Probar formato de títuloEncabezados dentro de tablas y formularios
Una jerarquía de documentación puede incluir tablas y formularios, pero sus rótulos no son nuevos niveles de encabezado. Usá th para las cabeceras de datos y label para identificar controles. La guía sobre tablas, formularios y hojas de cálculo desarrolla la capitalización y la relación accesible entre rótulo y contenido.
El estilo oración sigue siendo una base segura: Fecha de publicación, Nombre del proyecto y Estado de la revisión.
Errores frecuentes
- Capitalizar cada palabra porque el contenido está en una web.
- Saltar niveles para obtener un tamaño de fuente concreto.
- Usar negrita grande en lugar de un encabezado semántico.
- Aplicar
text-transform: capitalizecomo corrector ortográfico. - Modificar comandos, marcas o identificadores dentro del título.
- Repetir el nombre del sitio en todos los encabezados.
- Escribir rótulos vagos que no permiten anticipar el contenido.
Títulos de diapositivas y documentación proyectada
Una diapositiva también necesita jerarquía, pero no utiliza niveles h1–h6 como una página HTML. El programa debe reconocer un título único por diapositiva y conservar un orden de lectura lógico para que la navegación no dependa solo de la posición visual.
La guía de presentaciones y diapositivas aplica el estilo oración a títulos, subtítulos, viñetas, gráficos y notas, y explica cómo revisar la versión exportada.
Fuentes consultadas
Preguntas frecuentes
¿En español se escribe con mayúscula cada palabra de un encabezado?
No como regla general. Se escribe con mayúscula inicial la primera palabra y se conservan las mayúsculas de nombres propios, siglas y denominaciones que las requieran.
¿La almohadilla de Markdown forma parte del título?
No. Una secuencia de una a seis almohadillas indica el nivel del encabezado; el texto visible comienza después del espacio.
¿Las etiquetas h1, h2 y h3 deben escribirse en mayúsculas?
No. Los nombres de los elementos suelen escribirse en minúscula en el código, y el contenido del encabezado sigue las reglas editoriales del idioma.
¿text-transform: capitalize crea títulos correctos en español?
No. La propiedad cambia la presentación y capitaliza palabras de forma mecánica; no aplica la regla española ni reconoce nombres propios o identificadores técnicos.