Docsbook
概要

構造化された回答

Docsbook は、ドキュメントページごとに <script type="application/ld+json"> 要素を 1 つ出力します。複数の独立した script タグではなく、リンクされたオブジェクトの単一の配列である schema.org @graph を格納するため、ページ上のすべてのオブジェクトが 1 つのコンテキストを共有し、@id によって相互に参照できます。

このページでは、そのグラフに含まれる内容、各オブジェクトが表示されるために Markdown で満たす必要がある条件、そして失敗した場合の状態を正確に説明します。

グラフには何が含まれ、何によって有効になるのか#

オブジェクト 表示 条件
Organization 常時 プロジェクトの所有者。sameAs は GitHub アカウントを指し、ワークスペースにそれがある場合は logo を使用
TechArticle 常時 ページ自体: headline、name、description、url、inLanguage、datePublished、dateModified、author、publisher、mainEntityOfPage
BreadcrumbList 常時 ワークスペースのホームからページまでの経路
Person（author として） GEO が有効 frontmatter の author:、それがなければそのファイルの最終コミットの作成者。GEO が無効の場合、author は Organization への @id 参照
speakable AEO が有効 無条件に TechArticle 内に追加
FAQPage AEO が有効 ページから少なくとも 1 つの質問と回答が得られる
HowTo AEO が有効 ページから 3 つ以上の手順で構成される手順が少なくとも 1 つ得られる

SoftwareApplication はこのグラフの一部ではありません。Docsbook はこれを顧客向けドキュメントではなく、自社のマーケティングページで独自に出力します。もし競合比較で当社について反対の説明を読んだことがあるなら、その型が実際に存在するのはそこです。

日付は front matter ではなく、ファイルの Git 履歴から取得されます。datePublished と dateModified は、そのファイルに変更を加えた最新のコミットから読み取られます。まだコミット履歴のないページには、推測した日付ではなく、どちらのキーも付与されません。

FAQPageを生成するMarkdownの構造は？#

次のいずれかの条件を満たすと、セクションは質問になります。

  1. テキストがFAQ、Frequently asked questions、またはロシア語のЧастые вопросы / Вопросы и ответы / Часто задаваемыеに一致するH2（大文字と小文字を区別しない）。その下にあるすべてのH3は、疑問符で終わっているかどうかにかかわらず、質問になります。
  2. ドキュメント内のどこにあるか、そのセクションに属しているかにかかわらず、?で終わるH3。

回答は、そのH3から次の見出しまでの空でないすべての行です。インラインの*、_、およびバッククォート文字は削除されます。コンテンツウィジェットのマーカー（<!-- widget:accordion -->とその閉じマーカー）は、回答に取り込まれるのではなくスキップされます。これは、FAQは通常アコーディオンとして作成されるためです。

次に、以下の順序で制限が適用されます。末尾の?がない各質問にはそれが追加され、各回答は1,000文字に切り詰められ、質問が3文字以下または回答が10文字以下の場合はペアが除外され、ページに保持される質問は最大20件です。

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

質問ではなく、FAQセクションにも含まれていないH3は、何も生成しません。## Setupの下にある### Install the CLIは正しく無視されます。

どのようなMarkdownの構造でHowToが生成されますか？#

次の3つの条件をすべて満たす必要があります。

  1. How toで始まるH1、H2、またはH3 — またはロシア語のКак。この場合、次の文字は英字または数字であってはならないため、Каким образомは一致しません。
  2. その後に番号付きリストが続く — 1.と1)のどちらも該当します。
  3. リストに少なくとも3つの手順がある。

番号付きリストの各項目がHowToStepになります。そのnameは最初の文で、単語の区切り位置で80文字に切り詰め、末尾に省略記号を付けたものです。そのtextは項目全体で、最大1,000文字です。リンクはアンカーテキストに変換され、インラインの強調は削除されます。フェンス付きコードブロック内のコンテンツは完全に無視されるため、例の中の番号付きリストが手順になることはありません。

1つの手順は最大20ステップ、1ページあたり最大5個のHowToオブジェクトに制限されます。

ステッパーウィジェットは番号付きリストとして扱われます。<!-- widget:stepper -->領域内では、見出しのレベルに関係なく、すべての見出しが次のステップを開始します — ただし、その領域がHowToになるのは、How to / Как見出しによって導入された場合だけです。# Quick startの下にあるステッパーは何も生成しません。

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

2つのステップでは何も生成されません。手順が本当に2つのステップで構成されている場合、それが正しい結果です — しきい値に達するためにリストを水増ししないでください。

生成されたJSON-LDの実際の内容#

これは、上記の2つのMarkdownブロックに対してDocsbook独自の抽出器を実行した出力です。

{
  "@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." }
      ]
    }
  ]
}

抽出器が質問の見出しに対して行ったことに注目してください。Markdown では省略されていた ? を追加しています。そのため、質問形式の H3 は、文として記述した場合でも、マークアップ上では正しく読めます。

パンくずリストに含まれる内容#

パンくずリストは、ワークスペースのホーム → プロジェクトのホーム → パスの各セグメントにつき1項目、という構成です。各セグメントの name は人間が読みやすい形式に変換されます。つまり、.md 拡張子が削除され、ハイフンとアンダースコアがスペースに変換され、各単語の先頭が大文字になります。一方、その item URL は、ページの <link rel="canonical"> が使用するものと同じ正規URLビルダーによって構築されるため、両者が異なるホストを示すことはありません。翻訳されたロケールでは、パンくずリストのURLもそのロケール内で表現されます。

{
  "@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" }
  ]
}

Googleでは、各 ListItem に position、name、item を指定し、リストに少なくとも2つの項目を含めることが求められます（Google、パンくず）。プロジェクトのルートにあるページでは、ホーム項目がちょうど2つ生成され、これは文書化されている最小要件です。

speakableが示す内容#

AEOを有効にすると、TechArticleに以下が追加されます：

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

schema.orgでは、SpeakableSpecificationを「特に読み上げに適しているとして強調されたドキュメントのセクション」を示すものと定義しています（schema.org）。セレクターのリストは優先順位を示しています。GEOが有効な場合はGEO TL;DRブロック、次に記事の最初の段落、最後にH1です。実際には、読者が最初に目にするものが、機械が要約として扱うものでもあります。つまり、回答ではなく背景から始まるページは、その背景を要約として示すことになります。

マークアップが間違っているとどうなるか#

Docsbook では、公開前にグラフを検証する処理はありません。レンダリング経路にスキーマリンターはなく、クローラーのアクセス、サーバーサイドレンダリング、llms.txt をチェックするツールである audit_geo も、JSON-LD をまったく検査しません。抽出処理が生成したものが、そのままページに出力されます。知っておくべき失敗モードは4つあります。

  • 検出対象が何も見つからない。 最も一般的で、最も気づきにくい結果です。AEO は有効で、ページには FAQ のようなセクションがあるのに、FAQPage は現れません。ほとんどの場合、見出しレベルが原因です。検出器は H2 セクションと H3 の質問を読み取るため、H3 セクションと H4 の質問で FAQ を記述すると何も生成されません。
  • 検出対象が多すぎる。 ? で終わる H3 は、本文中の修辞的な見出しを含め、ドキュメント内のどこにあっても FAQ の質問になります。その結果、FAQ ではないページを説明する有効なマークアップが生成されます。これは構文の問題ではなくポリシーの問題です。Google のガイドラインでは、「構造化データはページのコンテンツを正しく表すものでなければなりません」と定められています（Google）。見出しを文に言い換えれば、一致しなくなります。
  • 回答内の生 HTML によってブロックが壊れる。 回答テキストは JSON にそのままコピーされます。FAQ の回答内にリテラルの </script> シーケンスがあると、JSON-LD 要素が途中で終了し、その位置以降のすべてのオブジェクトが失われます。FAQ の回答には生 HTML を入れず、ページの他の部分で使用している Markdown を使ってください。
  • ページがカスタムドメインで配信されている。 独自ドメイン上のワークスペースは別の経路でレンダリングされ、AEO の切り替え設定にかかわらず、TechArticle だけを出力します。パンくずも、FAQPage も、HowTo も、speakable もありません。検出に失敗したと判断する前に、*.docsbook.io のアドレスで確認してください。

Google のリッチリザルトテストまたはSchema Markup Validatorで確認してください。現在、緑色の結果が意味することと意味しないことに注意してください。BreadcrumbList は引き続きサポートされているリッチリザルトですが、FAQPage と HowTo は有効な schema.org であるものの、Google は現在これらを表示していません。詳しくはAEOの制限事項を参照してください。

制限事項と未解決の問題#

  • TechArticle は、Google が記事リッチリザルト用に挙げている3つのタイプのいずれでもありません。 Google のドキュメントには、「Article オブジェクトは、次の schema.org タイプのいずれかに基づいている必要があります: Article、NewsArticle、BlogPosting」と記載されています（Google、記事）。TechArticle は Article の schema.org サブタイプであり、「技術記事 - 例: ハウツー（タスク）トピック、ステップごとの手順、手順に沿ったトラブルシューティング、仕様」（schema.org）を意味します。これはドキュメントページを正確に説明するものです。Google がサブタイプを記事リッチリザルトの対象として扱うかどうかは、そのドキュメントのどこにも明記されていません。私たちは推測よりも正確さを選びました。
  • FAQ と How-to の検出機能が認識するのは英語とロシア語のみです。 セクション見出しと手順を表す動詞は、この2言語に対してのみ照合されます。ドイツ語または日本語の FAQ ページでは、H3 見出しが ? で終わっていない限り、FAQPage は生成されません。
  • 回答は文章のみです。 質問見出しから次の見出しまでのすべての内容が結合され、1,000文字で切り詰められます。そのため、表、コードブロック、画像は回答テキスト内に未加工のソースとして含まれるか、途中で切り詰められます。FAQ の回答は数文程度に収めてください。
  • 生成された内容の件数はどこにも報告されません。 特定のページが生成した FAQPage の質問数や HowTo オブジェクト数を知らせるパネル、ログ、API はありません。ソースを表示するか、バリデーターを使用してください。

Updated

このページは役に立ちましたか？

提供： Docsbook