2020 年 5 月 18 日

如何在您的文件中整合相關的搜尋列

Clémentine UrquizarMeilisearch 工程主管

How to integrate a relevant search bar to your documentation

在您的文件中整合相關的搜尋列

您可能已經注意到我們的文件中的搜尋列。

MeiliSearch 文件搜尋列示範

您可能也想在您自己的文件中加入相同的搜尋列！

本教學將引導您完成為您的文件建立相關且強大的搜尋列的步驟 🚀

執行 MeiliSearch 實例
抓取您的內容
整合搜尋列

執行 MeiliSearch 實例

首先，您需要抓取您的文件內容並將其推送到 MeiliSearch 實例中。

您可以使用 curl 在您的電腦上安裝並執行 MeiliSearch。

$ curl -L https://install.meilisearch.com | sh
$ ./meilisearch --master-key=myMasterKey

還有其他安裝 MeiliSearch 的方法。

MeiliSearch 是開源的，可以在您的伺服器或任何雲端供應商上執行。

注意：您在後續步驟中提供的 Host URL 和 API 金鑰對應於此 MeiliSearch 實例的憑證。
在上面的範例中，Host URL 是 https://127.0.0.1:7700，API 金鑰是 myMasterKey。

抓取您的內容

Meili 團隊提供並維護一個抓取工具，以自動讀取您網站的內容並將其儲存到 MeiliSearch 中的索引。

設定檔

抓取工具需要一個設定檔，以了解您要抓取的內容，這可以透過提供選擇器（例如 HTML 標籤）來完成。

以下是一個基本設定檔的範例

{
  "index_uid": "docs",
  "start_urls": ["https://www.example.com/doc/"],
  "sitemap_urls": ["https://www.example.com/sitemap.xml"],
  "stop_urls": [],
  "selectors": {
    "lvl0": {
      "selector": ".docs-lvl0",
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": {
      "selector": ".docs-lvl1",
      "global": true,
      "default_value": "Chapter"
    },
    "lvl2": ".docs-content .docs-lvl2",
    "lvl3": ".docs-content .docs-lvl3",
    "lvl4": ".docs-content .docs-lvl4",
    "lvl5": ".docs-content .docs-lvl5",
    "lvl6": ".docs-content .docs-lvl6",
    "text": ".docs-content p, .docs-content li"
  }
}

index_uid 欄位是您的 MeiliSearch 實例中儲存您網站內容的索引識別碼。如果索引不存在，抓取工具將會建立一個新的索引。

在此範例中，docs-content 類別是文字內容的主要容器。大多數情況下，此標籤是 <main> 或 <article> HTML 元素。

lvlX 選擇器應使用標準標題標籤，如 h1、h2、h3 等。您也可以使用靜態類別。為這些元素設定唯一的 id 或 name 屬性。

此主要文件容器之外的每個可搜尋的 lvl 元素（例如，在側邊欄中）都必須是 global 選擇器。它們將會被全域選取並注入到從您的頁面建立的每個文件中。

如果您使用 VuePress 作為您的文件，您可以查看我們在生產環境中使用的設定檔。在我們的案例中，主要容器是 theme-default-content，而標題和副標題的選擇器是 h1、h2...

執行抓取工具

您可以使用 Docker 執行抓取工具。在第一步設定本機 MeiliSearch 實例後，我們執行：

$ docker run -t --rm 
    --network=host 
    -e MEILISEARCH_HOST_URL='https://127.0.0.1:7700' 
    -e MEILISEARCH_API_KEY='myMasterKey' 
    -v <absolute-path-to-your-config-file>:/docs-scraper/config.json 
    getmeili/docs-scraper:latest pipenv run ./docs_scraper config.json

注意：如果您不想使用 Docker，這裡有其他執行抓取工具的方法。

<絕對路徑到您的設定檔> 應該是您在上一步定義的設定檔的絕對路徑。

您必須提供的 API 金鑰應該具有將文件新增到您的 MeiliSearch 實例的權限。在生產環境中，我們建議提供私密金鑰而不是主金鑰，因為它更安全，並且具有執行此類請求的足夠權限。

更多關於MeiliSearch 驗證。

提示：我們建議在每次部署您的文件時都執行抓取工具，如同我們對 MeiliSearch 的文件所做的一樣。

整合搜尋列

如果您的文件不是 VuePress 應用程式，您可以跳過「適用於 VuePress 文件」部分，直接前往「適用於所有類型的文件」。

適用於 VuePress 文件

如果您使用 VuePress 作為您的文件，我們提供一個VuePress 外掛程式。此外掛程式已在 MeiliSearch 文件中實際使用。

VuePress plugin example

VuePress 外掛程式範例

在您的 VuePress 專案中

$ yarn add vuepress-plugin-meilisearch
# or
$ npm install vuepress-plugin-meilisearch

在您的 config.js 檔案中

module.exports = {
  plugins: [
    [
      "vuepress-plugin-meilisearch",
      {
        "hostUrl": "<your-meilisearch-host-url>",
        "apiKey": "<your-meilisearch-api-key>",
        "indexUid": "docs"
      }
    ],
  ],
}

hostUrl 和 apiKey 欄位是 MeiliSearch 實例的憑證。根據本教學，它們分別是 https://127.0.0.1:7700 和 myMasterKey。

indexUid 是您的 MeiliSearch 實例中儲存您網站內容的索引識別碼。它已在設定檔中定義。

這三個欄位是必要欄位，但還有更多可選欄位可供您自訂搜尋列。

警告：由於設定檔是公開的，我們強烈建議在生產環境中提供 MeiliSearch 公開金鑰，這足以執行搜尋請求。

閱讀更多關於MeiliSearch 驗證。

適用於所有類型的文件

如果您沒有使用 VuePress 作為您的文件，我們提供一個前端 SDK，以將強大且相關的搜尋列整合到任何文件網站。

docs-searchbar.js example

docs-searchbar.js 範例

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docs-searchbar.js@{version}/dist/cdn/docs-searchbar.min.css" />
  </head>

  <body>
    <input type="search" id="search-bar-input">
    <script src="https://cdn.jsdelivr.net/npm/docs-searchbar.js@{version}/dist/cdn/docs-searchbar.min.js"></script>
    <script>
      docsSearchBar({
        hostUrl: '<your-meilisearch-host-url>',
        apiKey: '<your-meilisearch-api-key>',
        indexUid: 'docs',
        inputSelector: '#search-bar-input',
        debug: true // Set debug to true if you want to inspect the dropdown
      });
    </script>
  </body>
</html>

hostUrl 和 apiKey 欄位是 MeiliSearch 實例的憑證。根據本教學，它們分別是 https://127.0.0.1:7700 和 myMasterKey。

indexUid 是您的 MeiliSearch 實例中儲存您網站內容的索引識別碼。它已在設定檔中定義。
inputSelector 是 HTML 搜尋輸入標籤的 id 屬性。

警告：我們強烈建議在生產環境中提供 MeiliSearch 公開金鑰，這足以執行搜尋請求。
閱讀更多關於MeiliSearch 驗證。

此程式庫的預設行為非常適合文件搜尋列，但您可能需要一些自訂設定。

注意：如需更具體的範例，您可以查看這個基本 HTML 檔案或這個更進階的 Vue 檔案。

下一步是什麼？

現在，您的網站上應該有一個可以運作的搜尋引擎，恭喜您！🎉

如果您現在想在生產環境中執行 MeiliSearch，您可以查看本教學！