版本：3.5.2

搜尋

您可以使用以下幾種方式將搜尋加入網站

🥇 Algolia DocSearch（官方）
👥 Typesense DocSearch
👥 本地搜尋
👥 使用自訂 SearchBar 組件

資訊

🥇 Docusaurus 提供對 Algolia DocSearch 一級支援。

👥 其他選項由社群維護：請將 bug 回報至各自的儲存庫。

🥇 使用 Algolia DocSearch

Docusaurus 擁有 Algolia DocSearch 的官方支援。

對於任何開發人員文件檔或技術部落格，此項服務是免費的：只要確定您已經閱讀檢查清單並且申請 DocSearch 程式。

DocSearch 每週爬取您的網站一次（時間表可透過網路介面進行設定），並將所有內容匯總成 Algolia 索引。然後使用 Algolia API 直接從您的前端查詢此內容。

如果您的網站不符合資格享用 DocSearch 的免費主機版本，或者您的網站位於防火牆後並且非公開，那麼您可以執行自己的 DocSearch 爬取程式。

註解

預設情況下，Docusaurus 預設值會產生 sitemap.xml，供 Algolia 爬取程式使用。

從舊版的 Docsearch 開始嗎？

您可以在我們的部落格貼文中了解更多有關從舊版 DocSearch 架構進行遷移的資訊，或是參考 DocSearch 遷移文件檔。

索引設定

您的申請經過核准並部署後，您會收到一封電子郵件，其中包含讓您將 DocSearch 加入專案的所有詳細資訊。您可以從網路介面編輯和管理爬取作業。索引在部署後即可立即使用，因此通常不需要手動設定。

使用建議的爬蟲組態

強烈建議使用我們官方的 Docusaurus v3 爬蟲組態。如果您選擇其他爬蟲組態，我們將無法提供支援。

更新您的爬蟲組態時

爬蟲組態包含 initialIndexSettings，僅在您的 Algolia 索引尚未存在時，才可以使用它來初始化該索引。

如果您更新您的 initialIndexSettings 爬蟲設定，就可以透過介面手動更新索引，但 Algolia 團隊建議您刪除索引，然後重新啟動爬蟲，以使用新的設定完全重新初始化索引。

連結 Algolia

Docusaurus 自己所使用的 @docusaurus/preset-classic 支援 Algolia DocSearch 整合。如果您使用預設標籤，則不需要其他安裝。

不使用 @docusaurus/preset-classic 時的安裝步驟

安裝套件

npm
Yarn
pnpm

npm install --save @docusaurus/theme-search-algolia

yarn add @docusaurus/theme-search-algolia

pnpm add @docusaurus/theme-search-algolia

在 docusaurus.config.js 中註冊佈景主題

docusaurus.config.js
export default {
  title: 'My site',
  // ...
  themes: ['@docusaurus/theme-search-algolia'],
  themeConfig: {
    // ...
  },
};

然後，在您的 themeConfig 中新增一個 algolia 欄位。申請 DocSearch 以取得您的 Algolia 索引和 API 金鑰。

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      // The application ID provided by Algolia
      appId: 'YOUR_APP_ID',

      // Public API key: it is safe to commit it
      apiKey: 'YOUR_SEARCH_API_KEY',

      indexName: 'YOUR_INDEX_NAME',

      // Optional: see doc section below
      contextualSearch: true,

      // Optional: Specify domains where the navigation should occur through window.location instead on history.push. Useful when our Algolia config crawls multiple documentation sites and we want to navigate with window.location.href to them.
      externalUrlRegex: 'external\\.com|domain\\.com',

      // Optional: Replace parts of the item URLs from Algolia. Useful when using the same search index for multiple deployments using a different baseUrl. You can use regexp or string in the `from` param. For example: localhost:3000 vs myCompany.com/docs
      replaceSearchResultPathname: {
        from: '/docs/', // or as RegExp: /\/docs\//
        to: '/',
      },

      // Optional: Algolia search parameters
      searchParameters: {},

      // Optional: path for search page that enabled by default (`false` to disable it)
      searchPagePath: 'search',

      // Optional: whether the insights feature is enabled or not on Docsearch (`false` by default)
      insights: false,

      //... other Algolia params
    },
  },
};

資訊

searchParameters 選項以前在 Docusaurus v1 中稱為 algoliaOptions。

請參閱其官方 DocSearch 文件，以了解可能的數值。

警告

搜尋功能在 Algolia 爬取您的網站之前，將無法可靠運作。

如果搜尋在任何重大變更後都無法運作，請使用 Algolia 儀表板來 觸發新的爬蟲。

情境搜尋

情境搜尋為 預設啟用。

它會確保搜尋結果與目前的語言和版本 相關。

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      contextualSearch: true,
    },
  },
};

讓我們考慮你有 2 個文件版本 (v1 和 v2) 和 2 種語言 (en 和 fr)。

在瀏覽 v2 文件時，返回 v1 文件的搜尋結果會很奇怪。有時候 v1 和 v2 文件很類似，而且你會得到同一個查詢的重複搜尋結果（每個版本一個結果）。

類似地，在瀏覽法文網站時，返回英文文件搜尋結果是很奇怪的。

為了解決這個問題，情境式搜尋功能會了解你在瀏覽特定文件版本和語言，然後會動態地建立搜尋查詢篩選條件。

在 /en/docs/v1/myDoc 上，搜尋結果將只包含英文 v1 文件（+ 其他未分版本的頁面）的結果。
在 /fr/docs/v2/myDoc 上，搜尋結果將只包含法文 v2 文件（+ 其他未分版本的頁面）的結果。

資訊

在使用 contextualSearch: true (預設) 時，會將情境式層面篩選條件和 algolia.searchParameters.facetFilters 所提供的條件合併。

對於特定需求，你可以停用 contextualSearch 並定義你自己的 facetFilters。

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      contextualSearch: false,
      searchParameters: {
        facetFilters: ['language:en', ['filter1', 'filter2'], 'filter3'],
      },
    },
  },
};

參閱相關的 Algolia 分面式文件。

情境式搜尋不起作用嗎？

如果你只有在停用情境式搜尋時，才會取得搜尋結果，這很有可能是因為索引組態問題所造成的。

設定 Algolia 搜尋樣式

預設情況下，DocSearch 會附上一組微調過的佈景主題，這組佈景主題原本就是為易用性所設計，確保顏色和對比符合標準。

你仍然可以重複使用 Docusaurus 的 Infima CSS 變數，透過編輯 /src/css/custom.css 檔案，來設定 DocSearch 的樣式。

/src/css/custom.css
[data-theme='light'] .DocSearch {
  /* --docsearch-primary-color: var(--ifm-color-primary); */
  /* --docsearch-text-color: var(--ifm-font-color-base); */
  --docsearch-muted-color: var(--ifm-color-secondary-darkest);
  --docsearch-container-background: rgba(94, 100, 112, 0.7);
  /* Modal */
  --docsearch-modal-background: var(--ifm-color-secondary-lighter);
  /* Search box */
  --docsearch-searchbox-background: var(--ifm-color-secondary);
  --docsearch-searchbox-focus-background: var(--ifm-color-white);
  /* Hit */
  --docsearch-hit-color: var(--ifm-font-color-base);
  --docsearch-hit-active-color: var(--ifm-color-white);
  --docsearch-hit-background: var(--ifm-color-white);
  /* Footer */
  --docsearch-footer-background: var(--ifm-color-white);
}

[data-theme='dark'] .DocSearch {
  --docsearch-text-color: var(--ifm-font-color-base);
  --docsearch-muted-color: var(--ifm-color-secondary-darkest);
  --docsearch-container-background: rgba(47, 55, 69, 0.7);
  /* Modal */
  --docsearch-modal-background: var(--ifm-background-color);
  /* Search box */
  --docsearch-searchbox-background: var(--ifm-background-color);
  --docsearch-searchbox-focus-background: var(--ifm-color-black);
  /* Hit */
  --docsearch-hit-color: var(--ifm-font-color-base);
  --docsearch-hit-active-color: var(--ifm-color-white);
  --docsearch-hit-background: var(--ifm-color-emphasis-100);
  /* Footer */
  --docsearch-footer-background: var(--ifm-background-surface-color);
  --docsearch-key-gradient: linear-gradient(
    -26.5deg,
    var(--ifm-color-emphasis-200) 0%,
    var(--ifm-color-emphasis-100) 100%
  );
}

自訂 Algolia 搜尋行為

Algolia DocSearch 支援一清單選項，你可以將他們傳遞給 docusaurus.config.js 檔案中的 algolia 欄位。

docusaurus.config.js
export default {
  themeConfig: {
    // ...
    algolia: {
      apiKey: 'YOUR_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      // Options...
    },
  },
};

編輯 Algolia 搜尋元件

如果你想要編輯 Algolia 搜尋的 React 元件，請在 @docusaurus/theme-search-algolia 中交換 SearchBar 元件。

npm
Yarn
pnpm

npm run swizzle @docusaurus/theme-search-algolia SearchBar

yarn swizzle @docusaurus/theme-search-algolia SearchBar

pnpm run swizzle @docusaurus/theme-search-algolia SearchBar

問題排除

這是 Docusaurus 使用者在使用 Algolia DocSearch 時遇到最常見的問題。

沒有搜尋結果

通常看不到搜尋結果，是因為索引設定問題。

如何檢查是否有設定問題？

Docusaurus 使用Algolia faceting 的情境搜尋功能，以建立像以下的動態查詢。

[
  "language:en",
  [
    "docusaurus_tag:default",
    "docusaurus_tag:docs-default-3.2.1",
    "docusaurus_tag:docs-community-current",
    "docusaurus_tag:docs-docs-tests-current"
  ]
]

在 Algolia UI 中，您的索引應允許在欄位中建立分面查詢 docusaurus_tag、language、lang、version、type，就像以下螢幕擷取畫面所示

Algolia index showing appropriate faceting fields

或者，如果您使用 {contextualSearch: false}（我們並不特別推薦）停用情境搜尋，Docusaurus 將不會使用分面查詢，這樣您便會開始看到結果。

使用建議的設定

我們建議具體的爬蟲設定是有理由的。如果您選擇使用其他設定，我們將無法提供支援。

您可以遵循以下步驟修正索引設定問題

使用建議的爬蟲設定
透過 UI 刪除您的索引
透過 UI 觸發新的爬取
檢查您的索引是否使用適當的分面欄位重新建立：docusaurus_tag、language、lang、version、type
您現在可以看到搜尋結果，即使已啟用情境搜尋

支援

Algolia DocSearch 團隊可以協助您找出網站上的搜尋問題。

您可以透過他們的支援頁面或Discord連絡 Algolia。

Docusaurus 也在Discord上有一個#algolia頻道。

👥 使用 Typesense DocSearch

Typesense DocSearch 的運作方式與 Algolia DocSearch 類似，只不過您的網站會索引到 Typesense 搜尋叢集中。

Typesense 是一個開放原始碼的即時搜尋引擎，您可以

自行託管在您自己的伺服器上或
使用已管理的 Typesense Cloud 服務。

與 Algolia DocSearch 類似，有兩個元件

typesense-docsearch-scraper - 會擷取您的網站並將資料索引至 Typesense 叢集。
docusaurus-theme-search-typesense - 要加入網站的可視元件搜尋欄。

在此處閱讀如何執行 typesense-docsearch-scraper 以及如何在您的 Docusaurus 站點中安裝搜尋欄的逐步操作教學。

👥 使用本機搜尋

您可以使用本機搜尋外掛程式，適用於搜尋索引較小且可在使用者造訪您的網站時下載至使用者瀏覽器的網站。

您可以在此處找到社群支援本機搜尋外掛程式清單。

👥 使用自己的搜尋

若要使用自己的搜尋，請在 @docusaurus/theme-classic 中切換 SearchBar 元件

npm
Yarn
pnpm

npm run swizzle @docusaurus/theme-classic SearchBar

yarn swizzle @docusaurus/theme-classic SearchBar

pnpm run swizzle @docusaurus/theme-classic SearchBar

這會在您的專案資料夾中建立 src/theme/SearchBar 檔案。重新啟動您的開發伺服器並編輯元件，您將會看到 Docusaurus 現正使用您自己的 SearchBar 元件。

注意：您也可以從 Algolia SearchBar 切換並在該處建立您自己的搜尋元件。

🥇 使用 Algolia DocSearch​

索引設定

連結 Algolia​

情境搜尋​

設定 Algolia 搜尋樣式

自訂 Algolia 搜尋行為

編輯 Algolia 搜尋元件

問題排除

沒有搜尋結果​

支援​

👥 使用 Typesense DocSearch​

👥 使用本機搜尋​

👥 使用自己的搜尋​