メインコンテンツへスキップ
バージョン: レガシー (v1.x - v2.x)

必須設定

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。 エラーを見つけましたか？ 問題を報告 →

このセクションでは、DocSearchインデックスの構築方法に関する詳細を基に、クロールを最適化するベストプラクティスを紹介します。当社クローラーがウェブサイトから最適な検索体験を構築するためには、以下の仕様を採用することが必須です。ウェブサイトを更新しこれらのルールに従う必要があります。

注：対応ツールで生成されたウェブサイトの場合、既に要件を満たしているため変更は不要です。

汎用設定の例​

{
  "index_name": "example",
  "start_urls": ["https://www.example.com/doc/"],
  "sitemap_urls": ["https://www.example.com/sitemap.xml"],
  "stop_urls": [],
  "selectors": {
    "lvl0": {
      "selector": ".DocSearch-lvl0",
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": {
      "selector": ".DocSearch-lvl1",
      "global": true,
      "default_value": "Chapter"
    },
    "lvl2": ".DocSearch-content .DocSearch-lvl2",
    "lvl3": ".DocSearch-content .DocSearch-lvl3",
    "lvl4": ".DocSearch-content .DocSearch-lvl4",
    "lvl5": ".DocSearch-content .DocSearch-lvl5",
    "lvl6": ".DocSearch-content .DocSearch-lvl6",
    "text": ".DocSearch-content p, .DocSearch-content li"
  },
  "custom_settings": {
    "attributesForFaceting": ["language", "version"]
  },
  "nb_hits": "OUTPUT OF THE CRAWL"
}

明確なレイアウトの概要​

これらのベストプラクティスを実装したウェブサイトはシンプルで明快な構成になります。以下のような外観が理想的です：

Recommended layout for your page

青色のメイン要素が.DocSearch-contentコンテナになります。詳細は後続のガイドラインで説明します。

セレクタとして適切なクラスを使用​

コンテンツの役割を特定するため、スタイル変更を含まない静的クラスを追加できます。これらの専用クラスにより、ドキュメントから「入力しながら学べる」優れた検索体験を構築できます。

  • テキストコンテンツのメインコンテナに静的クラスDocSearch-contentを追加（通常は<main>または<article>HTML要素）

  • メインドキュメントコンテナ外の検索可能なlvl要素（サイドバーなど）はglobalセレクタにする必要があります。これらはグローバルに収集され、ページから生成される全レコードに注入されます。レベル値は重要であり、HTMLフローに沿って増加する必要がある点に注意してください。レベルX（lvlX）はX > YとなるレベルYの後に出現する必要があります。

  • lvlXセレクタは標準見出しタグ（h1, h2, h3など）か静的クラスを使用します。後述するように、これらの要素には一意のidまたはname属性を設定してください。

  • lvlXセレクタに一致するDOM要素には一意のidまたはname属性が必要です。これにより一致要素の正確な位置までスクロールするリダイレクトが可能になります。

  • テキスト要素（textセレクタ）は全て<p>または<li>タグで囲んでください。コンテンツは原子的に分割され小さな単位である必要があります。要素のネストによる重複発生に注意してください。

  • ここで紹介されているHTMLフロー全体の一貫性を維持してください。

メタタグによるグローバル情報の追加​

当社クローラーはDocSearch専用メタタグから情報を自動抽出します：

<meta name="docsearch:language" content="en" />
<meta name="docsearch:version" content="1.0.0" />

クロールはこれらのmetaタグのcontent値を、ページから抽出された全レコードに追加します。メタタグのnameはdocsearch:$NAMEパターンに従う必要があります。$NAMEは全レコードに設定される属性名です。

これらの属性はfacetFiltersとして変換しUIからフィルタリング可能です。AlgoliaインデックスのattributesForFaceting設定と、DocSearchのcustom_settings設定経由での設定PR提出が必要です。

"custom_settings": {
  "attributesForFaceting": ["language", "version"]
}

これによりメタタグの値でフィルタリング可能になります。以下の例ではこれらのページからレコードを取得するJavaScriptスニペットの更新方法を示します。

docsearch({
  […],
  algoliaOptions: {
    'facetFilters': ["language:en", "version:1.0.0"]
  },
  […],
});

docsearch:versionメタタグはカンマ区切りトークンのセットにでき、各トークンはページに関連するバージョンです。これらのトークンはSemVer仕様に準拠するか、英数字のみを含む必要があります（例：latest, next）。ファセットフィルターとして、これらのバージョントークンは大文字小文字を区別しません。

例えば、以下のメタタグがあるページから抽出された全レコード：

<meta name="docsearch:version" content="2.0.0-alpha.62,latest" />

これらのレコードのversion属性は次のようになります：

version:["2.0.0-alpha.62" , "latest"]

あると便利な設定​

  • ウェブサイトには更新されたサイトマップが必要です。これはクローラーに更新対象を認識させる重要な要素です。ご安心ください、埋め込みハイパーリンクを通じて優れたコンテンツを発見するため、引き続きサイトをクロールします。

  • すべてのページには完全なコンテキストが含まれている必要があります。グローバル要素の活用が有効です（上記参照）。

  • ドキュメントコンテンツがクライアントサイドのJavaScriptレンダリングなしでも利用可能であることを確認してください。JavaScriptが必須の場合は設定でjs_render: trueを設定する必要があります。

ご質問は？Discordでご連絡いただくか、サポートチームまでお知らせください。