バージョン: レガシー (v1.x - v2.x)

設定ファイル

非公式ベータ版翻訳

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

DocSearchの設定ファイルは次のような構造です：

{
  "index_name": "example",
  "start_urls": ["https://www.example.com/docs"],
  "selectors": {
    "lvl0": "#content header h1",
    "lvl1": "#content article h1",
    "lvl2": "#content section h3",
    "lvl3": "#content section h4",
    "lvl4": "#content section h5",
    "lvl5": "#content section h6",
    "text": "#content header p,#content section p,#content section ol"
  }
}

`index_name`

ここで指定するのは、レコードが保存されるAlgoliaインデックスの名前です。提供されるapiKeyはこのインデックス専用に制限されており、検索専用キーとなっています。

無料版DocSearchクローラーを使用する場合、indexNameは常に設定ファイル名と同じになります。自身でDocSearchを実行する場合は任意の名前を設定できます。

{
  "index_name": "example"
}

DocSearchスクレイパーが実行されると、一時インデックスが構築されます。スクレイピング完了後、そのインデックスはindex_nameで指定された名前に移動されます（既存のインデックスは置き換えられます）。

デフォルトでは、一時インデックスの名前はindex_nameの値 + _tmp となります。

別の名前を使用するには、環境変数INDEX_NAME_TMPに異なる値を設定します。この変数は.envファイル内でAPPLICATION_IDとAPI_KEYと一緒に設定可能です。

`start_urls`

クローリングを開始するURLのリストを配列で指定します。クローラーはこれらのページからリンク（<a>タグ）を再帰的にたどりますが、別ドメインへのリンクやstop_urlsにマッチするリンクは追跡しません。

{
  "start_urls": ["https://www.example.com/docs"]
}

`selectors_key`によるセレクターのカスタマイズ

URLに応じて詳細なセレクターセットを定義できます。start_urls内でselectors_keyパラメーターを使用してください。

{
  "start_urls": [
    {
      "url": "http://www.example.com/docs/faq/",
      "selectors_key": "faq"
    },
    {
      "url": "http://www.example.com/docs/"
    }
  ],
  […],
  "selectors": {
    "default": {
      "lvl0": ".docs h1",
      "lvl1": ".docs h2",
      "lvl2": ".docs h3",
      "lvl3": ".docs h4",
      "lvl4": ".docs h5",
      "text": ".docs p, .docs li"
    },
    "faq": {
      "lvl0": ".faq h1",
      "lvl1": ".faq h2",
      "lvl2": ".faq h3",
      "lvl3": ".faq h4",
      "lvl4": ".faq h5",
      "text": ".faq p, .faq li"
    }
  }
}

スクレイパーはURLに基づいて適切なサブセットを見つけるため、start_urlsアイテムを順に検査し、最初にマッチした設定を適用します。

URLがhttp://www.example.com/en/api/で、設定が以下の場合：

{
  "start_urls": [
    {
      "url": "http://www.example.com/doc/",
      "selectors_key": "doc"
    },
    {
      "url": "http://www.example.com/doc/faq/",
      "selectors_key": "faq"
    },
   […],
  ]
}

docに関連するセレクターセットのみが適用されます。正しい設定方法は前述の通り逆順に定義することです。

start_urlsアイテムにselectors_keyが定義されていない場合、defaultセットが使用されます。このフォールバック用セレクターセットの設定を忘れないでください。

正規表現の使用

start_urlsとstop_urlsでは正規表現を使用して複雑なパターンを表現できます。正規表現の配列かオブジェクトを定義可能で、オブジェクトの場合は少なくとも到達可能なページを指すurlキーが必要です。

正規表現をオブジェクトで定義する場合、特定のURLパターンに注入されるvariablesキーも定義できます。次の例でこの機能を明確に示します：

{
  "start_urls": [
    {
      "url": "http://www.example.com/docs/(?P<lang>.*?)/(?P<version>.*?)/",
      "variables": {
        "lang": ["en", "fr"],
        "version": ["latest", "3.3", "3.2"]
      }
    }
  ]
}

この構文を使用する利点として、http://www.example.com/docs/en/latestにマッチするページから抽出された全レコードにlang: enやversion: latest属性が付与されます。これによりfacetFiltersでのフィルタリングが可能になります。

次の例はUIが特定の言語とバージョンにマッチする結果をフィルタリングする方法を示しています。

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

カスタムタグの使用

正規表現なしで特定ページにカスタムタグを適用できます。tagsキーにタグリストを追加してください。これらのタグはAlgoliaでファセットとして自動追加され、値に基づくフィルタリングが可能になります。

{
  "start_urls": [
    {
      "url": "http://www.example.com/docs/concepts/",
      "tags": ["concepts", "terminology"]
    }
  ]
}

JSスニペット例：

docsearch({
  […],
  algoliaOptions: {
    'facetFilters': ["tags:concepts"]
  },
});

ページランクの使用

特定ページの重要度を調整します。このパラメーターはページから生成されるレコードの優先度を上げます。高いpage_rankを持つページは低いpage_rankのページより先に表示されます。負の値を含む任意の数値を指定可能です。

{
  "start_urls": [
    {
      "url": "http://www.example.com/docs/concepts/",
      "page_rank": 5
    },
    {
      "url": "http://www.example.com/docs/contributors/",
      "page_rank": 1
    }
  ]
}

この例では、_Concepts_ページから生成されたレコードは_Contributors_ページの結果より優先的に表示されます。

ページ単位のカスタムセレクター使用

ウェブサイトのマークアップがページごとに大きく異なり、汎用的なセレクタを使用できない場合、セレクタを名前空間化し、特定のページに適用するセレクタセットを指定できます。

{
  "start_urls": [
    "http://www.example.com/docs/",
    {
      "url": "http://www.example.com/docs/concepts/",
      "selectors_key": "concepts"
    },
    {
      "url": "http://www.example.com/docs/contributors/",
      "selectors_key": "contributors"
    }
  ],
  "selectors": {
    "default": {
      "lvl0": ".main h1",
      "lvl1": ".main h2",
      "lvl2": ".main h3",
      "lvl3": ".main h4",
      "lvl4": ".main h5",
      "text": ".main p"
    },
    "concepts": {
      "lvl0": ".header h2",
      "lvl1": ".main h1.title",
      "lvl2": ".main h2.title",
      "lvl3": ".main h3.title",
      "lvl4": ".main h5.title",
      "text": ".main p"
    },
    "contributors": {
      "lvl0": ".main h1",
      "lvl1": ".contributors .name",
      "lvl2": ".contributors .title",
      "text": ".contributors .description"
    }
  }
}

ここでは、すべてのドキュメントページがselectors.defaultで定義されたセレクタを使用し、./concepts配下のページはselectors.conceptsを、./contributors配下のページはselectors.contributorsを使用します。

`selectors`

このオブジェクトには、レコード階層を作成するために使用されるすべてのCSSセレクタが含まれます。最大6レベル（lvl0、lvl1、lvl2、lvl3、lvl4、lvl5）とtextを設定できます。

デフォルト設定では、ページのtitleまたはh1をlvl0、h2をlvl1、h3をlvl2、pをtextとしてターゲットしますが、これはマークアップに大きく依存します。

textキーは必須ですが、適切な関連性の深さを確保するため、lvl0、lvl1、lvl2も設定することを強く推奨します。

{
  "selectors": {
    "lvl0": "#content header h1",
    "lvl1": "#content article h1",
    "lvl2": "#content section h3",
    "lvl3": "#content section h4",
    "lvl4": "#content section h5",
    "lvl5": "#content section h6",
    "text": "#content header p,#content section p,#content section ol"
  }
}

セレクタは文字列として渡すか、selectorキーを含むオブジェクトとして渡せます。その他の特殊キーは後述の通り設定可能です。

{
  "selectors": {
    "lvl0": {
      "selector": "#content header h1"
    }
  }
}

グローバルセレクタの使用

セレクタを通じたコンテンツ抽出のデフォルト手法は、HTMLマークアップを上から下へ読み取る方法です。これはヘッダー階層のような半構造化コンテンツで有効ですが、関連情報が同じフローに含まれない場合（タイトルがヘッダーやサイドバーに含まれない場合など）には機能しません。

このような場合、セレクタをグローバルに設定できます。これによりページ全体がマッチ対象となり、そのページから抽出されるすべてのレコードで同じ値が使用されます。

{
  "selectors": {
    "lvl0": {
      "selector": "#content header h1",
      "global": true
    }
  }
}

textセレクタをグローバルに設定することは推奨しません。

デフォルト値の設定

セレクタがページ上の有効な要素にマッチしない場合、フォールバックとしてdefault_valueを定義できます。

{
  "selectors": {
    "lvl0": {
      "selector": "#content header h1",
      "default_value": "Documentation"
    }
  }
}

不要な文字の除去

一部のドキュメントでは、見出しに#や›などの特殊文字を追加しています。これらの文字はスタイリッシュですが意味を持たず、検索結果にインデックスされるべきではありません。

strip_charsキーを設定することで、最終的なインデックス値から除外したい文字リストを定義できます。

{
  "selectors": {
    "lvl0": {
      "selector": "#content header h1",
      "strip_chars": "#›"
    }
  }
}

strip_charsは設定ファイルのルートに直接定義することも可能で、その場合はすべてのセレクタに適用されます。

{
  "strip_chars": "#›"
}

CSSではなくXPathを使用した要素ターゲティング

CSSセレクタはページ要素をターゲットする明確で簡潔な方法ですが、CSSではカスケードを遡れないなどの制限があります。

より強力なセレクタ機構が必要な場合、type: xpathを設定することでXPathを使用したセレクタ記述が可能です。

次の例では、li.chapter.active.doneを検索し、DOMを2レベル遡ってa要素を見つけます。このa要素のコンテンツがlvl0セレクタの値として使用されます。

{
  "selectors": {
    "lvl0": {
      "selector": "//li[@class=\"chapter active done\"]/../../a",
      "type": "xpath",
      "global": true
    }
  }
}

XPathセレクタは可読性が低くなる可能性があります。ブラウザで事前にテストし、期待通りの要素にマッチすることを確認することを強く推奨します。

`custom_settings` オプション

このキーを使用してAlgoliaインデックス設定を上書きできますが、デフォルト設定はすべてのウェブサイトで機能するよう設計されているため、変更は推奨しません。

`custom_settings.separatorsToIndex` オプション

ユースケースの例としてseparatorsToIndex設定があります。デフォルトではAlgoliaはすべての特殊文字を単語の区切り文字として扱いますが、メソッド名などのコンテキストでは、_、/、#などの意味を保持させたい場合があります。

{
  "custom_settings": {
    "separatorsToIndex": "_/"
  }
}

Algolia設定の詳細については公式ドキュメントを参照してください。

`custom_settings.synonyms` オプション

custom_settingsにはsynonymsキーを含めることが可能で、その値は同義語の配列となります。各要素は単一単語の同義語グループを表します。これらの単語は互換的に扱われます。

例：

"custom_settings": {
    "synonyms": [
      [
        "js",
        "javascript"
      ],
      [
        "es6",
        "ECMAScript6",
        "ECMAScript2015"
      ]
    ]
  },

※Algoliaでは高度な同義語機能も利用可能ですが、当クローラーがサポートするのは標準的な単一単語の同義語のみです

`scrape_start_urls` オプション

デフォルトではクローラーはstart_urlsで定義されたページからコンテンツを抽出します。starts_urlsに有用なコンテンツがない場合や他ページと重複している場合は、この値をfalseに設定してください。

{
  "scrape_start_urls": false
}

`selectors_exclude` オプション

CSSセレクターの配列を指定します。これらのセレクターに一致する要素は、データ抽出前にページから削除されます。

目次、サイドバー、フッターなどを除去する場合に有用で、他のセレクター記述を簡素化できます。

{
  "selectors_exclude": [".footer", "ul.deprecated"]
}

`stop_urls` オプション

文字列または正規表現の配列を指定します。クローラーがリンクを訪問する際、この配列のいずれかに一致すると判断した場合、リンクの追跡を行いません。クローラーの訪問範囲を制限する目的で使用します。

重複コンテンツを避けるため、start_urlsにhttp://www.example.com/docs/を設定している場合にhttp://www.example.com/docs/index.htmlを追加するなどが典型的な使用例です。

{
  "stop_urls": ["https://www.example.com/docs/index.html", "license.html"]
}

`min_indexed_level` オプション

デフォルト値は0です。値を上げると、十分なlvlXが設定されていないレコードのインデックス作成を抑制できます。例: min_indexed_level: 2の場合、lvl0、lvl1、lvl2が全て設定されている一時レコードのみがインデックス化されます。詳細な戦略についてはこのセクションで解説。

同一のlvl0やlvl1を持つページが存在するドキュメントで有用です。この場合、全共有レコードをインデックスせず、ページ間で異なるコンテンツのみを保持したい場合に適しています。

{
  "min_indexed_level": 2
}

`only_content_level` オプション

only_content_levelをtrueに設定すると、クローラーはlvlXセレクター用のレコードを作成しません。

このオプション使用時はmin_indexed_levelの設定は無視されます。

{
  "only_content_level": true
}

`nb_hits` 特殊項目

DocSearchによって抽出・インデックスされたレコード数を示します。設定ミスによる意図しない急増/急減を検知するため、当チームが内部でこのキーを監視しています。

nb_hitsはDocSearch実行のたびに自動更新されます。tty環境での実行時は更新前に確認プロンプトが表示されます。プロンプトを回避するには、.envファイルでUPDATE_NB_HITS環境変数をtrue（有効）またはfalse（無効）に設定してください（APPLICATION_IDやAPI_KEYと併せて設定可能）。

このフィールドは手動編集不要です。念のため仕様を記載しています。

サイトマップ

ウェブサイトにsitemap.xmlが存在する場合、DocSearchに通知すればクロール対象ページの定義に活用できます。

`sitemap_urls` オプション

サイトマップファイルのURL配列を指定可能です。この値が設定されている場合、DocSearchはstarts_urlsの全リンクを追跡する代わりに、サイトマップからURLを読み込みます。

{
  "sitemap_urls": ["http://www.example.com/docs/sitemap.xml"]
}

当パラメーターは明示的な定義が必要です（クローラーはrobots.txtを参照しません）

`sitemap_alternate_links` オプション

サイトマップにはURLの代替リンクが含まれる場合があります。これらは同じページの別言語版や異なるURLのバージョンです。デフォルトではDocSearchはこれらのURLを無視します。

これらの代替バージョンもクロールしたい場合は、この設定をtrueにしてください。

{
  "sitemap_urls": ["http://www.example.com/docs/sitemap.xml"],
  "sitemap_alternate_links": true
}

上記の設定と以下のsitemap.xmlがある場合、http://www.example.com/docs/とhttp://www.example.com/docs/de/の両方がクロールされます。

  <url>
    <loc>http://www.example.com/docs/</loc>
    <xhtml:link rel="alternate" hreflang="de" href="http://www.example.com/de/"/>
  </url>

JavaScriptレンダリング

デフォルトではDocSearchはサーバーサイドレンダリングを想定しており、HTMLソースがサーバーから直接返されることを前提としています。コンテンツがフロントエンドで生成される場合は、Seleniumを使用してブラウザをエミュレートするようにDocSearchに指示する必要があります。

※クライアントサイドクロールはサーバーサイドクロールより大幅に遅いため、サーバーサイドレンダリングを有効にするようサイトを更新することを強く推奨します

`js_render` オプション

ウェブサイトがクライアントサイドレンダリングを必要とする場合、この値をtrueに設定してください。これによりDocSearchはSeleniumプロキシを起動してすべてのウェブページを取得します。

{
  "js_render": true
}

`js_wait` オプション

ウェブサイトの読み込みが遅い場合、js_waitを使用してコンテンツ抽出前にページが読み込まれるのを待つ時間（秒単位）を指定できます。

このオプションはクロール時間に大きな影響を与える可能性があるため、代わりにサーバーサイドレンダリングを有効にすることを推奨します。

js_renderがfalseの場合、このオプションは効果を持ちません。

{
  "js_render": true,
  "js_wait": 2
}

`use_anchors` オプション

クライアントサイドレンダリングを使用するウェブサイトでは、完全なURLではなくURLハッシュ（#以降の部分）を活用することがよくあります。

このようなURLを使用するウェブサイトの場合、すべてのコンテンツをインデックスするためにuse_anchorsをtrueに設定する必要があります。

{
  "js_render": true,
  "use_anchors": true
}

`user_agent` オプション

ウェブサイトクロールに使用するユーザーエージェントを上書きできます。デフォルト値は次の通りです：

Algolia DocSearch Crawler

ただし、ブラウザエミュレーションが必要なクロール（js_render=trueの場合）では、user_agentは次のようになります：

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/71.0.3578.98 Safari/537.36

設定ファイルから上書きする例：

{
  "user_agent": "Custom Bot"
}

index_name​

start_urls​

selectors_keyによるセレクターのカスタマイズ​

正規表現の使用​

カスタムタグの使用​

ページランクの使用​

ページ単位のカスタムセレクター使用​

selectors​

グローバルセレクタの使用​

デフォルト値の設定​

不要な文字の除去​

CSSではなくXPathを使用した要素ターゲティング​

custom_settings オプション​

custom_settings.separatorsToIndex オプション​

custom_settings.synonyms オプション​

scrape_start_urls オプション​

selectors_exclude オプション​

stop_urls オプション​

min_indexed_level オプション​

only_content_level オプション​

nb_hits 特殊項目​

サイトマップ​

sitemap_urls オプション​

sitemap_alternate_links オプション​

JavaScriptレンダリング​

js_render オプション​

js_wait オプション​

use_anchors オプション​

user_agent オプション​