Frontmatter
Configure títulos, descrições, ícones, barras laterais e metadados de SEO usando o bloco YAML de frontmatter no topo de cada arquivo MDX.
Todo arquivo MDX começa com um bloco YAML entre marcadores ---. Esses metadados controlam o título da página, a aparência da barra lateral e como a página é exibida quando compartilhada nas redes sociais ou nos resultados de busca.
Frontmatter básico
Toda página precisa de pelo menos um título:
---
title: Getting Started
description: Learn the basics in 5 minutes
---Campos disponíveis
Obrigatório
| Campo | Tipo | Descrição |
|---|---|---|
title | string | Título da página exibido na navegação e na aba do navegador |
Recomendado
| Campo | Tipo | Descrição |
|---|---|---|
description | string | Resumo breve para SEO e resultados de busca (50-160 caracteres) |
Opcional
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
icon | string | - | Ícone do Font Awesome exibido ao lado do título da página na navegação da barra lateral |
sidebarTitle | string | title | Título mais curto para a navegação da barra lateral |
mode | string | - | Defina como "wide" para usar um layout de largura total |
hideFooter | boolean | false | Oculta o rodapé social nesta página |
rss | boolean | false | Ativa a geração de feed RSS a partir dos componentes Update nesta página |
search | boolean | true | Defina como false para excluir a página da busca do site, das respostas do chat de IA e do MCP. Ela permanece na barra lateral, no sitemap e no llms.txt. Consulte Excluir uma página apenas da busca |
private | boolean | false | Exige a senha do site para visualizar esta página. Definir isso em qualquer página ativa o modo de páginas específicas na próxima build. |
public | boolean | false | Isenta esta página da proteção por senha (usado quando todo o site é protegido por auth.password.enabled). Tem precedência sobre private: true quando ambos são definidos. |
SEO e redes sociais
Controle como a página aparece nos resultados de busca e nas prévias sociais. Defina esses campos como chaves de nível superior ou dentro de um bloco seo: aninhado. Ambos funcionam, e os valores por página substituem os padrões seo.metatags de docs.json.
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
keywords | string[] | - | Palavras-chave de busca, emitidas como uma tag <meta name="keywords"> |
canonical | string | auto | URL canônica desta página, substituindo a URL gerada automaticamente |
noindex | boolean | false | Exclui esta página dos mecanismos de busca e do sitemap |
og:* / twitter:* | string | - | Tags de prévia social do Open Graph e do Twitter/X (por exemplo, og:title, og:image, twitter:card) |
seo | object | - | Bloco aninhado que contém qualquer um dos campos acima, além de tags meta personalizadas arbitrárias |
---
title: API Reference
description: REST endpoints and authentication
"og:image": /images/api-card.png
"twitter:card": summary_large_image
canonical: https://docs.acme.com/api-reference
---Consulte Otimização de SEO para ver a lista completa de tags compatíveis e exemplos.
Após uma build, cole a URL da página na ferramenta gratuita OpenGraph Preview para ver como essas tags são renderizadas no X, Facebook, LinkedIn, Slack, Discord e muito mais.
Exemplos
Página de documentação padrão
---
title: Authentication
description: Secure your API with OAuth 2.0 and API keys
icon: lock
---Título longo com substituição na barra lateral
---
title: Configuring Single Sign-On with SAML 2.0
sidebarTitle: SSO Setup
description: Set up enterprise SSO for your organization
---O título completo aparece na página, enquanto o sidebarTitle mais curto mantém a navegação organizada.
Layout amplo
---
title: API Reference
description: Complete API documentation
mode: wide
---O modo amplo remove o índice e expande o conteúdo para ocupar toda a largura. É útil para páginas de referência de API ou conteúdo com tabelas largas.
Ocultar rodapé
---
title: Custom Landing
description: A focused landing page experience
hideFooter: true
---Use hideFooter em páginas de destino, páginas de changelog ou qualquer página em que você queira uma seção inferior mais limpa, sem links sociais.
Práticas recomendadas de SEO
Seu título aparece em:
- Abas do navegador
- Resultados de mecanismos de busca
- Barra lateral de navegação
- Compartilhamentos nas redes sociais
Mantenha os títulos com menos de 60 caracteres. Coloque as palavras-chave importantes no início.
# Good - clear and keyword-rich
title: Deploy to Production
# Avoid - vague or too long
title: How to Deploy Your Application to Production ServersAs descrições aparecem nos resultados de busca e nas prévias sociais. Procure usar de 50 a 160 caracteres que:
- Resumam o conteúdo da página
- Incluam palavras-chave relevantes
- Incentivem os usuários a clicar
# Good - actionable and specific
description: Deploy your docs to production in under 2 minutes with zero configuration
# Avoid - generic or missing
description: Documentation pageOs ícones ajudam os usuários a identificar rapidamente os itens da navegação. Use o mesmo ícone em páginas relacionadas:
| Tópico | Ícone sugerido |
|---|---|
| Getting started | rocket |
| Authentication | lock |
| API reference | code |
| Settings | gear |
| Billing | credit-card |
Consulte os ícones no Font Awesome.
Validação
O Jamdesk valida o frontmatter durante a build. Erros comuns:
Error: Page "api/auth.mdx" is missing required field: titleCorreção: Adicione o campo title ao frontmatter.
Error: Invalid frontmatter in "guide.mdx": unexpected tokenCorreção: Verifique se há:
- Aspas ausentes em strings com caracteres especiais
- Indentação incorreta
- Dois-pontos ausentes após as chaves
Cole o bloco entre os marcadores --- no YAML Validator gratuito para identificar a linha e a coluna do erro.