Como o Docsbook constrói o cabeçalho de uma página

Esta página é o mecanismo: o que o Docsbook coloca em <head> e em sitemap.xml para cada página que hospeda, na ordem em que o código resolve isso, para que você possa prever a saída em vez de fazer uma requisição curl. Para saber o que isso significa para você e o que precisa ativar, comece pelo índice de SEO.

Qual é o título da página e de onde ele vem?#

O <title> de uma página do Docsbook é resolvido em três etapas; a primeira correspondência é usada:

Ordem	Origem	Por que vem primeiro
1	Frontmatter `title:`	O único dos três que você pode editar sem alterar o que o leitor vê na página.
2	O corpo `# H1`	Um título real, já escrito para uma pessoa.
3	Um título derivado do nome do arquivo	Nunca fica vazio; uma página sempre tem uma linha de SERP.

O nome do workspace é então acrescentado exatamente uma vez, como Page title — Workspace, e ignorado quando o título já o contém como uma palavra independente. "Docs" dentro de "Docsbook" não conta — os dois caracteres vizinhos da correspondência devem ser caracteres não pertencentes a palavras, testados em relação a letras e dígitos Unicode, e não aos caracteres ASCII; assim, um nome de workspace em cirílico ou CJK corresponde da mesma forma que um nome latino. Uma página cujo título contém apenas o nome do workspace (a raiz do site) torna-se Workspace — Documentation. A string final é emitida como um título absoluto, o que impede que o modelo %s | Docsbook usado em todo o site acrescente uma segunda cópia da marca.

Em uma página traduzida, o título vem dos metadados traduzidos em cache e, caso contrário, do primeiro <h1> do HTML traduzido armazenado — portanto, uma página em chinês exibe um título em chinês. A descrição é deliberadamente mantida no idioma de origem: o Docsbook não inventa uma tradução para ela.

O que é a meta description e o que é removido dela?#

Ordem: primeiro o description: do frontmatter e, em seguida, os parágrafos iniciais da própria página.

Antes que o texto do corpo possa se tornar uma descrição, ele é limpo: comentários HTML (que são os marcadores de widgets), marcadores {icon-name}, títulos, imagens, código delimitado e inline, caracteres de ênfase, tags HTML brutas, marcadores de itens de lista e marcadores de citações em bloco são removidos, e um link Markdown é reduzido ao texto do link, em vez de inserir sua URL na frase. Parágrafos com 20 caracteres ou menos são descartados como fragmentos.

Duas extensões são construídas a partir da mesma fonte em uma única passagem: 160 caracteres para <meta name="description"> e 400 para og:description e o description JSON-LD. Uma descrição fornecida no frontmatter preenche ambos. O truncamento ocorre em um limite de palavra e dá preferência ao final de uma frase quando ele cai na metade final do limite; caso contrário, o texto termina com reticências.

Qual URL a página considera canônica?#

Uma página, uma URL canônica, resolvida nesta ordem:

Seu domínio personalizado, quando o espaço de trabalho tem um. O espelho *.docsbook.io então disponibiliza Disallow: / em vez de existir como uma segunda cópia.
Um caminho raiz pertencente ao produto, para a própria documentação do Docsbook.
O caminho curto raiz para espaços de trabalho de demonstração, pois essa é a URL que responde a 200 — a forma com subdomínio redireciona para ela.
https://<owner>.docsbook.io/<repo>/<path> para todo o restante.

As páginas traduzidas seguem os mesmos quatro caminhos, com a localidade inserida onde o roteador realmente a disponibiliza. en é tratado especialmente de volta para a URL sem prefixo, pois /en/page e /page disponibilizam conteúdo idêntico byte a byte, e uma URL de localidade para uma página que não foi realmente traduzida renderiza o texto de origem, portanto usa a URL de origem como canônica em vez de alegar ser a autoridade.

Quais idiomas são anunciados como alternativas?#

O conjunto hreflang contém x-default e en no URL de origem, além de uma entrada para cada idioma ativado para o qual esta página foi de fato traduzida. Ativar um idioma não o adiciona: a URL de um locale não traduzido aponta canonicamente para fora de si mesma, e um desses membros basta para invalidar todo o cluster. Uma página que contenha noindex não recebe nenhum conjunto, em vez de um conjunto pendente.

O sitemap não emite nenhuma alternativa no nível da página, propositalmente: ele não pode arcar com a verificação de tradução por página, portanto qualquer conjunto que criasse listaria todos os locales ativados e reintroduziria exatamente a contradição que o conjunto no nível da página existe para evitar.

Cada página emite OpenGraph (og:title, og:description com comprimento de 400 caracteres, og:url = a URL canônica, og:site_name, og:type: article, og:locale) e um cartão X do tipo summary_large_image contendo a descrição de 160 caracteres. A imagem é gerada por página em 1200×630, armazenada em cache por 24 horas e renderiza a composição da marca do workspace, a seção como um texto acima do título, o título da página (cortado em 64 caracteres, reduzido acima de 30) e a descrição cortada em 130, nas cores do workspace. Em um domínio personalizado, o cartão é a mesma imagem, solicitada por URL absoluta a partir do domínio apex — mas og:description contém a string de 160 caracteres, não a de 400 caracteres.

Quais diretivas de robots uma página contém?#

Quatro regras, em ordem estrita de precedência:

Condição	Emitido
Pré-visualização administrativa (`?preview=true`)	`noindex, follow`
Chave de SEO global desativada	`noindex, nofollow`
Frontmatter da página `noindex`	`noindex, follow`
Caso contrário	`index, follow`

noindex: true, noindex: yes, noindex: 1 e a grafia robots: noindex contam todas. Qualquer outra coisa — ausente, false, index — significa indexar.

robots.txt varia conforme o host. O domínio raiz fornece uma regra curinga permissiva com Crawl-delay: 10, impede os caminhos sem conteúdo próprios do aplicativo, nomeia explicitamente dezoito rastreadores de IA e de pesquisa em Crawl-delay: 5, bloqueia diretamente treze rastreadores de alto volume e baixo valor de citação e lista uma linha Sitemap: por site localizável. Um subdomínio de workspace fornece a mesma política para bots, além de sua própria linha Sitemap:. Um domínio personalizado fornece a política para bots sem nenhuma linha Sitemap: — ele ainda não tem seu próprio sitemap, e direcionar os rastreadores para o sitemap do espelho anunciaria um segundo host para cada página. Crawl-delay é uma cortesia, não um padrão: o RFC 9309 define apenas user-agent, allow e disallow, e o Google adiciona sitemap e nada mais — “outros campos, como crawl-delay, não são compatíveis”.

O que entra em sitemap.xml?#

Um sitemap por proprietário, reconstruído no máximo uma vez por hora. Para cada repositório indexado, ele lista todos os arquivos Markdown, mapeando um README na raiz do repositório para a raiz do site e todos os outros arquivos para seus próprios caminhos. Cada entrada contém:

lastmod — a data do último commit que alterou esse arquivo, proveniente do repositório de origem. O horário de renderização é usado apenas quando não é possível ler o histórico de commits.
changefreq — weekly.
priority — 0.9 para uma página de destino, 0.7 para uma página interna e 0.8 / 0.6 para suas traduções.

Os URLs traduzidos são listados somente quando uma tradução realmente existe, e URLs duplicados são consolidados antes da emissão do arquivo. Um repositório cuja árvore não possa ser lida é descartado silenciosamente, e o restante do sitemap continua sendo servido: um sitemap que retorna 500 custa mais do que um que deixa um site de fora.

Páginas que contêm noindex ainda são listadas. Reconhecer a flag significa ler o conteúdo de todas as páginas, algo que a criação do sitemap deliberadamente não faz; a própria diretiva da página é respeitada quando ela é acessada, portanto o custo é uma visita do rastreador.

Quais dados estruturados são emitidos?#

Em um host hospedado pelo Docsbook, cada página emite um @graph JSON-LD com três nós:

Organization — o espaço de trabalho, sua URL, seu perfil do GitHub e seu logotipo, se definido.
TechArticle — título, descrição, URL canônica, inLanguage, datePublished e dateModified do histórico de commits do repositório de origem, autor, editor, mainEntityOfPage.
BreadcrumbList — proprietário → site → cada segmento de caminho, criado com o mesmo construtor canônico que o <link rel="canonical"> usa, para que nenhuma migalha possa nomear um host com o qual a tag canônica discorde.

Com o AEO ativado, speakable é adicionado, e os nós FAQPage / HowTo aparecem somente quando a página realmente contém essa estrutura. Com o GEO ativado, um autor Person é adicionado a partir do frontmatter ou do autor do último commit.

Âncoras, modo de renderização e hosts#

Âncoras. Os ids dos títulos vêm do gerador de slugs do próprio renderizador, e cada link profundo que o Docsbook fornece — resultados de pesquisa, citações de IA — é calculado chamando essa mesma biblioteca, em vez de derivar novamente a string. Títulos duplicados apontam para a primeira ocorrência.

Modo de renderização. Uma solicitação anônima para uma página pública é atendida por uma rota renderizada no servidor e armazenada em cache (janela de 24 horas); solicitações de usuários autenticados e de pré-visualização seguem para uma renderização dinâmica e nunca são armazenadas em cache pela CDN. De qualquer forma, o rastreador recebe HTML completo — nenhuma etapa de renderização no lado do cliente se interpõe entre um bot e o seu texto.

Domínio personalizado versus o domínio compartilhado. Em um domínio personalizado, a URL canônica, o título, a descrição, os cartões e um nó TechArticle estão todos presentes, e a política de bots é aplicada. Cinco coisas não estão: a configuração de SEO em todo o site e o noindex por página (as páginas são servidas index, follow incondicionalmente), o conjunto hreflang, os nós BreadcrumbList e Organization, os redirecionamentos de páginas movidas e os sinais de GEO — nenhum bloco de TL;DR, nenhuma linha visível de Atualizado e um autor TechArticle que é sempre um Person nomeado após o proprietário do repositório. Consulte Limitações.

Por que essas regras (evidências)#

Regra	Por que funciona para o consumidor	Fonte
Um `<title>` em cada página, marca acrescentada uma vez	O Google lista `<title>` primeiro entre as fontes de títulos de links e alerta contra "texto repetido ou padrão em elementos `<title>`"	Títulos de links
Descrições por página, nunca uma única string para todo o site	"Descrições idênticas ou semelhantes em todas as páginas de um site não são úteis"	Snippets
O canônico aponta para uma URL que responde com 200, nunca para um redirecionamento	`rel="canonical"` é "um sinal forte", e o Google recomenda um canônico autorreferente na página canônica	Consolidar URLs duplicadas
Somente localidades genuinamente traduzidas em `hreflang`	"Se a página X vincula à página Y, a página Y deve vincular de volta à página X… essas anotações podem ser ignoradas"	Versões localizadas
Datas reais de commit como `lastmod`	O Google usa `<lastmod>` "se for consistente e comprovadamente… preciso"	Criar um sitemap
Dados estruturados somente para conteúdo que a página possui	"não adicione dados estruturados sobre informações que não estejam visíveis para o usuário"	Introdução aos dados estruturados
HTML renderizado no servidor em vez de no cliente	O Google renderiza JS em uma fila na qual uma página "pode permanecer… por alguns segundos, mas pode levar mais tempo", e "nem todos os bots podem executar JavaScript"	Noções básicas de SEO para JavaScript
Imagem de cartão de 1200×630	"Use imagens com pelo menos 1200 x 630 pixels", próximo a uma proporção de 1,91:1	Imagens para compartilhamento

Limites e questões em aberto#

priority e changefreq são decorativos. O Docsbook os gera, e o Google afirma claramente: "O Google ignora os valores de <priority> e <changefreq>." O protocolo sitemaps.org acrescenta que a prioridade "provavelmente não influenciará a posição dos seus URLs". Eles não custam nada e não proporcionam nada ao Google; outros mecanismos variam.
TechArticle não está na lista de resultados avançados de artigos do Google. É um tipo real do schema.org (Thing > CreativeWork > Article > TechArticle) e descreve o conteúdo com precisão, mas a documentação de artigos do Google afirma que os objetos "devem ser baseados em um dos seguintes tipos do schema.org: Article, NewsArticle, BlogPosting". Considere o nó uma descrição precisa, não uma garantia de elegibilidade para resultados avançados. Os dados estruturados também não são documentados como um fator de classificação: a introdução do Google os descreve como algo que torna uma página elegível para uma aparência aprimorada e não diz nada sobre a classificação.
Questão em aberto: o que o og:description de 400 caracteres proporciona. O Docsbook o cria porque a tag tem espaço onde <meta description> não tem. Nenhuma fonte que consultamos documenta como algum consumidor específico trunca og:description, e o protocolo OpenGraph não especifica nenhum limite de tamanho. Considere 400 uma escolha interna, não um ótimo medido.
Páginas em domínios personalizados ignoram suas opções de indexação. A opção de SEO de todo o site e o noindex por página são respeitados apenas em hosts hospedados pelo Docsbook; em um domínio personalizado, a página é disponibilizada como index, follow independentemente disso. /sitemap.xml também não é resolvido ali, portanto seu robots.txt não contém nenhuma linha de Sitemap:, e uma página renomeada por meio do Docsbook mantém seu redirecionamento apenas no domínio compartilhado. Para manter uma página fora do índice em um domínio personalizado atualmente, mantenha-a fora do repositório publicado.
Um único sitemap é limitado a 50.000 URLs / 50 MB, de acordo com o protocolo sitemaps.org e o próprio limite do Google. O Docsbook gera um sitemap por proprietário e não os divide; um proprietário acima desse limite não é tratado atualmente.