Jamdesk Documentation logo

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

Meta tags

Título e descrição do frontmatter se tornam meta tags.

Open Graph

Imagens de compartilhamento social geradas para cada página.

Sitemap e robots

Sitemap XML e robots.txt gerados em cada build.

JSON-LD

Dados estruturados Schema.org em cada página para resultados de busca enriquecidos.

IndexNow

URLs alteradas enviadas aos mecanismos de busca após cada build.

Endpoints de IA

llms.txt e servidor MCP para que ferramentas de IA leiam sua documentação.

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:

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:

docs.json
{
  "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.

Prévia do OpenGraph

Visualize o cartão de qualquer página no X, Facebook, LinkedIn e outros. Valide suas tags Open Graph.

---
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

GrupoTags
Open Graphog: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
Artigoog:type: article com article:published_time, article:modified_time, article:author, article:section, article:tag
Twitter / Xtwitter:card, twitter:title, twitter:description, twitter:image, twitter:image:alt, twitter:site, twitter:creator, twitter:player, tags de cartão de aplicativo
Outraskeywords, 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:

ValorComo aparece
summaryMiniatura quadrada pequena à esquerda, título + descrição ao lado. Compacto.
summary_large_imageImagem 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:

docs.json
{
  "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:

docs.json
{
  "seo": {
    "socialCard": {
      "theme": "dark",
      "brandColor": true,
      "accentBar": false,
      "siteName": false,
      "customImage": "replace"
    }
  }
}
ChavePadrãoEfeito
theme"light""dark" usa texto claro sobre fundo escuro e a imagem logo.dark.
brandColorfalsetrue 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.
accentBartruefalse remove a barra colorida ao longo da parte inferior do cartão.
siteNametruefalse 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.

ArquivoFinalidade
sitemap.xmlLista todas as páginas com datas de última modificação para mecanismos de busca
robots.txtPermite 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.txt

O que o sitemap inclui

  • Todas as páginas publicadas (excluindo as que têm noindex ou hidden no 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 (de docs.json).
  • BreadcrumbList: caminho de navegação de Início até a página atual, derivado da sua configuração navigation.

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:image personalizada nas páginas principais, ou use o cartão gerado automaticamente. Verifique-o com a ferramenta Prévia do OpenGraph.

Artigos relacionados

Referência de frontmatter

Todas as opções de frontmatter disponíveis

Referência de docs.json

Opções de configuração para o site inteiro

Ferramenta de prévia do OpenGraph

Visualize e valide seus cartões sociais em todas as plataformas