Otimização de SEO
Controle títulos, descrições e meta tags para mecanismos de busca e prévias em redes sociais. A Jamdesk gera sitemaps e imagens Open Graph automaticamente.
Defina títulos, descrições e metadados no frontmatter para controlar como sua documentação aparece em mecanismos de busca e prévias em redes sociais.
O que o Jamdesk faz automaticamente
Como otimizar seu conteúdo
Escreva um frontmatter eficaz
---
title: User Authentication # Under 60 characters
description: Set up OAuth, JWT, and session-based authentication # 120-160 characters
---
Coloque as palavras-chave no início. "Configuração de autenticação" é melhor que "Como configurar a autenticação".
Títulos de página
- Mantenha abaixo de 60 caracteres, contando o nome do site que o formato de título adiciona. Títulos mais longos são truncados nos resultados de busca
- Inclua sua palavra-chave principal próximo ao início
- Torne cada título único em toda a sua documentação
Por padrão, o título na aba do navegador e no resultado de busca é Título da página — Nome do site. Altere-o com seo.titleTemplate em docs.json. Coloque %s onde deve ir o título da página:
{
"seo": {
"titleTemplate": "%s | Acme"
}
}
Uma página intitulada Primeiros passos então exibe Primeiros passos | Acme. Use "%s" sozinho para omitir o nome do site. Um template sem %s faz o build falhar. jamdesk validate mostra o erro. As prévias de links (og:title e twitter:title) continuam mostrando somente o título da página.
Algumas páginas ignoram o template. Uma página sem title exibe seu name seguido de "Documentation", como Acme Documentation, ou somente o name se ele já terminar em "Docs" ou "Documentation". Uma página cujo título é igual ao seu name exibe apenas esse título.
jamdesk validate e jamdesk dev aceitam seo.titleTemplate a partir da versão 1.1.220 da CLI. Atualize com npm i -g jamdesk@latest.
Descrições
- Procure de 120 a 160 caracteres
- Resuma o que o leitor vai aprender
- Inclua palavras-chave relevantes de forma natural
Fallback gerado automaticamente. A Jamdesk extrai o primeiro parágrafo de texto do conteúdo da página (até 155 caracteres) quando description está ausente no frontmatter. Títulos, blocos de código, imagens e componentes MDX são ignorados. Esse texto preenche <meta name="description">, Open Graph e cartões do Twitter. Uma descrição explícita ainda oferece os melhores resultados.
Como controlar a indexação
Configurações para todo o site
Defina o comportamento padrão dos robôs em docs.json:
{
"seo": {
"metatags": {
"robots": "index, follow"
}
}
}Controle por página
Substitua a indexação de páginas específicas no frontmatter:
---
title: Internal Notes
noindex: true
---
Use noindex para:
- Páginas de rascunho ou em andamento
- Documentação interna
- Conteúdo descontinuado que você mantém para referência
Indexação de busca e ingestão por IA
Os metadados robots e noindex controlam mecanismos de busca: se uma página aparece no Google e no seu sitemap.xml. Eles não afetam os arquivos llms.txt e llms-full.txt que as ferramentas de IA leem. Defina seo.ai.llmsTxt como false para deixar de publicá-los (veja Desativando o llms.txt). Os dois controles são independentes: uma página pode ser indexada por mecanismos de busca e excluída da ingestão por IA, ou o inverso.
URLs canônicas
Defina uma canônica se sua documentação estiver acessível em várias URLs:
---
title: Getting Started
canonical: https://docs.example.com/getting-started
---
Você também pode definir uma base canônica para o site inteiro em docs.json. A Jamdesk acrescenta o caminho de cada página a ela:
{
"seo": {
"metatags": {
"canonical": "https://docs.acme.com"
}
}
}Prévia social e Open Graph
A Jamdesk gera um cartão social 1200×630 com a marca do site para cada página. Substitua qualquer tag social no frontmatter com chaves de nível superior simples ou com um bloco seo: aninhado. O valor de nível superior prevalece quando a mesma chave é definida das duas formas.
---
title: API Reference
description: REST API endpoints and authentication
"og:title": API Reference — Acme
"og:description": Everything you need to call the Acme API
"og:image": /images/api-social-card.png
"twitter:card": summary_large_image
"twitter:creator": "@acme"
keywords: ["api", "rest", "authentication"]
canonical: https://docs.acme.com/api-reference
---Tags compatíveis
| Grupo | Tags |
|---|---|
| Open Graph | og:title, og:description, og:image, og:image:width, og:image:height, og:image:alt, og:url, og:type, og:site_name, og:locale, og:video, og:audio |
| Artigo | og:type: article com article:published_time, article:modified_time, article:author, article:section, article:tag |
| Twitter / X | twitter:card, twitter:title, twitter:description, twitter:image, twitter:image:alt, twitter:site, twitter:creator, twitter:player, tags de cartão de aplicativo |
| Outras | keywords, author, robots, googlebot, google-site-verification, theme-color, além de qualquer tag personalizada (coloque tags personalizadas em seo:) |
Dimensões de imagem OG personalizada. og:image:width e og:image:height só se aplicam quando customImage é "replace". Defina-as no mesmo lugar do og:image que descrevem, seja no frontmatter da página ou em seo.metatags. O cartão gerado tem sempre 1200×630.
Tags personalizadas. Meta tags arbitrárias (por exemplo, x-pinterest) são emitidas como <meta name="...">. Coloque-as no bloco seo:. Somente chaves de SEO reconhecidas são aproveitadas quando definidas no nível superior.
Tipo de card do Twitter / X
A tag twitter:card controla qual layout o X (e outras plataformas) usam quando seu link é compartilhado:
| Valor | Como aparece |
|---|---|
summary | Miniatura quadrada pequena à esquerda, título + descrição ao lado. Compacto. |
summary_large_image | Imagem grande em largura total no topo, título + descrição abaixo. |
Use summary_large_image para um cartão de marca 1200×630. Ele exibe a imagem em largura total.
Imagem padrão para todo o site
Defina uma imagem social de reserva para todas as páginas em docs.json. Qualquer página que defina seu próprio og:image a substitui:
{
"seo": {
"metatags": {
"og:image": "https://docs.acme.com/images/default-card.png"
}
}
}Visualize antes de publicar. Cole a URL da página na ferramenta Prévia do OpenGraph após um build. Ela mostra como o cartão aparece em cada plataforma e valida as tags Open Graph. Também verifica as dimensões da imagem e explica como corrigir problemas.
Personalizar o cartão social
O seu cartão gerado mantém a aparência atual, a menos que você adicione seo.socialCard ao docs.json. Defina apenas as chaves que quer alterar:
{
"seo": {
"socialCard": {
"theme": "dark",
"brandColor": true,
"accentBar": false,
"siteName": false,
"customImage": "replace"
}
}
}| Chave | Padrão | Efeito |
|---|---|---|
theme | "light" | "dark" usa texto claro sobre fundo escuro e a imagem logo.dark. |
brandColor | false | true colore a barra inferior e o selo de seção com colors.primary. Um cartão escuro usa colors.light, se você tiver definido. Se não tiver colors, o cartão usa a cor de destaque do seu tema. false mantém o vermelho padrão. |
accentBar | true | false remove a barra colorida ao longo da parte inferior do cartão. |
siteName | true | false oculta o nome do site abaixo do logo. Use quando seu logo já mostra o nome. |
customImage | "background" | "background" desenha o título da página sobre sua og:image. "replace" usa sua og:image como o cartão inteiro. |
O cartão só consegue desenhar logos SVG, PNG e JPG. A Jamdesk converte para WebP, no momento do build, arquivos de logo PNG e JPG do seu repositório. Com isso, o cartão costuma mostrar o favicon e mantém o nome do site, mesmo com siteName: false. Use um logo SVG para exibir seu logo completo no cartão. Use um SVG em logo.dark para um cartão escuro.
O cartão não consegue desenhar texto dentro de um logo SVG. Esse texto sai em branco. Converta o texto em contornos (paths) na sua ferramenta de design e exporte o SVG novamente. No Figma, selecione o texto e use Flatten. No Illustrator, use Type > Create Outlines. O build mostra uma sugestão quando encontra texto no SVG do logo do cartão. Logos definidos com uma URL completa (https://...) não são verificados.
O texto do selo volta à cor de texto normal quando a sua cor de marca não se destaca do cartão. A barra mantém a cor de marca, a menos que essa cor quase se confunda com o fundo do cartão. Nesse caso, a barra fica cinza.
Por padrão, a Jamdesk desenha o título da página sobre sua og:image. Defina "customImage": "replace" para mostrar uma imagem que já tenha seu próprio texto ou design, sem alterações.
Escolha o theme que combina com uma og:image usada como fundo do cartão: dark para uma imagem escura, light para uma clara.
No modo replace, a Jamdesk não desenha título sobre a imagem. Uma og:image em seo.metatags se aplica a todas as páginas. Uma página que define sua própria og:image usa essa em vez dela. Somente páginas sem nenhuma das duas recebem um cartão gerado. Use um PNG ou JPG 1200×630. Algumas plataformas não exibem imagens WebP ou SVG.
Redes sociais armazenam em cache as prévias de links. Um link já compartilhado pode manter o cartão antigo por um tempo depois que você altera essas configurações. Confira o novo cartão com a ferramenta Prévia do OpenGraph.
Versões mais antigas da CLI da Jamdesk rejeitam seo.socialCard e seo.titleTemplate em jamdesk validate e jamdesk dev. Atualize com npm i -g jamdesk@latest.
Sitemap e robots.txt
A Jamdesk gera sitemap.xml e robots.txt em cada build.
| Arquivo | Finalidade |
|---|---|
sitemap.xml | Lista todas as páginas com datas de última modificação para mecanismos de busca |
robots.txt | Permite todos os rastreadores e aponta para o sitemap |
Onde encontrá-los
As URLs dependem de sua documentação estar em um domínio raiz ou em um subcaminho /docs:
Se sua documentação estiver na raiz do domínio (por exemplo, docs.acme.com ou acme.jamdesk.app):
https://docs.acme.com/sitemap.xml
https://docs.acme.com/robots.txtO que o sitemap inclui
- Todas as páginas publicadas (excluindo as que têm
noindexouhiddenno frontmatter) - Datas de última modificação do frontmatter, quando disponíveis
- Frequência de alteração semanal
Excluir páginas do sitemap
Adicione noindex ao frontmatter para manter uma página fora do sitemap e dos mecanismos de busca:
---
title: Internal Notes
noindex: true
---
Páginas com hidden: true também são excluídas.
Dados estruturados JSON-LD
Toda página inclui dados estruturados do schema.org como uma tag <script type="application/ld+json">, com dois esquemas:
WebSite: nome do seu site, URL e descrição (dedocs.json).BreadcrumbList: caminho de navegação de Início até a página atual, derivado da sua configuraçãonavigation.
Não é necessária nenhuma configuração. Mecanismos de busca usam isso para resultados enriquecidos, como trilhas de navegação (breadcrumbs) nos resultados.
Verifique sua marcação. Cole a URL de qualquer página no Teste de Resultados Enriquecidos do Google para confirmar que os dados estruturados são detectados.
IndexNow
A Jamdesk envia as URLs de páginas alteradas para o IndexNow após cada build. Bing, Yandex e outros mecanismos de busca participantes ficam sabendo das alterações sem esperar pelo próximo ciclo de rastreamento.
- Dispara após cada build bem-sucedido
- Envia apenas as páginas que mudaram
- Não bloqueante. Nunca atrasa seu build
- Não requer configuração
Práticas recomendadas
Revise esta lista antes de publicar:
Checklist antes de publicar
- Títulos únicos: cada página tem um título distinto e descritivo com menos de 60 caracteres.
- Descrições precisas: as descrições resumem a página em 120-160 caracteres.
- Títulos lógicos: os títulos seguem uma hierarquia limpa: um H1, depois H2 → H3.
- Links descritivos: os links internos usam um texto âncora significativo, nunca "clique aqui".
- Texto alternativo das imagens: toda imagem tem texto alternativo para acessibilidade e busca de imagens.
- Imagem social: defina uma
og:imagepersonalizada nas páginas principais, ou use o cartão gerado automaticamente. Verifique-o com a ferramenta Prévia do OpenGraph.
