Reglas de escritura de elementos: cuándo usar cada bloque

Cada página del SEO playbook depende de una distinción: un contenido tiene un propósito, mientras que su nivel de encabezado y apariencia visual son solo presentación. Estas reglas de escritura de elementos convierten esa distinción en un contrato de producción. Síguelas antes de aplicar cualquier componente, convertir un artículo entre sistemas de publicación o cambiar un elemento que ya aparece en páginas publicadas.

Resumen rápido

• Revisa la biblioteca de elementos por propósito antes que por nombre. Si el propósito de un elemento coincide con el trabajo que realiza una sección, ese elemento es obligatorio.
• Usa Markdown simple solo después de confirmar que ningún elemento tipado representa el propósito del pasaje. El texto libre es un recurso, no un valor predeterminado.
• Escribe el artículo completo primero como texto plano. Aplica los elementos en una pasada estructural separada de arriba a abajo para que la composición y el marcado no compitan por la atención.
• Trata la directiva de Markdown como el contenido canónico creado por el autor. Los renderizadores de Hugo y WordPress mapean los mismos campos y cuerpo en salida nativa de cada plataforma.
• Mantén las páginas publicadas existentes con el significado con el que fueron revisadas. Un cambio de definición que rompe la compatibilidad crea una nueva versión y una migración explícita; nunca reinterpreta silenciosamente el contenido antiguo.

La regla de precedencia que rige

La biblioteca debe revisarse por lo que hace un pasaje, no por cómo el escritor decidió llamarlo. Los nombres varían: un escritor puede titular una sección «¿Qué es la tasa de abandono?», otro «La tasa de abandono explicada» y un tercero «Una definición práctica». Su propósito es idéntico, por lo que los tres se mapean al mismo elemento de definición.

Esta precedencia existe porque el texto libre y un elemento tipado pueden verse idénticos en pantalla mientras se comportan de forma completamente diferente río abajo. Un encabezado con estilo seguido de un párrafo puede parecerse a una caja de definición en el navegador, pero no tiene identidad de componente. No puede producir de forma confiable la salida estructurada de la definición, exponer sus campos a otro renderizador, retener su semántica durante la migración ni ser encontrado por una verificación de calidad que pregunte si la página contiene una definición. El elemento tipado se mapea a un componente y una forma de datos conocida; el texto libre visualmente similar no se mapea a nada.

Por lo tanto, la regla es estricta:

Antes de escribir o aprobar cualquier encabezado o bloque de contenido, identifica su propósito. Si ese propósito coincide con una definición de elemento, usa el elemento. La similitud visual, un H2 existente o la capacidad de expresar las mismas palabras en un párrafo no hacen que el texto libre sea equivalente.

La precedencia es semántica, no visual. Una página aún puede contener encabezados ordinarios dentro o alrededor de un elemento cuando su definición lo permite, pero el encabezado nunca reemplaza el tipo de elemento.

Texto libre frente a un elemento tipado

Usa esta ruta de decisión hasta que el diagrama compartido esté disponible:

1. Expresa el trabajo del pasaje en un verbo. Ejemplos: definir, advertir, resumir, comparar, probar, instruir o invitar a la acción. Esto evita que el texto del encabezado disimule el propósito subyacente.
2. Busca en la biblioteca por ese propósito y sus sinónimos. Un escritor que busca solo el encabezado literal «¿Qué es X?» puede pasar por alto un elemento de definición cuya página se llama «Caja de definición».
3. Usa el elemento coincidente cuando exista. No compares apariencias ni preguntes si Markdown podría imitar el diseño; el comportamiento registrado es el factor decisivo.
4. Usa texto libre cuando ningún propósito coincida. Esto es correcto para explicación conectiva, argumentación, análisis, contexto narrativo y transiciones que pertenecen al flujo principal del artículo y no requieren un comportamiento de componente distinto.
5. Registra una brecha repetida. Si el mismo propósito no coincidente aparece en varias páginas, propón un elemento de la biblioteca en lugar de inventar una directiva o tratamiento CSS único en un artículo.

El Markdown simple es genuinamente correcto cuando las palabras forman el razonamiento continuo del artículo y no necesitan una etiqueta independiente, un contrato de datos, una interacción o una ruta de reutilización. Por ejemplo, dos párrafos que explican por qué una recomendación se sigue de la evidencia precedente son prosa normal. Un conjunto compacto de conclusiones al inicio no es prosa normal simplemente porque se pueda escribir como viñetas; tiene el propósito reconocido de un elemento de resumen o conclusiones.

Confusiones comunes que causan marcado incorrecto

Estos casos se enumeran explícitamente porque pasan fácilmente una revisión visual. El error se vuelve visible solo cuando otro renderizador, validador, índice de búsqueda o consumidor de salida estructurada recibe la página.

La distinción entre conclusiones clave y un resumen rápido es especialmente importante. Usa conclusiones cuando los elementos sean resultados que el lector debe recordar, lo que significa que a menudo solo pueden escribirse después de que el artículo exista. Usa un resumen cuando los elementos orienten al lector sobre el alcance o la secuencia antes de leer. Elige según esa tarea editorial, incluso si el tema actual hace que ambos componentes se vean similares.

Sintaxis de directivas y atributos

La forma canónica de Markdown utiliza una directiva de bloque nombrada. Los atributos siguen al nombre de la directiva entre llaves:

:::nombre-del-elemento{clave=valor clave2="valor con espacios" .clase}
Contenido del cuerpo
:::

Los atributos existen para transportar propiedades pequeñas y estables que afectan el significado del elemento o su presentación compatible. Mantenerlos legibles por máquina evita que los escritores oculten configuración en la prosa. Usa clave=valor para un valor sin espacios y clave2="valor con espacios" cuando haya espacios. Un valor de atributo sin comillas no puede contener espacios. Un punto inicial agrega una clase compatible, como en .compact; no es un lugar para inventar estilos específicos de la página.

Las claves de atributos están en minúsculas y usan la ortografía exacta definida en la página del elemento. Los valores booleanos y enumerados también siguen el contrato de esa página. No crees un atributo porque un renderizador lo tolere: un atributo no declarado no tiene garantía multiplataforma.

Los cierres ::: pertenecen al elemento externo. Mantenlos en sus propias líneas para que un analizador pueda distinguir el cuerpo del siguiente párrafo. Los ejemplos de código que muestran directivas deben permanecer dentro de bloques de código delimitados, como en esta página, para que Hugo no los interprete como contenido.

Mapeo predeterminado del cuerpo

La mayoría de los elementos necesitan un título breve y un cuerpo más largo. Exigir que los autores repitan estos como atributos haría que el texto largo sea difícil de editar y fácil de escapar incorrectamente, por lo que el cuerpo proporciona el mapeo predeterminado:

:::ejemplo
## Un encabezado concreto

El resto del cuerpo puede contener párrafos, listas, enlaces y otro contenido permitido por la definición del elemento.
:::

A menos que una página de elemento anule explícitamente la regla, el primer encabezado en el cuerpo se mapea a title, y todo lo que sigue a ese encabezado se mapea a content. El marcador de encabezado expresa la jerarquía fuente para los editores; el campo mapeado permite que cada plataforma renderice el nivel de encabezado semántico apropiado en contexto.

Solo el primer encabezado del cuerpo recibe este tratamiento especial. Los encabezados posteriores permanecen como parte de content. Si el cuerpo no tiene encabezado, title está ausente; eso es válido solo cuando la definición del elemento marca su título como opcional. Si un elemento define ranuras nombradas o un mapeo diferente, su propia página tiene prioridad sobre este valor predeterminado porque el renderizador debe saber exactamente dónde pertenece cada fragmento.

Elementos anidados

Algunos elementos contienen una lista repetible cuyas entradas necesitan atributos y un cuerpo, como pasos con identificadores, tarjetas con etiquetas o elementos de lista de verificación con un estado inicial. Aplanar esas entradas en una sola lista de Markdown perdería sus campos individuales, por lo que los elementos anidados usan una directiva de elemento explícita:

:::elemento-padre{variante=compacto}
::item{clave=valor}
### Título del primer elemento

Explicación del primer elemento.
::
::item{clave2="valor con espacios"}
### Título del segundo elemento

Explicación del segundo elemento.
::
:::

El contrato es ::item{clave=valor} … ::: dos puntos abren cada elemento, el nombre singular es item, y dos puntos lo cierran. El padre mantiene su cierre de tres puntos. Esta diferencia visual importa porque hace que el anidamiento no sea ambiguo sin depender de la indentación, que se daña fácilmente con copiar y pegar.

Cada elemento aplica el mismo mapeo predeterminado del cuerpo a menos que la página del elemento padre indique lo contrario: su primer encabezado se convierte en el title de ese elemento, y el resto se convierte en su content. Coloca los atributos en el elemento cuando describan solo ese elemento; colócalos en el padre cuando afecten a la colección como un todo.

Enlaces, imágenes y botones en línea

La fuente portable necesita rutas predecibles. Una URL relativa debe ser relativa a la raíz del sitio, no al archivo Markdown actual, porque la misma fuente puede renderizarse a una profundidad diferente del sistema de archivos en Hugo o importarse a WordPress.

• Los enlaces a páginas internas usan una barra inclinada inicial y final, como el enlace a la biblioteca de elementos . No uses ../, omitas la barra inicial ni codifiques el dominio de producción para una página interna.
• Los enlaces externos usan una URL completa https://. El esquema es parte del destino y no debe ser inferido por un renderizador.
• Los archivos fuente de imágenes residen debajo de cdn-assets/seo-playbook/, y sus rutas públicas comienzan en /cdn-assets/seo-playbook/. Añade el grupo y nombre de archivo aprobados solo después de que el recurso exista.
• El texto alternativo describe la información transmitida por una imagen, no su nombre de archivo o apariencia decorativa. Una imagen decorativa usa un texto alternativo vacío, pero la página del elemento relevante debe permitir explícitamente la decoración.
• Una llamada a la acción en línea usa :button[Etiqueta visible]{href="/destino/"}. El texto entre corchetes es la etiqueta accesible y href sigue las mismas reglas de ruta interna o externa. Usa un botón solo para una acción genuina siguiente, no para hacer que un enlace de referencia ordinario sea más prominente.

Una imagen es contenido, no un workaround para un diseño no soportado. Si la imagen contiene etiquetas, números o instrucciones esenciales, repite esa información en texto accesible o usa un elemento estructurado que la exponga. Las solicitudes de captura de pantalla permanecen como comentarios HTML hasta que el recurso nombrado exista; no son referencias de imagen publicadas y deben establecer screenshotsPending = true en el frontmatter.

El frontmatter y los elementos del cuerpo tienen trabajos diferentes

El frontmatter describe el documento como documento. Las directivas del cuerpo describen bloques significativos dentro de la experiencia de lectura. Mantener estas capas separadas permite que las páginas de listado, los esquemas, el enrutamiento y las herramientas de publicación lean metadatos sin analizar la prosa visible.

Por lo tanto, los elementos de metadatos viven en el frontmatter: título de página, descripción, palabras clave, fechas de publicación y actualización, información canónica o de alias, propiedad, taxonomía, uniones del playbook y cualquier colección orientada a esquemas que el contrato de la página coloque allí, como las entradas de FAQ en páginas de academy. Estos campos nunca se escriben como directivas :::. Un bloque visible que repite algunos metadatos no mueve el campo autorizado fuera del frontmatter; recibe su propio elemento del cuerpo solo cuando tiene un propósito separado orientado al lector.

Los elementos de contenido viven en el cuerpo: definiciones, advertencias, consejos, resúmenes, conclusiones, listas de verificación, comparaciones, bloques de evidencia, ejemplos, pasos y llamadas a la acción. Son directivas porque su ubicación en la narrativa importa. Mover una advertencia al frontmatter la desconectaría del pasaje que califica; ocultar metadatos en una directiva del cuerpo haría que los sistemas a nivel de documento no puedan encontrarlos de manera confiable.

Los metadatos son obligatorios por defecto

Los metadatos impulsan rutas, vistas previas, descubrimiento, uniones y salida estructurada antes de que alguien lea el cuerpo. Un campo omitido puede, por lo tanto, romper consumidores que nunca renderizan el artículo. Por esa razón, cada elemento de metadatos es obligatorio a menos que su página de elemento diga explícitamente que es opcional.

Obligatorio significa poblado con un valor válido, no meramente presente como una cadena vacía o colección vacía. No infieras opcionalidad de la omisión de otra página y no añadas valores de relleno para satisfacer la validación. Si un valor obligatorio aún no se conoce, la página no está lista para publicarse. Los elementos del cuerpo siguen las reglas de obligatoriedad del tipo de publicación relevante y de las páginas de elemento, en lugar de este valor predeterminado de metadatos.

Escribe primero, aplica elementos después

La selección de elementos es una tarea de clasificación, mientras que redactar es una tarea de razonamiento. Intentar realizar ambas frase por frase hace que el escritor optimice prematuramente los límites del componente. El resultado habitual son transiciones más débiles, explicaciones superficiales ajustadas a una caja, encabezados repetitivos creados para satisfacer el marcado y directivas elegidas porque son convenientes en lugar de porque su propósito coincida.

Por lo tanto, la producción se realiza en dos pasadas distintas:

1. Escribe el artículo completo como texto plano. Completa el argumento, ejemplos, calificaciones, transiciones y conclusión. En esta etapa, los encabezados pueden describir la lógica del borrador, pero no determinan el tipo de elemento final.
2. Aplica elementos en una pasada separada de arriba a abajo. Para cada encabezado y bloque, indica su propósito, revisa la biblioteca, envuelve las secciones coincidentes, añade los atributos declarados y confirma el mapeo y anidamiento del cuerpo.

La separación mejora ambos resultados. La prosa se desarrolla según las preguntas del lector en lugar de los tamaños de caja del tema actual, mientras que la pasada de marcado puede comparar bloques similares de manera consistente en todo el documento. También hace visibles las omisiones: un escritor puede ver que el artículo contiene una advertencia o definición antes de decidir cómo codificarla.

Después de la pasada estructural, lee la página una vez sin mirar los nombres de las directivas. Los elementos deben apoyar un artículo coherente, no convertirlo en una pila de widgets desconectados. Luego inspecciona la fuente una vez sin juzgar la prosa, verificando cierres, atributos, elementos anidados, rutas y metadatos requeridos.

El contrato de tres notaciones

Un elemento se define una vez por su propósito, campos canónicos, valores permitidos, mapeo del cuerpo, comportamiento de accesibilidad, comportamiento de salida estructurada y versión. Esa definición es la fuente de verdad. Las tres notaciones de plataforma son adaptadores a ella, no tres diseños de componente independientes.

Las formas representativas explican el mapeo; la página del elemento individual publica su nombre y campos exactos soportados. Los autores trabajan en la notación requerida por su flujo de trabajo de publicación, pero no renombran campos, añaden significados solo de plataforma ni imitan manualmente el HTML de otro renderizador.

El propietario del elemento mantiene la definición canónica y decide si un cambio propuesto es compatible o versionado. Los mantenedores de Hugo y WordPress son dueños de sus adaptadores y los prueban contra fixtures compartidos: el mismo título, contenido, atributos, elementos, enlaces y expectativas de accesibilidad deben sobrevivir las tres rutas. Los propietarios editoriales verifican el propósito y los ejemplos. Ningún mantenedor de plataforma puede redefinir el significado editorial localmente; si una plataforma no puede expresar el contrato, eso es un defecto del adaptador o una propuesta de cambio de contrato.

Este modelo permite que la presentación difiera donde las plataformas lo requieran mientras mantiene estable la semántica. Hugo puede renderizar HTML del lado del servidor y WordPress puede almacenar un comentario de bloque, pero una advertencia sigue siendo una advertencia, un elemento de lista de verificación sigue siendo un elemento, y los mismos campos requeridos permanecen disponibles río abajo.

Versionado de elementos publicados

El contenido publicado fue revisado contra el significado del elemento que existía en el momento de la publicación. Cambiar ese significado silenciosamente puede alterar advertencias, datos estructurados, accesibilidad o importaciones sin que un editor toque la página. El versionado protege esa aprobación editorial.

Usa la siguiente política de cambios:

• Cambio compatible en el renderizador: Un refinamiento visual, mejora de rendimiento o corrección de error que preserve el propósito, campos, valores aceptados, mapeo del cuerpo y significado de la salida puede enviarse dentro de la versión actual. Las páginas existentes lo reciben a través del renderizador.
• Cambio aditivo compatible: Un nuevo atributo opcional puede unirse a la versión actual solo cuando su ausencia preserve la salida existente y cada adaptador pueda ignorarlo o soportarlo de forma segura. La definición y las pruebas de plataforma cambian juntas.
• Cambio disruptivo: Un campo renombrado o eliminado, un nuevo campo obligatorio, cambio en el mapeo del cuerpo, cambio de propósito, cambio de valor predeterminado con efecto semántico o estructura de elementos anidados incompatible crea una nueva versión mayor del elemento.
• Desaprobación: La versión antigua permanece renderizable para páginas publicadas. Su página de elemento identifica el reemplazo y la ruta de migración; las páginas nuevas usan la versión actual.
• Migración: Una migración de contenido es explícita, delimitada, previsualizada en Markdown, Hugo y WordPress, y validada editorialmente antes de la publicación. Registra qué páginas cambiaron y por qué. No hagas que un renderizador adivine cómo se debe reinterpretar la fuente antigua.

Cuando no se escribe ninguna versión en la fuente, el elemento usa la versión base definida cuando se adoptó este contrato. Esa línea base implícita debe permanecer estable. Las nuevas versiones mayores se identifican mediante el mecanismo de versión declarado en la página del elemento; no reutilizan la sintaxis sin versionar.

La reversión también es importante. Mantén el renderizador anterior y la representación fuente disponibles hasta que las páginas migradas pasen las verificaciones estructurales, visuales, de accesibilidad y de salida estructurada. Si una migración falla, restaura el mapeo de la versión anterior en lugar de aplanar el elemento en texto libre, lo que descartaría la semántica que el versionado pretende proteger.

Lista de verificación de revisión de producción

Usa esta revisión final después de la pasada de prosa y la pasada de elementos:

• ¿Se puede expresar el propósito de cada bloque que no sea prosa en un solo verbo?
• ¿Se buscó en la biblioteca por ese propósito y sinónimos cercanos?
• ¿Cada propósito coincidente usa su elemento tipado, incluso cuando un H2 y un párrafo se verían similares?
• ¿Cada pasaje restante de texto libre es parte de la explicación, análisis, narrativa o transición continua del artículo?
• ¿Los atributos siguen {clave=valor clave2="valor con espacios" .clase}, con espacios entrecomillados y usando solo claves declaradas?
• ¿El primer encabezado del cuerpo se mapea a title y el resto a content, a menos que la página del elemento declare otro mapeo?
• ¿Los hijos repetibles usan ::item{clave=valor} … ::, con los atributos del padre y del elemento colocados en el nivel correcto?
• ¿Los enlaces internos son relativos a la raíz con barras inclinadas inicial y final, los enlaces externos son absolutos y las rutas de imagen están dentro de la raíz de imágenes aprobada?
• ¿Los campos de metadatos están en el frontmatter, nunca en directivas del cuerpo, y están completos todos los valores de metadatos obligatorios?
• ¿Los mismos campos canónicos pueden mapearse sin pérdida a Markdown, Hugo y WordPress?
• ¿Cualquier cambio de definición preserva las páginas antiguas o introduce una versión explícita y una migración?

Esta página es un requisito previo para cada página de elemento individual. Cada definición de elemento debe enlazar de vuelta a estas reglas base, y luego documentar solo sus excepciones específicas de propósito: atributos soportados, campos obligatorios, anulaciones de mapeo del cuerpo o de elementos, anidamiento permitido, nombres exactos de plataforma e historial de versiones. Si una página de elemento guarda silencio, se aplican los valores predeterminados de esta página.