YAML front matter: metadados no topo de um arquivo Markdown
YAML front matter
YAML front matter no Markdown: sintaxe, campos e exemplos | We.Inc
O que é YAML front matter, as regras do ---, os campos que Jekyll, Hugo, Eleventy e Astro leem, e um separador que mostra os metadados e o corpo do seu próprio arquivo.
Front matter é um bloco de YAML bem no topo de um arquivo Markdown, aberto e fechado por uma linha de três hifens (---). Os geradores de sites estáticos o leem como os dados da página, como título, data, layout e tags, e renderizam tudo abaixo da linha de fechamento como o conteúdo da página.
Suporte a front matter em quatro geradores de sites estáticos populares
Gerador
Formatos
Campos que ele mesmo lê
Jekyll
YAML entre ---
layout, permalink, published; em posts: date, category, categories, tags
O front matter transforma um arquivo Markdown simples em uma página com metadados, e um único hífen fora do lugar o quebra. Cole um arquivo no separador para ver exatamente onde os metadados terminam e o conteúdo começa, e quais campos de nível superior ele encontrou, antes que o seu build reclame.
Cole um arquivo Markdown ou edite o post de exemplo.
O separador verifica se a primeira linha é --- (YAML) ou +++ (TOML) e procura a linha de fechamento correspondente.
Ele mostra o bloco de front matter, os campos simples de nível superior que encontrou e o corpo que será renderizado.
Se o bloco nunca for fechado, ele avisa, e essa é a causa mais comum de uma página mostrar os metadados como texto.
Nada pode vir antes do --- de abertura, nem uma linha em branco nem um byte order mark, senão a maioria dos geradores trata o bloco como texto comum.
Coloque entre aspas os títulos que têm dois-pontos seguidos de espaço, como "Preços: o que mudou", senão o YAML os lê como um mapeamento aninhado.
Escreva as datas como YYYY-MM-DD para que geradores e bibliotecas YAML concordem sobre o que elas significam.
Mantenha os campos personalizados em um lugar consistente. O Hugo, por exemplo, tem uma chave params feita para os seus próprios valores.
Perguntas frequentes
O que é front matter no Markdown?
São metadados escritos no topo de um arquivo Markdown entre duas linhas delimitadoras. O próprio Markdown não os define; os geradores de sites estáticos e as ferramentas de conteúdo adotaram a convenção e os leem como dados antes de renderizar o resto.
O front matter precisa ser YAML?
YAML é o padrão comum, mas não a única opção. O Hugo aceita TOML entre linhas +++ e JSON entre chaves, o Eleventy aceita ---json e ---js, e o Astro também aceita TOML.
Por que a minha página mostra o front matter como texto?
Geralmente há algo antes do primeiro ---, falta o --- de fechamento ou a linha de abertura tem caracteres a mais. O separador acima aponta os dois últimos casos na hora.
O front matter pode ficar vazio?
Sim. No Jekyll, um par vazio de linhas --- ainda marca o arquivo para processamento, e é assim que arquivos CSS ou de feed têm as tags Liquid renderizadas sem nenhum metadado.
Como leio o front matter no meu próprio código?
Divida o arquivo nos delimitadores, interprete a primeira parte com uma biblioteca YAML e passe o resto para o seu renderizador de Markdown. O Eleventy faz isso com o pacote gray-matter, que você também pode usar diretamente no Node.
As regras dos delimitadores
A documentação do Jekyll é direta: o front matter precisa ser a primeira coisa no arquivo e precisa ser YAML válido entre linhas de três hifens. Os outros geradores seguem o mesmo formato.
Dentro do bloco vale o YAML normal. Indente com espaços, coloque entre aspas os valores com caracteres especiais e use listas para tags e categorias.
Campos que vale definir em toda página
Um title e uma description cobrem o título da página e o trecho na busca na maioria dos temas. Uma date ordena os posts, e draft ou published decide se a página é gerada ou não.
Todo o resto depende dos seus templates. Qualquer campo que você adicionar vira um dado que o layout pode exibir, como o nome do autor, o caminho de uma imagem de destaque ou o tempo de leitura.
Exemplos de front matter
Um post de blog (YAML)
Um post típico: título entre aspas porque contém dois-pontos, uma data, uma lista de tags e um campo personalizado de autor.
O mesmo post com front matter em TOML (Hugo)
O Hugo lê +++ como front matter em TOML. Os valores personalizados ficam na chave params.
Separador de front matter
Cole um arquivo Markdown. O separador encontra o bloco de front matter, lista os campos simples de nível superior e mostra o corpo que será renderizado.
Arquivo Markdown
Front matter ({f})
Campos de nível superior encontrados
Nenhuma linha simples key: value no nível superior.
Corpo
Sem front matter: a primeira linha não é --- nem +++, então o arquivo inteiro é tratado como conteúdo.
O bloco aberto com {d} nunca é fechado. Adicione uma linha {d} correspondente depois do último campo.