Frontmatter YAML para JSON em Markdown: matriz SSG, exemplos e cuidados

O frontmatter do Markdown — aquele bloco YAML cercado por --- no topo do arquivo — atrapalha sempre que você quer empurrar artigos para um CMS headless, gerar um índice JSON da metadata, migrar entre geradores estáticos, ou passar contexto estruturado para um LLM. A correção técnica é curta, mas os detalhes escapam justamente quando o seu SSG aceita um formato e a ferramenta seguinte do pipeline espera outro.

Este guia mostra como extrair o bloco YAML de frontmatter de um arquivo Markdown e converter para JSON, qual SSG aceita nativamente qual formato, como lidar com datas e strings multilinha sem perder informação, e quando usar uma CLI em vez de um conversor só de navegador. O caminho mais curto é "abrir o .md → copiar o YAML entre os dois --- → colar em YAML para JSON". Toda a conversão roda dentro do navegador, então posts privados e payloads internos de CMS nunca saem da sua máquina.

A resposta curta: frontmatter é "delimitadores + corpo YAML", converta só o corpo

Um bloco de frontmatter tem este formato:

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

A partir daqui começa o corpo Markdown.

As duas linhas com --- são separadores de documento em termos de YAML 1.2, mas quando você alimenta um bloco de frontmatter num parser, o que de fato você quer converter são as quatro linhas do meio. Cole essas quatro linhas em YAML para JSON e você recebe:

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

Repare nos tipos: title é string, date vira string (JSON não tem tipo Date), tags é array, draft é booleano de verdade. A inferência de tipos do YAML é o que torna a saída JSON fiel — e também o que mais causa bugs quando ela chuta errado.

Por que converter o frontmatter? Quatro casos comuns

A maior parte dos pedidos de conversão cai em um destes quatro cenários. Saber em qual você está define o que extrair e o que vigiar.

Ingestão em CMS headless / API

Contentful, Strapi, Sanity, microCMS e similares tratam a metadata do post como JSON estruturado. Se a sua equipe escreveu Markdown com frontmatter YAML durante anos e agora migra para um CMS, você converte o frontmatter para JSON e inclui no payload REST ou GraphQL.

Scripts de build que só precisam da metadata

Gerar artefatos como "índice de posts", "contagem de tags" ou "arquivo por data" não exige reparsear o corpo inteiro de cada Markdown. Extrair só o frontmatter como JSON mantém o passo de build barato. Em Node.js a ferramenta canônica é gray-matter; em Python é python-frontmatter.

Migração entre SSGs

Mover de Jekyll para Astro, ou de Hugo para Next.js, exige auditar cada title, layout, permalink e campo customizado. As diferenças de tipo entre SSGs são reais — o namespace params.foo do Hugo não existe nas Content Collections do Astro — e converter o frontmatter para JSON dá uma forma normalizada para fazer grep.

Formatação de contexto para LLM / RAG

Alimentar artigos para ChatGPT, Claude ou um pipeline RAG é mais preciso quando você passa a metadata como JSON estruturado junto do corpo. Tags, categorias e datas viram endereçáveis por máquina em vez de ficar enterradas num preâmbulo YAML.

Os três formatos de frontmatter: YAML, TOML, JSON

Frontmatter nem sempre é YAML. SSGs aceitam formatos diferentes com delimitadores diferentes, e é daí que vem a maior parte do atrito entre ferramentas.

Frontmatter YAML (o padrão)

---
title: "Olá"
date: 2026-06-22
---

Delimitado por três hifens ---. Jekyll, Hugo, Astro, Eleventy, Gatsby, Docusaurus — quase todos os SSGs importantes aceitam este formato.

Frontmatter TOML (território Hugo / Zola)

+++
title = "Olá"
date = 2026-06-22
+++

Delimitado por três sinais de mais +++. Zola exige TOML; Hugo aceita YAML, TOML e JSON.

Frontmatter JSON (Hugo e Eleventy)

{
  "title": "Olá",
  "date": "2026-06-22"
}

As próprias chaves são os delimitadores. Hugo e Eleventy parseiam isso de forma nativa. Astro, Jekyll, Gatsby e Docusaurus não — a documentação do Astro diz literalmente "YAML ou TOML".

Matriz de compatibilidade de frontmatter por SSG

Aqui está o que cada SSG importante aceita sem configuração adicional, conforme a documentação oficial em meados de 2026.

Duas conclusões práticas:

• Indo para Astro, Jekyll, Gatsby ou Docusaurus com metadata em JSON? Converta para YAML primeiro; eles não parseiam frontmatter JSON.
• Migrando para Zola? Você precisa traduzir cada bloco de frontmatter de YAML para TOML em lote.

Hugo e Eleventy são os consumidores mais flexíveis — metadata YAML ou JSON existente funciona sem conversão.

Extraindo o frontmatter de um Markdown completo

Antes de colar qualquer coisa no conversor, você precisa só do corpo YAML, sem as linhas --- e sem o corpo Markdown. O procedimento:

1. Confirme que a linha 1 é exatamente --- e que não tem linha em branco antes. A maioria dos parsers rejeita o frontmatter se houver qualquer coisa acima da abertura.
2. Avance até encontrar o próximo --- sozinho em sua própria linha.
3. As linhas estritamente entre essas duas cercas são o seu corpo YAML.

Cole esse corpo em YAML para JSON. A conversão roda inteiramente no seu navegador, então posts não publicados, documentação interna ou payloads de CMS com segredos não são enviados a servidor nenhum. Isso torna o FormatArc complementar às CLIs, não substituto: uma CLI é a escolha certa quando você processa centenas de arquivos em CI, e uma ferramenta de navegador é a escolha certa quando você quer inspecionar um bloco antes de enviar para um CMS.

Erros comuns de extração

• "parse error: bad indentation" — seu YAML mistura tabulações com espaços. Converta tudo para espaços.
• "mapping values are not allowed here" — um valor contém dois pontos e não está entre aspas. Envolva o valor: title: "10:00 reunião".
• "could not find expected ':'" — falta o espaço depois de - ou : em um item de lista ou chave de mapa.

Sentido inverso: frontmatter JSON de volta para YAML

Se você tira metadata de um CMS como JSON e precisa escrevê-la de volta num arquivo Markdown, quer a conversão inversa. JSON para YAML recebe um objeto JSON e devolve YAML. Para que o resultado vire um bloco de frontmatter válido, envolva-o em cercas ---:

---
{ aqui entra a saída YAML da conversão }
---

Isso acontece toda vez que você leva dados em forma JSON para Astro, Jekyll, Gatsby ou Docusaurus, já que nenhum deles aceita frontmatter JSON diretamente.

Cinco tipos que quebram na conversão YAML para JSON

YAML e JSON têm sistemas de tipos sobrepostos, mas não idênticos. Estas cinco categorias são as que mais tropeçam em conversões de frontmatter.

Datas e horas

Parsers YAML 1.1 podem transformar 2026-06-22 em um valor Date nativo, mas JSON não tem tipo Date, então fica serializado como string. Confirme que a saída é "2026-06-22" com as aspas, não um número ou um objeto. Valores com fuso horário como 2026-06-22T10:00:00-03:00 permanecem como strings ISO 8601.

Strings multilinha

Os blocos YAML | (literal, preserva quebras) e > (dobrado, colapsa quebras em espaços) terminam em uma única string JSON com escapes \n. Confirme que as quebras de linha sobreviveram como você esperava.

description: |
  Linha um
  Linha dois

vira

{ "description": "Linha um\nLinha dois\n" }

Âncoras e aliases (& / *)

YAML permite definir uma âncora (&id) e reusá-la em outro lugar com um alias (*id). JSON não tem equivalente, então o alias é expandido em uma cópia. Se o seu YAML reusava uma referência por economia de memória, a saída JSON ficará maior e qualquer mutação posterior afetará só uma cópia.

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

Tags YAML específicas de linguagem, como os símbolos Ruby do Jekyll ou os objetos Python do PyYAML, não fazem round-trip para JSON. A maioria dos parsers lança erro ou silenciosamente descarta a tag e mantém só o valor. Audite o seu frontmatter procurando qualquer prefixo ! antes de converter.

Unicode e aspas

YAML trata strings com aspas simples (') e duplas (") de forma distinta — as simples preservam as barras invertidas literalmente, as duplas interpretam sequências de escape. JSON exige aspas duplas, então valores YAML com aspas simples são reescritos como JSON com duplas, o que às vezes muda como \n ou \t são renderizados.

Quando usar uma CLI e quando o FormatArc

Existem várias ferramentas maduras para conversão de frontmatter YAML para JSON. Elas não competem entre si; cada uma encaixa em um fluxo diferente.

Uma divisão razoável: inspeção ad-hoc, voo de teste pré-CMS e conteúdo sensível vão para o FormatArc; lotes em CI e indexação do repositório inteiro vão para uma CLI.

Padrões do mundo real

Empurrando para Contentful ou Strapi

Mapeie as chaves do seu frontmatter para os campos do Content Model do CMS. Se os nomes divergirem, transforme a saída JSON antes do POST — manualmente para uma migração única, ou com uma função de mapeamento em cima do gray-matter para sincronização repetida.

Importando exports do Notion

O export Markdown do Notion não produz um bloco de frontmatter como tal. Normalmente você precisa escrever um separadamente e depois convertê-lo para JSON para as ferramentas a jusante. As propriedades de página do Notion também são exportadas como JSON em separado, o que é mais limpo de fundir do que tentar reconstruir o frontmatter a partir do cabeçalho da página.

Validação de frontmatter em CI

Um job típico do GitHub Actions converte o frontmatter de cada arquivo para JSON e valida contra um JSON Schema: campos obrigatórios presentes, datas em formato ISO, tags não vazias. Pegar deriva de schema na hora do PR sai muito mais barato do que caçá-la em produção.

Armadilhas frequentes

--- colide com uma régua horizontal do corpo

Uma régua horizontal em Markdown também se escreve ---. Se uma HR perdida ficar muito no início do corpo, um parser permissivo pode confundi-la com o fechamento do frontmatter. Use *** ou ___ para HRs e evita a colisão.

Tabulações na indentação

YAML proíbe tabulações na indentação. Uma única tab dentro do bloco de frontmatter lança "found character that cannot start any token". Configure o seu editor para converter tabs em espaços nos arquivos .md.

Sobre-inferência booleana (o problema norueguês)

YAML 1.1 trata yes, no, on, off, y, n como booleanos. Um valor como country: NO (Noruega) silenciosamente vira country: false após a conversão. Envolva valores ambíguos em aspas: "NO". É famoso o bastante para ter apelido ("the Norway problem") e termina afetando quase todas as equipes.

Strings numéricas perdendo zeros à esquerda

ISBNs, CEPs e números de telefone como 01234 viram 1234 porque YAML os parseia como inteiros. Envolva em aspas: "01234".

Fechamento — a rota mais curta de conversão de frontmatter

Resumindo, o fluxo para levar um bloco de frontmatter YAML para JSON é:

1. Abra o arquivo Markdown e copie o corpo YAML entre as duas cercas --- (sem incluir as cercas).
2. Cole em YAML para JSON. Tudo roda no navegador.
3. Audite a saída procurando pelos cinco tipos frágeis: data, multilinha, âncoras, tags customizadas e booleanos ambíguos.
4. Envie o JSON para o CMS, script de build, validador de schema ou LLM que precisar dele.

Quando precisar do sentido inverso, JSON para YAML cobre. Quando migrar entre SSGs, a matriz acima diz qual destino aceita qual formato nativamente.

Leitura relacionada sobre YAML, JSON e Markdown:

• Guia de sintaxe YAML — os blocos básicos de YAML
• Converter YAML para JSON: guia completo — o caso geral além do frontmatter
• YAML vs JSON: quando usar cada um — escolhendo um formato
• O que é YAML — YAML para iniciantes
• Guia de Markdown para HTML — o lado do corpo
• CommonMark vs GFM — diferenças entre dialetos Markdown