Front matter en Markdown

El front matter es un bloque de metadatos que se coloca al inicio de un archivo Markdown, antes del contenido. Sirve para asociar al documento información como el título, la descripción, la fecha de publicación, las etiquetas, el autor o cualquier otro dato estructurado que necesite el sistema que procesará el archivo.

Es un patrón fundamental en generadores de sitios estáticos, blogs basados en Markdown, sistemas de gestión de notas como Obsidian y prácticamente cualquier herramienta que necesite tratar los archivos .md como contenido publicable. A continuación verás las tres sintaxis más extendidas, los campos habituales y los errores que más quebraderos de cabeza dan al principio.

Sintaxis YAML

La forma más habitual de front matter usa sintaxis YAML y se delimita con tres guiones (---) al principio y al final del bloque. Es la opción por defecto en Jekyll, Hugo, Docusaurus, Astro, Obsidian y la mayoría de generadores modernos.

---
title: Mi artículo
description: Una descripción del artículo
date: 2026-01-15
tags:
  - markdown
  - tutorial
draft: false
---

El contenido del artículo empieza aquí.

YAML es muy permisivo con los espacios, pero exige consistencia en la indentación. Si tienes errores raros al procesar el archivo, casi siempre se deben a tabuladores mezclados con espacios o a niveles de indentación desiguales.

Sintaxis TOML

Generadores como Hugo o Zola admiten también front matter en formato TOML, delimitado por tres signos de suma (+++). TOML es más estricto que YAML en cuanto a tipos de datos, lo que reduce ambigüedades a costa de una sintaxis algo más verbosa.

+++
title = "Mi artículo"
description = "Una descripción del artículo"
date = 2026-01-15
tags = ["markdown", "tutorial"]
draft = false
+++

El contenido del artículo empieza aquí.

A diferencia de YAML, en TOML las cadenas siempre van entrecomilladas y las listas se escriben en una sola línea con corchetes.

Sintaxis JSON

Una tercera opción, menos común pero soportada por Hugo y algunas herramientas, consiste en escribir el front matter como un objeto JSON entre llaves al principio del archivo. Es la sintaxis más estricta de las tres y la menos cómoda de escribir a mano, pero útil cuando los metadatos los genera otro sistema automáticamente.

{
  "title": "Mi artículo",
  "description": "Una descripción del artículo",
  "date": "2026-01-15",
  "tags": ["markdown", "tutorial"],
  "draft": false
}

El contenido del artículo empieza aquí.

JSON exige comillas dobles obligatorias y no admite comentarios, así que solo es práctico en flujos automatizados.

Campos comunes

Los campos que aparecen en el front matter dependen del sistema que procese el archivo, pero hay un conjunto de claves que se repiten en casi todas las plataformas. La siguiente tabla recoge las más habituales:

Cada generador interpreta unos campos u otros, así que conviene consultar su documentación. Por ejemplo, en Obsidian hay claves específicas como aliases o cssclass, mientras que en Hugo destacan weight, menu o params.

Cómo se procesa el front matter

Cuando un procesador Markdown encuentra un bloque de front matter al inicio del archivo, lo separa del contenido y lo entrega al sistema que lo está consumiendo. Lo habitual es que el generador de sitios estáticos cargue esos metadatos en variables disponibles para la plantilla, de modo que el title del front matter se convierta en la etiqueta <title> de la página, la description se traduzca a la metaetiqueta correspondiente, la date se use para ordenar los artículos en el listado del blog y los tags se utilicen para construir las páginas de etiquetas.

En proyectos de Node, la librería de referencia para leer front matter es gray-matter, que se integra con Next.js, Astro y prácticamente cualquier flujo basado en JavaScript. En el mundo Python tienes python-frontmatter, que cumple la misma función.

Herramientas que soportan front matter

El front matter es prácticamente universal en herramientas relacionadas con Markdown. Estas son las más representativas, con la sintaxis que admite cada una:

• Jekyll: YAML únicamente. Fue uno de los primeros generadores en popularizar el formato.
• Hugo: YAML, TOML y JSON. Es el más flexible de los grandes.
• Astro: YAML. Lo integra de forma nativa en sus colecciones de contenido.
• Docusaurus: YAML, con campos específicos para documentación versionada.
• Next.js: YAML a través de librerías como gray-matter. Es lo que utiliza esta web.
• Gatsby: YAML mediante gatsby-plugin-mdx.
• Obsidian: YAML, con campos propios para la organización de notas.
• Eleventy: YAML, TOML y JSON.

Errores comunes con YAML

La mayoría de errores al procesar un archivo Markdown con front matter vienen de detalles muy concretos de la sintaxis YAML. Los más frecuentes son:

• Dos puntos seguidos de espacio dentro de un valor sin entrecomillar. Una línea como title: Markdown: la guía definitiva rompe YAML, porque el parser interpreta el segundo : como un separador de clave nuevo. La solución es entrecomillar el valor: title: "Markdown: la guía definitiva".
• Mezclar tabuladores con espacios en la indentación. YAML exige que la indentación sea siempre con espacios, y rompe en cuanto detecta un tabulador.
• Niveles de indentación inconsistentes. Si en un nivel usas dos espacios y en otro cuatro, el parser puede aceptar parte del bloque y rechazar el resto.
• Comillas dentro de comillas sin escapar. Una línea como title: "Esta es "mi" guía" confunde al parser. La solución es alternar comillas dobles y simples, o escapar con \".
• Fechas en formato no ISO. Algunos parsers exigen YYYY-MM-DD. Si escribes 15/01/2026 o 2026-1-15, puede interpretarse como cadena o lanzar un error.
• Valores booleanos no esperados. YAML interpreta como booleanos tanto true, false, yes, no, on y off. Si quieres que el valor sea la cadena literal "no", debes entrecomillarla.

Si un archivo Markdown se renderiza con el front matter incluido como texto en el cuerpo del documento, casi seguro que hay un fallo de sintaxis YAML que el parser no ha podido procesar. Los validadores online de YAML resuelven la mayoría de casos en segundos.

Recursos relacionados

• Especificación de YAML: documento oficial del formato.
• Versiones de Markdown: cómo distintas variantes tratan los metadatos.
• MDX: alternativa programática al front matter mediante const meta.
• Sintaxis avanzada de Markdown: el resto de extensiones útiles del formato.