Docsbookがページのheadを構築する仕組み

このページでは、Docsbookがホストするすべてのページについて、コードが解決される順序に沿って、<head>とsitemap.xmlに何を配置するかを説明します。これにより、curlを実行しなくても出力を予測できます。何が自分にとって有用で、何を有効にする必要があるかについては、SEOインデックスから始めてください。

ページ上のタイトルとは何で、どこから取得されますか？#

Docsbook ページの <title> は3つの手順で解決されます。最初に一致したものが採用されます。

順序	ソース	最初に採用される理由
1	フロントマターの `title:`	ページ上で読者に表示される内容を変更せずに編集できる、3つの中で唯一のものです。
2	本文の `# H1`	人間向けにすでに記述されている実際の見出しです。
3	ファイル名から導出されたタイトル	空になることはなく、ページには常にSERP行が存在します。

その後、ワークスペース名が Page title — Workspace としてちょうど1回追加されます。ただし、タイトルにワークスペース名が単独の単語としてすでに含まれている場合は追加されません。"Docsbook" 内の "Docs" は一致とはみなされません。一致箇所の両隣は単語以外の文字でなければならず、ASCII文字ではなくUnicodeの文字と数字を対象に判定されるため、キリル文字やCJKのワークスペース名もラテン文字の名前と同じように一致します。タイトルがワークスペース名だけのページ（サイトのルート）は Workspace — Documentation になります。完成した文字列は絶対タイトルとして出力されるため、サイト全体の %s | Docsbook テンプレートがブランド名を重複して追加することはありません。

翻訳済みページでは、タイトルはキャッシュされた翻訳済みメタデータから取得されます。それ以外の場合は、保存された翻訳済みHTMLの最初の <h1> から取得されるため、中国語のページには中国語のタイトルが表示されます。説明は意図的に元の言語のまま残されます。Docsbook が説明文の翻訳を自動生成することはありません。

メタディスクリプションとは何か、そこから何が取り除かれるのか#

順序: まずフロントマターの description:、次にページ自体の冒頭の段落です。

本文テキストを説明文にできるようにする前に、不要な要素が除去されます。HTMLコメント（ウィジェットマーカーもこれに該当します）、{icon-name} マーカー、見出し、画像、フェンス付きコードとインラインコード、強調記号、生のHTMLタグ、リストの箇条書き記号、引用ブロックのマーカーが取り除かれます。また、MarkdownリンクはURLを文中に引き込むのではなく、リンクテキストに置き換えられます。20文字以下の段落は断片として破棄されます。

同じソースから1回の処理で2つの長さが生成されます。<meta name="description"> 用に160文字、og:description とJSON-LDのdescription 用に400文字です。フロントマターに記述された説明文が両方に使用されます。切り詰める位置は単語の境界となり、予算の後半に文末がある場合は文末を優先します。それ以外の場合、テキストは省略記号で終わります。

ページが正規とするURLはどれですか？#

1ページにつき1つの正規URLがあり、次の順序で決まります：

カスタムドメイン（ワークスペースにある場合）。*.docsbook.io ミラーは、 2つ目のコピーとして存在するのではなく、Disallow: / を提供します。
プロダクト所有の apex パス（Docsbook 自体のドキュメントの場合）。
apex の短縮パス（ショーケースワークスペースの場合）。これは 200 に答えるURLであり、サブドメイン形式からはこのURLにリダイレクトされます。
その他すべての場合は https://<owner>.docsbook.io/<repo>/<path>。

翻訳されたページも同じ4つの分岐をたどりますが、ロケールはルーターが実際に提供する場所に挿入されます。en はプレフィックスなしのURLに戻るよう特別扱いされます。これは、 /en/page と /page がバイト単位で同一のコンテンツを提供し、実際には翻訳されていないページのロケールURLでは原文が表示されるためです。そのため、権威あるURLであると示すのではなく、原文のURLを正規URLとします。

代替言語として提示されるのはどの言語ですか？#

hreflang セットには、ソースURLの x-default と en に加え、1つのエントリが含まれます。有効化された言語のうち、このページが実際に翻訳されている言語ごとに1つずつ追加されます。言語を有効化しただけでは追加されません。翻訳されていないロケールのURLは自身をcanonicalとして指定せず、そのようなメンバーが1つでもあるとクラスター全体が無効になります。noindex を持つページには、宙に浮いたセットではなく、セット自体が付与されません。

サイトマップでは、意図的にページレベルの代替言語を一切出力しません。サイトマップではページごとの翻訳チェックを実行できないため、構築されるセットには有効化されたすべてのロケールが列挙されることになり、ページレベルのセットが回避しようとしているまさにその矛盾を再び引き起こすからです。

すべてのページでは、400文字の長さのOpenGraph（og:title、og:description、 og:url = 正規URL、og:site_name、og:type: article、og:locale）と、 160文字の説明を含むタイプsummary_large_imageのXカードが生成されます。画像はページごとに1200×630で生成され、24時間キャッシュされます。ワークスペースのロックアップ、セクションをアイブロウとして、ページタイトル（64文字で切り詰め、 30文字を超える場合は小さく設定）、説明（130文字で切り詰め）をワークスペースの色で表示します。カスタムドメインではカードは同じ画像で、 apexから絶対URLでリクエストされますが、そこではog:descriptionに400文字の文字列ではなく 160文字の文字列が格納されます。

ページにはどの robots ディレクティブが含まれますか？#

厳密な優先順位で、4つのルールがあります。

条件	出力内容
管理者プレビュー（`?preview=true`）	`noindex, follow`
サイト全体のSEOスイッチがオフ	`noindex, nofollow`
ページのフロントマター `noindex`	`noindex, follow`
その他の場合	`index, follow`

noindex: true、noindex: yes、noindex: 1、および robots: noindex の表記はすべて該当します。その他（未設定、false、index）はインデックス登録を意味します。

robots.txt はホストによって異なります。アペックスドメインでは、Crawl-delay: 10 を含む寛容なワイルドカードルールを提供し、アプリ独自の非コンテンツパスへのアクセスを拒否し、Crawl-delay: 5 で 18 のAIおよび検索クローラーを明示的に指定し、引用価値の低い大量アクセスのクローラー 13 種を完全にブロックし、検出可能なサイトごとに Sitemap: 行を1つずつ記載します。ワークスペースのサブドメインでは、同じボットポリシーに加えて独自の Sitemap: 行を提供します。カスタムドメインでは、Sitemap: 行を含まないボットポリシーを提供します。独自のサイトマップはまだなく、ミラーのサイトマップをクローラーに示すと、すべてのページについて2つ目のホストを宣伝することになるためです。Crawl-delayは配慮であって標準ではありません。RFC 9309 が定義しているのは user-agent、allow、disallow のみであり、Google が追加しているのも sitemap だけです。「crawl-delay などの他のフィールドはサポートされていません」。

sitemap.xml には何が含まれますか？#

所有者ごとにサイトマップを1つ作成し、再構築は1時間に1回までです。インデックス対象の各リポジトリについて、すべての Markdown ファイルを列挙し、リポジトリルートの README をサイトルートに割り当て、それ以外のすべてのファイルをそれぞれのパスに割り当てます。各エントリには次の情報が含まれます：

lastmod — ソースリポジトリから取得した、そのファイルに変更を加えた最後のコミットの日付です。コミット履歴を読み取れない場合に限り、レンダリング時刻が使用されます。
changefreq — weekly。
priority — ランディングページの場合は 0.9、内部ページの場合は 0.7、それらの翻訳の場合は 0.8 / 0.6 です。

翻訳された URL は、翻訳が実際に存在する場合にのみ記載され、ファイルの出力前に重複する URL はまとめられます。ツリーを読み取れないリポジトリは通知なく除外され、残りのサイトマップは引き続き提供されます。500 エラーになるサイトマップは、1ページ分少ないサイトマップよりも大きな問題だからです。

noindex を持つページも引き続き一覧に含まれます。このフラグを認識するにはすべてのページのコンテンツを読み取る必要がありますが、サイトマップの構築では意図的にそれを行いません。ページ独自のディレクティブは到着時に適用されるため、必要なコストは1回のクロール訪問です。

どのような構造化データが出力されますか？#

Docsbookでホストされるサイトでは、すべてのページが3つのノードを含むJSON-LD @graphを出力します：

Organization — ワークスペース、そのURL、GitHubプロフィール、設定されている場合はロゴ。
TechArticle — 見出し、説明、正規URL、ソースリポジトリのコミット履歴から取得したinLanguage、 datePublished、dateModified、作成者、発行者、mainEntityOfPage。
BreadcrumbList — 所有者 → サイト → 各パスセグメント。<link rel="canonical">が使用するものと同じ正規ビルダーから構築されるため、パンくずが正規タグと一致しないホスト名を示すことはありません。

AEOを有効にするとspeakableが追加され、FAQPage / HowToノードは、ページに実際にその構造が含まれている場合にのみ表示されます。 GEOを有効にすると、フロントマターまたは最後のコミットの作成者からPerson作成者が追加されます。

アンカー、レンダリングモード、ホスト#

アンカー。見出しのIDはレンダラー独自のスラッガーによって生成され、Docsbookが提供するすべてのディープリンク（検索結果やAIによる引用など）は、文字列を再生成するのではなく、同じライブラリを呼び出して計算されます。重複する見出しは最初の出現箇所に解決されます。

レンダリングモード。公開ページへの匿名リクエストは、キャッシュされたサーバーレンダリングのルート（24時間のウィンドウ）から提供されます。ログイン済みおよびプレビューのリクエストは動的レンダリングにフォールスルーし、CDNにキャッシュされることはありません。いずれの場合も、クローラーは完全なHTMLを受け取ります。ボットとテキストの間にクライアント側のレンダリング手順が介在することはありません。

カスタムドメインと共有ドメインの違い。カスタムドメインでは、正規URL、タイトル、説明、カード、および TechArticle ノードがすべて存在し、ボットポリシーが適用されます。存在しないものは5つあります。サイト全体のSEOスイッチとページごとの noindex （ページは無条件に index, follow で提供されます）、hreflang セット、 BreadcrumbList と Organization ノード、移動されたページのリダイレクト、そしてGEO シグナルです。TL;DRブロック、表示されるUpdated行、および常にリポジトリ所有者にちなんで名付けられた Person である TechArticle 著者はありません。制限事項を参照してください。

これらのルールの理由（根拠）#

ルール	コンシューマーに対して機能する理由	出典
すべてのページに `<title>` を設定し、ブランド名は1回だけ付加する	Googleはタイトルリンクのソースとしてまず `<title>` を挙げており、`<title>` 要素内の「繰り返しテキストや定型文」を避けるよう警告している	タイトルリンク
ページごとに説明を設定し、サイト全体で1つの文字列を使い回さない	「サイトのすべてのページで同一または類似した説明を使用しても役に立たない」	スニペット
Canonicalは200を返すURLを指し、リダイレクトは使用しない	`rel="canonical"` は「強いシグナル」であり、Googleはcanonicalページに自己参照canonicalを設定することを推奨している	重複URLの統合
`hreflang` には実際に翻訳されたロケールのみを記載する	「ページXがページYにリンクする場合、ページYはページXにリンクし返さなければならない…そうでなければ、これらのアノテーションは無視される可能性がある」	ローカライズ版
実際のコミット日を `lastmod` として使用する	Googleは `<lastmod>` を「一貫して検証可能な形で正確である」場合に使用する	サイトマップの作成
ページに存在するコンテンツにのみ構造化データを使用する	「ユーザーに表示されない情報について構造化データを追加しない」	構造化データの概要
クライアントサイドではなくサーバーでHTMLをレンダリングする	Googleはキュー内でJavaScriptをレンダリングするため、ページが「数秒間…その状態に留まる可能性があるが、さらに時間がかかることもあり」、また「すべてのボットがJavaScriptを実行できるわけではない」	JavaScript SEOの基本
1200×630のカード画像	「少なくとも1200 x 630ピクセルの画像を使用する」、1.91:1の比率に近い	シェア画像

制限と未解決の問題#

priority と changefreq は装飾です。 Docsbook がこれらを出力しますが、Google は明確に「Google は <priority> と <changefreq> の値を無視します」と述べています。 sitemaps.org プロトコルでは、priority は「URL の順位に影響を与える可能性は低い」とも記載されています。 Google に対してはコストもメリットもありませんが、他の検索エンジンについては異なります。
TechArticle は Google の Article リッチリザルトの対象リストに含まれていません。 これは実在する schema.org の型（Thing > CreativeWork > Article > TechArticle）であり、コンテンツを正確に表現しますが、Google の Article ドキュメントでは、オブジェクトは「次の schema.org 型のいずれかに基づいている必要があります: Article、NewsArticle、BlogPosting」と記載されています。このノードは正確な説明として扱い、リッチリザルトの対象資格とは見なさないでください。また、構造化データがランキング要因であることも文書化されていません。Google の導入では、構造化データによってページが表示を強化するための対象となると説明されているだけで、ランキングについては何も述べていません。
未解決の疑問: 400 文字の og:description にどのようなメリットがあるのか。 Docsbook は、 <meta description> にはない余地がタグにあるため、これを生成します。取得した情報源のいずれにも、特定のコンシューマーが og:description をどのように切り詰めるかは記載されておらず、 OpenGraph プロトコルにも長さの規定はありません。400 は測定された最適値ではなく、サイト内の選択と考えてください。
カスタムドメインのページでは、インデックス登録の切り替え設定が無視されます。 サイト全体の SEO スイッチとページごとの noindex は Docsbook がホストするホスト上でのみ適用されます。カスタムドメインでは、ページは常に index, follow として提供されます。/sitemap.xml もそこで解決されないため、その robots.txt には Sitemap: 行が含まれず、Docsbook を通じて名前変更されたページも共有ドメイン上でのみリダイレクトが維持されます。現在、カスタムドメイン上でページをインデックスから除外するには、公開リポジトリに含めないでください。
1 つのサイトマップは 50,000 URL / 50 MB に制限されます。これは sitemaps.org プロトコルおよび Google 独自の制限によるものです。Docsbook は所有者ごとに 1 つのサイトマップを生成し、分割しません。この上限を超えた所有者には、現在対応していません。