YAML front matter: metadatos al principio de un archivo Markdown
YAML front matter
YAML front matter en Markdown: sintaxis, campos y ejemplos | We.Inc
Qué es el front matter YAML, las reglas de ---, los campos que leen Jekyll, Hugo, Eleventy y Astro, y un separador que muestra los metadatos y el cuerpo de tu propio archivo.
El front matter es un bloque de YAML al principio de un archivo Markdown, abierto y cerrado por una línea de tres guiones (---). Los generadores de sitios estáticos lo leen como los datos de la página, como el título, la fecha, el layout y las etiquetas, y después renderizan todo lo que hay bajo la línea de cierre como el contenido de la página.
Soporte de front matter en cuatro generadores de sitios estáticos populares
Generador
Formatos
Campos que lee por sí mismo
Jekyll
YAML entre ---
layout, permalink, published; en los posts: date, category, categories, tags
El front matter convierte un archivo Markdown simple en una página con metadatos, y un solo guion mal colocado lo rompe. Pega un archivo en el separador para ver exactamente dónde terminan los metadatos y empieza el contenido, y qué campos de primer nivel encontró, antes de que tu build se queje.
Pega un archivo Markdown, o edita el post de ejemplo.
El separador comprueba que la primera línea sea --- (YAML) o +++ (TOML) y busca la línea de cierre correspondiente.
Muestra el bloque de front matter, los campos simples de primer nivel que encontró y el cuerpo que se renderizará.
Si el bloque nunca se cierra, te lo dice; es la causa más habitual de que una página muestre sus metadatos como texto.
No puede haber nada antes del --- de apertura, ni siquiera una línea en blanco o una marca de orden de bytes, o la mayoría de los generadores tratarán el bloque como texto normal.
Pon entre comillas los títulos que contengan dos puntos seguidos de un espacio, como "Precios: qué ha cambiado", o YAML los leerá como un mapeo anidado.
Escribe las fechas como YYYY-MM-DD para que los generadores y las bibliotecas YAML coincidan en lo que significan.
Mantén los campos personalizados en un mismo lugar coherente. Hugo, por ejemplo, tiene una clave params pensada para tus propios valores.
Preguntas frecuentes
¿Qué es el front matter en Markdown?
Son metadatos escritos al principio de un archivo Markdown entre dos líneas delimitadoras. Markdown en sí no lo define; los generadores de sitios estáticos y las herramientas de contenido adoptaron la convención y lo leen como datos antes de renderizar el resto.
¿El front matter tiene que ser YAML?
YAML es la opción por defecto habitual, pero no la única. Hugo acepta TOML entre líneas +++ y JSON entre llaves, Eleventy admite ---json y ---js, y Astro también acepta TOML.
¿Por qué mi página muestra el front matter como texto?
Normalmente hay algo antes del primer ---, falta el --- de cierre o la línea de apertura tiene caracteres de más. El separador de arriba señala los dos últimos casos al instante.
¿Puede el front matter estar vacío?
Sí. En Jekyll, un par de líneas --- vacías sigue marcando el archivo para procesarlo, que es como los archivos CSS o de feed renderizan etiquetas Liquid sin ningún metadato.
¿Cómo leo el front matter en mi propio código?
Divide el archivo en los delimitadores, analiza la primera parte con una biblioteca YAML y pasa el resto a tu renderizador de Markdown. Eleventy lo hace con el paquete gray-matter, que también puedes usar directamente en Node.
Las reglas de los delimitadores
La documentación de Jekyll lo dice claramente: el front matter debe ser lo primero del archivo y debe ser YAML válido colocado entre líneas de tres guiones. Los demás generadores siguen la misma forma.
Dentro del bloque se aplica YAML normal. Indenta con espacios, pon entre comillas los valores con caracteres especiales y usa listas para las etiquetas y las categorías.
Campos que conviene definir en cada página
Un título y una descripción cubren el encabezado de la página y el fragmento de búsqueda en la mayoría de los temas. Una fecha ordena los posts, y draft o published decide si la página se genera o no.
Todo lo demás depende de tus plantillas. Cualquier campo que añadas se convierte en datos que el layout puede mostrar, como el nombre de un autor, la ruta de una imagen principal o un tiempo de lectura.
Ejemplos de front matter
Un post de blog (YAML)
Un post típico: título entre comillas porque contiene dos puntos, una fecha, una lista de etiquetas y un campo author personalizado.
El mismo post con front matter en TOML (Hugo)
Hugo lee +++ como front matter en TOML. Los valores personalizados van bajo la clave params.
Separador de front matter
Pega un archivo Markdown. El separador encuentra el bloque de front matter, enumera sus campos simples de primer nivel y muestra el cuerpo que se renderizará.
Archivo Markdown
Front matter ({f})
Campos de primer nivel encontrados
No hay líneas simples clave: valor en el primer nivel.
Cuerpo
Sin front matter: la primera línea no es --- ni +++, así que todo el archivo se trata como contenido.
El bloque abierto con {d} nunca se cierra. Añade una línea {d} correspondiente después del último campo.