Frontmatter

Defina os cinco campos de frontmatter de cada página — title, description, meta_tags, namespace e permalink — sob as regras de cada um.

Última atualização

Ver como Markdown Configurar agente

Comece pelo template

Toda página da documentação abre com um bloco de frontmatter. Quem escreve define cinco campos. O exemplo mostra a página em inglês do par, que é a fonte da verdade:

YAML
01---
02title: Create an Object Storage bucket
03description: >-
04 Create a read-only Object Storage bucket and grant read-write
05 permissions from the Azion API, the CLI, or Azion Console.
06meta_tags: 'Object Storage, bucket, permissions, edge storage, create bucket'
07namespace: documentation_products_object_storage_bucket
08permalink: /documentation/guides/application-development/data/create-and-modify-bucket/
09---

O title vira o H1 da página. Por isso, o corpo começa em um heading ##, nunca em #. Escreva o título com maiúscula só na primeira palavra e nos nomes próprios, como define Terminologia da documentação.

Um validador roda dentro de cada build. Ele interrompe o build quando um namespace ou um permalink está ausente, malformado ou aparece duas vezes no mesmo idioma. O validador não lê os outros campos; a qualidade deles depende de quem escreve.

Defina o namespace

O namespace identifica a página no site. Ele também é a chave que une os idiomas: a página em inglês e a tradução em português carregam o mesmo valor, caractere por caractere. Páginas bilíngues descreve o vínculo completo.

Duas regras se aplicam:

  • Mantenha o valor único dentro do idioma. Um valor duplicado interrompe o build.
  • Mantenha o valor idêntico entre os dois idiomas. Um valor diferente quebra o seletor de idioma, e o build passa mesmo assim.

A segunda regra não tem rede de proteção. O seletor perde a conexão entre as duas páginas em silêncio; confira o valor manualmente.

Escreva o valor em palavras minúsculas unidas por underscore. Construa o valor a partir do produto e da funcionalidade: documentation_products_object_storage_bucket.

O permalink é a URL da página sem o segmento de idioma. Só o permalink define a URL; o caminho do arquivo não define.

  • Não adicione prefixo de idioma. A árvore de diretórios fornece o prefixo: um arquivo na árvore em português publica em /pt-br/ mais o permalink. Um permalink que começa com /pt-br/ publica a página em /pt-br/pt-br/....
  • Use só letras ASCII minúsculas, dígitos, hífens e barras, e termine com uma barra: /documentacao/guias/desenvolvimento-de-aplicacoes/dados/criar-e-modificar-um-bucket/.
  • Mantenha o permalink único dentro do idioma. A página em inglês e a página em português têm permalinks diferentes, então o par nunca colide.
  • Remova os acentos dos permalinks em português: configuracao, não configuração.
  • Nomeie a URL pelo lugar da página na navegação: o caminho da seção, os segmentos das linhas acima dela e o slug da própria página, como em /documentacao/plataforma/firewall/waf/rule-sets/. Uma página muda de URL quando o lugar dela na navegação muda, e nunca quando o arquivo muda.
  • Mudar um permalink muda a URL, e a URL antiga passa a precisar de um redirect na mesma mudança.

Escreva a description e as meta_tags

A description vira a meta description da página. O valor de meta_tags vira as keywords, em uma lista separada por vírgulas entre aspas.

Nenhuma verificação valida esses dois campos, então um campo vazio publica em silêncio. Escreva os dois em toda página.

Escreva a description como uma ou duas frases que se sustentam sozinhas, com 50 a 160 caracteres. Comece com um verbo no imperativo e diga o que o leitor realiza na página. Não repita o título palavra por palavra. As regras de Estrutura de frases valem para a description.

Quatro aberturas são proibidas: Esta página descreve..., Este documento explica..., Saiba mais sobre... e Aprenda a.... Comece direto com o verbo. Uma abertura genérica gasta a description sem acrescentar informação.

Posicione a página em um menu lateral

A página não nomeia o próprio menu lateral. A navegação lista a página pelo namespace, e o menu lateral que o leitor vê é o da seção que a lista. Registre a página na navegação, não em um campo do frontmatter.

O campo também resolve a posse: cada página pertence a exatamente uma seção. Uma seção pode listar uma página que outra seção possui, e essa linha é um cross-link, não uma reivindicação. Mantenha a posse na seção onde os vizinhos da página vivem.

Omita o campo type

O frontmatter aceita um campo opcional type, que troca a página para um layout especial, como uma home com grade de cards. Páginas de documentação omitem o campo. Uma página sem o campo usa o layout padrão, que é o correto para conteúdo de documentação.