Respostas estruturadas

O Docsbook escreve um elemento <script type="application/ld+json"> por página de documentação. Ele contém um @graph do schema.org — um único array de objetos vinculados — em vez de várias tags de script separadas, para que todos os objetos da página compartilhem um contexto e possam fazer referência uns aos outros por meio de @id.

Esta página lista exatamente o que entra nesse grafo, o que precisa ser verdadeiro no seu Markdown para que cada objeto apareça e qual é a aparência de uma falha.

O que está no grafo e o que o ativa#

SoftwareApplication não faz parte deste grafo. O Docsbook o emite em suas próprias páginas de marketing, não na documentação para clientes — se você leu uma comparação com um concorrente afirmando o contrário sobre nós, é lá que o tipo realmente existe.

As datas vêm do histórico Git do arquivo, não do frontmatter: datePublished e dateModified são lidos do commit mais recente que alterou esse arquivo. Uma página sem histórico de commits ainda não contém nenhuma das duas chaves, em vez de uma data inventada.

Que formato de Markdown produz um FAQPage?#

Uma seção se torna perguntas quando qualquer uma das condições é atendida:

1. Um H2 cujo texto corresponde a FAQ, Frequently asked questions ou ao russo Частые вопросы / Вопросы и ответы / Часто задаваемые — sem distinção entre maiúsculas e minúsculas. Todo H3 abaixo dele se torna uma pergunta, termine ou não com um ponto de interrogação.
2. Qualquer H3 que termine em ?, em qualquer lugar do documento, independentemente da seção em que esteja.

A resposta é toda linha não vazia entre esse H3 e o próximo título. * inline, _ e caracteres de crase são removidos. Os marcadores de widget de conteúdo (<!-- widget:accordion --> e seu marcador de fechamento) são ignorados, em vez de serem incorporados à resposta, pois um acordeão é a forma usual de criar uma FAQ.

Em seguida, os limites são aplicados nesta ordem: um ? final é anexado a cada pergunta que não tenha um; cada resposta é limitada a 1.000 caracteres; um par é descartado se a pergunta tiver 3 caracteres ou menos ou se a resposta tiver 10 caracteres ou menos; e a página mantém no máximo 20 perguntas.

## FAQ
 
### Does a custom domain change my page URLs
 
Yes. Every canonical URL, sitemap entry and breadcrumb item moves to the new host on the next render.
 
### How long does the certificate take
 
Usually under a minute after the CNAME resolves.

Um H3 que não seja uma pergunta e não esteja dentro de uma seção de FAQ não produz nada. ### Install the CLI sob ## Setup é corretamente ignorado.

Que estrutura Markdown produz um HowTo?#

Três condições devem ser atendidas em conjunto:

1. Um H1, H2 ou H3 começando com How to — ou o termo russo Как, cujo próximo caractere não pode ser uma letra ou um dígito, portanto Каким образом não corresponde.
2. Uma lista numerada vem em seguida — tanto 1. quanto 1) contam.
3. A lista tem pelo menos 3 etapas.

Cada item numerado torna-se um HowToStep. Seu name é a primeira frase, truncada em 80 caracteres no limite de uma palavra, com reticências; seu text é o item inteiro, limitado a 1.000 caracteres. Os links são convertidos em seu texto âncora e a ênfase em linha é removida. O conteúdo dentro de blocos de código delimitados é totalmente ignorado, portanto uma lista numerada em um exemplo não se torna um procedimento.

Um procedimento é limitado a 20 etapas e uma página a 5 objetos HowTo.

Um widget de etapas conta como a lista numerada. Dentro de uma região <!-- widget:stepper -->, cada título abre a próxima etapa, independentemente do seu nível — mas a região só se torna um HowTo se um título How to / Как a tiver introduzido. Um stepper sob # Quick start não produz nada.

## How to move your docs to a custom domain
 
1. Open the admin panel and select **Custom Domain**.
2. Enter `docs.example.com` and save.
3. Add the CNAME record the panel shows to your DNS provider.

Du​​as etapas não produzem nada. Se o procedimento realmente tiver duas etapas, esse é o resultado correto — não preencha a lista para atingir o limite.

Como é, de fato, o JSON-LD emitido#

Esta é a saída dos próprios extratores do Docsbook, executados sobre os dois blocos Markdown acima:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "FAQPage",
      "mainEntity": [
        {
          "@type": "Question",
          "name": "Does a custom domain change my page URLs?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "Yes. Every canonical URL, sitemap entry and breadcrumb item moves to the new host on the next render."
          }
        },
        {
          "@type": "Question",
          "name": "How long does the certificate take?",
          "acceptedAnswer": { "@type": "Answer", "text": "Usually under a minute after the CNAME resolves." }
        }
      ]
    },
    {
      "@type": "HowTo",
      "name": "How to move your docs to a custom domain",
      "step": [
        { "@type": "HowToStep", "position": 1, "name": "Open the admin panel and select Custom Domain.", "text": "Open the admin panel and select Custom Domain." },
        { "@type": "HowToStep", "position": 2, "name": "Enter docs.example.com and save.", "text": "Enter docs.example.com and save." },
        { "@type": "HowToStep", "position": 3, "name": "Add the CNAME record the panel shows to your DNS provider.", "text": "Add the CNAME record the panel shows to your DNS provider." }
      ]
    }
  ]
}

Observe o que o extrator fez com os títulos das perguntas: ele acrescentou o ? que o Markdown omitiu. É por isso que um H3 formulado como pergunta é lido corretamente na marcação, mesmo quando você o escreveu como uma afirmação.

O que a trilha de navegação contém#

A trilha é composta pela página inicial do espaço de trabalho → pela página inicial do projeto → por um item para cada segmento do caminho. O name de cada segmento é humanizado — a extensão .md é removida, hífens e sublinhados são convertidos em espaços e cada palavra começa com letra maiúscula — enquanto seu URL item é construído pelo mesmo gerador de URLs canônicas usado pelo <link rel="canonical"> da página, portanto os dois nunca podem indicar hosts diferentes. Em uma localidade traduzida, os URLs da trilha são expressos dentro dessa localidade.

{
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "acme", "item": "https://acme.docsbook.io" },
    { "@type": "ListItem", "position": 2, "name": "Acme Handbook", "item": "https://acme.docsbook.io/handbook" },
    { "@type": "ListItem", "position": 3, "name": "Guides", "item": "https://acme.docsbook.io/handbook/guides" },
    { "@type": "ListItem", "position": 4, "name": "Custom Domains", "item": "https://acme.docsbook.io/handbook/guides/custom-domains" }
  ]
}

O Google exige position, name e item em cada ListItem e pelo menos dois itens na lista (Google, breadcrumb); uma página na raiz do projeto produz exatamente os dois itens iniciais, que constituem o mínimo documentado.

O que speakable diz#

Com o AEO ativado, o TechArticle ganha:

"speakable": {
  "@type": "SpeakableSpecification",
  "cssSelector": [".tldr", "article > p:first-of-type", "h1"]
}

schema.org define SpeakableSpecification como indicando "seções de um documento destacadas como particularmente adequadas para serem lidas em voz alta" (schema.org). A lista de seletores segue uma ordem de preferência: o bloco GEO TL;DR, se o GEO estiver ativado; depois, o primeiro parágrafo do artigo; e, por fim, o H1. A consequência prática é que aquilo que um leitor vê primeiro também é o que uma máquina trata como resumo — uma página que começa com contexto, em vez de uma resposta, declara o contexto como seu resumo.

O que acontece quando a marcação está errada#

Nada no Docsbook valida o grafo antes de ele ser publicado. Não há um linter de esquema no caminho de renderização, e audit_geo — a ferramenta que verifica o acesso dos rastreadores, a renderização no servidor e llms.txt — não inspeciona JSON-LD de forma alguma. O que quer que os extratores tenham produzido é o que vai para a página. Vale conhecer quatro modos de falha:

• O detector não encontrou nada. O resultado mais comum e menos visível: o AEO está ativado, a página tem uma seção com aparência de FAQ e nenhum FAQPage aparece. Quase sempre o problema é o nível do título — o detector lê seções H2 e perguntas H3, portanto uma FAQ escrita com seções H3 e perguntas H4 não produz nada.
• O detector encontrou elementos demais. Qualquer H3 que termine em ? se torna uma pergunta de FAQ em qualquer parte do documento, incluindo um título retórico em um texto. O resultado é uma marcação válida que descreve uma página que não é uma FAQ, o que é um problema de política, não de sintaxe — as diretrizes do Google exigem que "Seus dados estruturados devem ser uma representação verdadeira do conteúdo da página" (Google). Reformule o título como uma afirmação e ele deixará de corresponder.
• HTML bruto em uma resposta interrompe o bloco. O texto da resposta é copiado literalmente para o JSON. Uma sequência </script> literal dentro de uma resposta de FAQ encerra o elemento JSON-LD prematuramente, e todos os objetos posteriores são perdidos. Mantenha HTML bruto fora das respostas de FAQ; use o Markdown usado no restante da página.
• A página é servida em um domínio personalizado. Um espaço de trabalho em seu próprio domínio é renderizado por um caminho diferente que emite um TechArticle simples e nada mais — sem breadcrumb, sem FAQPage, sem HowTo, sem speakable, independentemente do que o botão de AEO indicar. Verifique o endereço *.docsbook.io antes de concluir que o detector falhou.

Verifique com o Teste de resultados avançados do Google ou com o Validador de marcação de esquema. Observe o que um resultado verde significa e não significa atualmente: BreadcrumbList ainda é um resultado avançado compatível, enquanto FAQPage e HowTo são esquemas schema.org válidos que o Google não renderiza mais — consulte as limitações do AEO.

Limites e questões em aberto#

• TechArticle não é um dos três tipos que o Google nomeia para o resultado avançado de artigo. A documentação do Google diz que "os objetos Article devem ser baseados em um dos seguintes tipos do schema.org: Article, NewsArticle, BlogPosting" (Google, artigo). TechArticle é um subtipo do schema.org de Article — "Um artigo técnico - Exemplo: tópicos de instruções (tarefas), procedimentos passo a passo, solução de problemas processual, especificações" (schema.org) — e é a descrição precisa de uma página de documentação. A documentação também não informa se o Google considera um subtipo elegível para o resultado avançado de artigo. Escolhemos a precisão em vez de fazer suposições.
• Os detectores de FAQ e How-to reconhecem apenas inglês e russo. Os títulos das seções e o verbo de procedimento são correspondidos com base nesses dois idiomas. Uma página de FAQ em alemão ou japonês não produz nenhum FAQPage, a menos que seus títulos H3 terminem em ?.
• As respostas contêm apenas prosa. Tudo entre um título de pergunta e o próximo título é concatenado e cortado em 1.000 caracteres — tabelas, blocos de código e imagens acabam como seu código-fonte bruto dentro do texto da resposta ou são truncados no meio. Mantenha as respostas de FAQ em algumas frases.
• Não há registro da quantidade do que foi emitido em lugar algum. Não existe painel, registro ou API que informe quantas perguntas FAQPage ou objetos HowTo uma determinada página produziu. Visualize o código-fonte ou use um validador.

Relacionado#

• AEO — o que um mecanismo de respostas precisa e o que a marcação ainda pode proporcionar
• Regras de conteúdo para mecanismos de respostas — as regras de prosa que determinam se o trecho será selecionado
• GEO — o bloco TL;DR que o seletor speakable prefere
• SEO — meta tags, sitemap e URLs canônicas
• Widgets de conteúdo — as regiões de stepper e acordeão que os detetores entendem