Frontmatter YAML a JSON en Markdown: matriz SSG, ejemplos y errores comunes

El frontmatter de Markdown — ese pequeño bloque YAML envuelto en --- al inicio del archivo — se vuelve un estorbo cuando quieres empujar artículos a un CMS headless, generar un índice JSON con la metadata, migrar entre generadores estáticos, o pasar contexto estructurado a un LLM. La solución técnica es corta, pero los detalles se cuelan justo cuando tu SSG acepta un formato y la siguiente herramienta del pipeline espera otro distinto.

Esta guía cubre cómo extraer el bloque YAML de frontmatter de un archivo Markdown y convertirlo a JSON, qué SSG acepta nativamente qué formato, cómo manejar fechas y cadenas multilínea sin perder información, y cuándo conviene una CLI frente a un convertidor en el navegador. El camino más corto es "abrir el .md → copiar el YAML entre los dos --- → pegar en YAML a JSON". Toda la conversión corre dentro del navegador, así que los posts privados y los payloads internos del CMS nunca salen de tu máquina.

La respuesta corta: frontmatter es "delimitadores + cuerpo YAML", convierte solo el cuerpo

Un bloque de frontmatter tiene esta forma:

---
title: "Mi primer post"
date: 2026-06-22
tags: ["intro", "demo"]
draft: false
---

A partir de aquí empieza el cuerpo Markdown.

Las dos líneas con --- son separadores de documento según YAML 1.2, pero cuando alimentas un bloque de frontmatter a un parser, lo que realmente quieres convertir son las cuatro líneas del medio. Pega esas cuatro líneas en YAML a JSON y obtienes:

{
  "title": "Mi primer post",
  "date": "2026-06-22",
  "tags": ["intro", "demo"],
  "draft": false
}

Fíjate en los tipos: title es cadena, date queda como cadena (JSON no tiene tipo Date), tags es un array, draft es un booleano real. La inferencia de tipos de YAML es lo que hace fiel la salida JSON, y también lo que más bugs causa cuando se equivoca.

¿Para qué convertir el frontmatter? Cuatro casos típicos

Casi todas las peticiones de conversión caen en uno de estos cuatro escenarios. Saber en cuál estás te dice qué extraer y qué vigilar.

Ingesta a CMS headless / API

Contentful, Strapi, Sanity y servicios similares manejan la metadata de los posts como JSON estructurado. Si tu equipo escribió Markdown con frontmatter YAML durante años y ahora migra a un CMS, conviertes el frontmatter a JSON y lo incluyes en el payload REST o GraphQL.

Scripts de build que solo necesitan metadata

Generar artefactos como "índice de posts", "conteo de tags" o "archivo por fecha de publicación" no necesita parsear el cuerpo entero de cada Markdown. Extraer solo el frontmatter como JSON mantiene barato el paso de build. En Node.js la herramienta canónica es gray-matter; en Python es python-frontmatter.

Migrar entre SSG

Pasar de Jekyll a Astro, o de Hugo a Next.js, exige auditar cada title, layout, permalink y campo personalizado. Las diferencias de tipo entre SSG son reales — el namespace params.foo de Hugo no existe en Astro Content Collections — y convertir el frontmatter a JSON te da una forma normalizada para grep contra ella.

Formato de contexto para LLM / RAG

Alimentar artículos a ChatGPT, Claude o un pipeline RAG es más preciso cuando pasas la metadata como JSON estructurado junto al cuerpo. Las etiquetas, categorías y fechas pasan a ser direccionables por máquina en vez de quedar enterradas en un preámbulo YAML.

Los tres formatos de frontmatter: YAML, TOML, JSON

El frontmatter no siempre es YAML. Los SSG aceptan formatos distintos con delimitadores distintos, y de ahí viene la mayor parte de la fricción entre herramientas.

Frontmatter YAML (el más habitual)

---
title: "Hola"
date: 2026-06-22
---

Delimitado por tres guiones ---. Jekyll, Hugo, Astro, Eleventy, Gatsby, Docusaurus — casi todos los SSG importantes aceptan este formato.

Frontmatter TOML (territorio de Hugo / Zola)

+++
title = "Hola"
date = 2026-06-22
+++

Delimitado por tres signos más +++. Zola exige TOML; Hugo acepta YAML, TOML y JSON.

Frontmatter JSON (Hugo y Eleventy)

{
  "title": "Hola",
  "date": "2026-06-22"
}

Las llaves mismas hacen de delimitadores. Hugo y Eleventy parsean esto de forma nativa. Astro, Jekyll, Gatsby y Docusaurus no — la documentación de Astro dice literalmente "YAML o TOML".

Matriz de compatibilidad de frontmatter por SSG

Esto es lo que cada SSG importante acepta sin configuración adicional, según la documentación oficial a mediados de 2026.

Dos conclusiones prácticas:

• ¿Vas hacia Astro, Jekyll, Gatsby o Docusaurus con metadata en JSON? Convierte a YAML primero; no parsean frontmatter JSON.
• ¿Migras a Zola? Tienes que traducir cada bloque de frontmatter de YAML a TOML en lote.

Hugo y Eleventy son los consumidores más flexibles — la metadata YAML o JSON existente funciona sin conversión.

Extraer el frontmatter de un Markdown completo

Antes de pegar nada en el convertidor, necesitas solo el cuerpo YAML, sin las líneas --- ni el cuerpo Markdown. El procedimiento:

1. Confirma que la línea 1 es exactamente --- y que no hay línea en blanco antes. La mayoría de parsers rechaza el frontmatter si hay algo por encima de la apertura.
2. Avanza hasta encontrar el siguiente --- aislado en su propia línea.
3. Las líneas estrictamente entre esas dos vallas son tu cuerpo YAML.

Pega ese cuerpo en YAML a JSON. La conversión corre íntegramente en tu navegador, así que los posts no publicados, la documentación interna o los payloads de CMS con secretos no se suben a ningún servidor. Eso hace a FormatArc complementario de las CLI más que un sustituto: una CLI es lo correcto cuando procesas cientos de archivos en CI, y una herramienta de navegador es lo correcto cuando quieres inspeccionar un bloque antes de enviarlo a un CMS.

Errores comunes al extraer

• "parse error: bad indentation" — tu YAML mezcla tabuladores con espacios. Convierte todo a espacios.
• "mapping values are not allowed here" — un valor contiene dos puntos y no está entre comillas. Encierra el valor: title: "10:00 reunión".
• "could not find expected ':'" — falta el espacio después de - o : en un ítem de lista o clave de mapa.

Sentido inverso: frontmatter JSON a YAML

Si sacas metadata de un CMS como JSON y necesitas escribirla de vuelta a un archivo Markdown, quieres la conversión inversa. JSON a YAML toma un objeto JSON y devuelve YAML. Para que sea un bloque de frontmatter válido, envuelve el resultado en vallas ---:

---
{ aquí va la salida YAML de la conversión }
---

Te tocará hacer esto cada vez que lleves datos en forma JSON hacia Astro, Jekyll, Gatsby o Docusaurus, dado que ninguno acepta frontmatter JSON directamente.

Cinco tipos que se rompen en la conversión YAML a JSON

YAML y JSON tienen sistemas de tipos que se solapan pero no son idénticos. Estas cinco categorías son las que más tropiezan en conversiones de frontmatter.

Fechas y horas

Los parsers YAML 1.1 pueden convertir 2026-06-22 en un valor Date nativo, pero JSON no tiene tipo Date, así que se serializa como cadena. Verifica que la salida sea "2026-06-22" con las comillas, no un número o un objeto. Los valores con zona horaria como 2026-06-22T10:00:00+02:00 se mantienen como cadenas ISO 8601.

Cadenas multilínea

Los bloques YAML | (literal, preserva saltos) y > (plegado, colapsa saltos a espacios) terminan en una sola cadena JSON con escapes \n. Asegúrate de que los saltos de línea sobrevivieron como esperabas.

description: |
  Línea uno
  Línea dos

queda como

{ "description": "Línea uno\nLínea dos\n" }

Anclas y alias (& / *)

YAML te deja definir un ancla (&id) y reutilizarla con un alias (*id). JSON no tiene equivalente, así que el alias se expande en una copia. Si tu YAML reutilizaba una referencia para ahorrar memoria, la salida JSON será más grande y cualquier mutación posterior afectará solo a una copia.

Tags personalizados (!Ruby/Symbol, !!python/object: etc.)

Los tags YAML específicos de un lenguaje, como los símbolos Ruby de Jekyll o los objetos Python de PyYAML, no pueden ir y volver a JSON. La mayoría de parsers o bien lanzan error o silenciosamente descartan el tag y conservan solo el valor. Audita tu frontmatter buscando cualquier prefijo ! antes de convertir.

Unicode y comillas

YAML trata las cadenas con comillas simples (') y dobles (") de forma distinta — las simples conservan las barras invertidas literalmente, las dobles interpretan las secuencias de escape. JSON exige comillas dobles, así que los valores YAML con comillas simples se reescriben como JSON con dobles, lo que a veces cambia cómo se renderizan \n o \t.

Cuándo usar una CLI y cuándo FormatArc

Hay varias herramientas maduras para convertir frontmatter YAML a JSON. No compiten entre sí; cada una encaja en un flujo distinto.

Un reparto razonable: inspección puntual, vuelo previo al CMS y contenido sensible van a FormatArc; lotes en CI e indexación del repositorio entero van a una CLI.

Patrones del mundo real

Enviar a Contentful o Strapi

Mapea las claves de tu frontmatter a los campos del Content Model del CMS. Si los nombres divergen, transforma la salida JSON antes del POST — a mano si es una migración única, o con una función de mapeo encima de gray-matter si la sincronización se repite.

Importar exports de Notion

El export Markdown de Notion no produce un bloque de frontmatter como tal. Normalmente tienes que escribir uno aparte y luego convertirlo a JSON para las herramientas que vienen después. Las propiedades de página de Notion también se exportan como JSON por separado, lo cual es más limpio de fusionar que intentar reconstruir el frontmatter desde la cabecera de la página.

Validación de frontmatter en CI

Un job típico de GitHub Actions convierte el frontmatter de cada archivo a JSON y lo valida contra un JSON Schema: campos obligatorios presentes, fechas en formato ISO, tags no vacíos. Cazar deriva de esquema en el momento del PR sale mucho más barato que perseguirla en producción.

Trampas frecuentes

--- choca con una regla horizontal del cuerpo

Una regla horizontal en Markdown también se escribe ---. Si una HR suelta queda muy arriba del cuerpo, un parser permisivo puede confundirla con el cierre del frontmatter. Usa *** o ___ para HRs y evitas la colisión.

Tabuladores en la indentación

YAML prohíbe tabuladores en la indentación. Un solo tab dentro del bloque de frontmatter lanza "found character that cannot start any token". Configura tu editor para convertir tabs a espacios en los archivos .md.

Sobre-inferencia booleana (el problema noruego)

YAML 1.1 trata yes, no, on, off, y, n como booleanos. Un valor como country: NO (Noruega) se vuelve silenciosamente country: false después de la conversión. Encierra los valores ambiguos: "NO". Es lo bastante famoso como para tener apodo ("the Norway problem") y termina afectando a casi todos los equipos.

Cadenas numéricas que pierden ceros a la izquierda

ISBNs, códigos postales y números de teléfono como 01234 se vuelven 1234 porque YAML los parsea como enteros. Encierra entre comillas: "01234".

Cierre — la ruta más corta de conversión de frontmatter

Resumiendo, el flujo para llevar un bloque de frontmatter YAML a JSON es:

1. Abre el archivo Markdown y copia el cuerpo YAML entre las dos vallas --- (sin incluir las vallas).
2. Pega en YAML a JSON. Todo corre en el navegador.
3. Audita la salida buscando los cinco tipos frágiles: fecha, multilínea, anclas, tags personalizados y booleanos ambiguos.
4. Envía el JSON al CMS, script de build, validador de esquema o LLM que lo necesite.

Cuando necesites el sentido inverso, JSON a YAML lo cubre. Cuando migres entre SSG, la matriz de arriba te dice qué destino acepta qué formato nativamente.

Lectura relacionada sobre YAML, JSON y Markdown:

• Guía de sintaxis YAML — los bloques básicos de YAML
• Convertir YAML a JSON: guía completa — el caso general más allá del frontmatter
• YAML vs JSON: cuándo usar cuál — elegir un formato
• Qué es YAML — YAML para principiantes
• Guía de Markdown a HTML — el lado del cuerpo
• CommonMark vs GFM — diferencias de dialectos Markdown