使用 Meilisearch 在你的 Gatsby 專案中加入搜尋欄
本指南將逐步介紹如何將你的 Gatsby 應用程式的內容新增至 Meilisearch
Nikita 是一個用於自動化部署工作流程的 Node.js 工具組。雖然我們認為它很棒，但我們注意到 Nikita 的文件網站並沒有真正讓使用者能夠快速搜尋並找到他們正在尋找的資訊。不過，Nikita 的內容是開源的，且文件網站是使用 Gatsby 建置的，因此我們決定藉此機會向你展示如何為基於 Gatsby 的專案新增一個不錯的搜尋介面。
在本教學中，我們將安裝 Meilisearch 以及一些其他相依性。然後，我們將複製 Nikita 的 Gatsby 儲存庫，並使用 Meilisearch 為 Nikita 的文件建立索引。最後，我們將在本地版本的 Nikita 文件中新增搜尋使用者介面。
你可以查看最終的程式碼，包括所有準備好在伺服器中執行的內容，在此 github 儲存庫中。
設定
在開始之前，讓我們先快速瀏覽一下你遵循本教學所需的一切。
介紹我們的工具
Gatsby
Gatsby 是一個基於 React 的開源框架，用於靜態網站生成 (SSG)。它結合了 React、GraphQL 和 Webpack 的功能，並提供絕佳的效能、可擴展性和安全性。
需求
為了能夠遵循本教學，你需要以下項目
- 一個開啟的 終端機或命令提示字元
- Node.js >= 14.15.X 且 <= 16.X：這使得在瀏覽器外執行 JS 成為可能
- 你可以使用命令
node --version檢查你目前使用的版本 - 如果你的 Node 版本超出此範圍，我們建議你安裝 nvm 並使用它來存取 Node 14
- 你可以使用命令
- Yarn >= 1.22：Yarn 是一個套件管理器，兼具專案管理器的功能
- Docker：Docker 將協助我們以相對較少的努力建立可用的開發環境
步驟
- 啟動 Meilisearch
- 設定 Gatsby 專案
- 新增 Meilisearch 外掛程式
- 將 Gatsby 應用程式的內容新增至 Meilisearch
- 建置前端
啟動 Meilisearch
有多種方法可以下載並執行 Meilisearch 執行個體。在本指南中，我們將使用 Docker。想要避免本機安裝嗎？試試我們的 Meilisearch 雲端，享有 14 天的免費試用！
在你的電腦中安裝 Docker 後，擷取並執行最新的 Meilisearch 容器映像。若要執行此操作，請開啟你的終端機並使用以下命令
docker pull getmeili/meilisearch:latest docker run -it --rm -p 7700:7700 getmeili/meilisearch:latest ./meilisearch --master-key=masterKey
Meilisearch 將開始在 https://127.0.0.1:7700 上執行。如果一切順利，你的終端機視窗中應該會看到類似以下的內容
設定 Gatsby 專案
準備好 Meilisearch 後，就可以下載 Nikita 的文件了。
在另一個終端機視窗中，導覽至你的工作目錄，然後複製我們將在本指南中使用的 Nikita 專案
git clone https://github.com/adaltas/node-nikita.git
你可以在 docs/content 資料夾內的 markdown 檔案中找到 Gatsby 應用程式的內容。這是 Gatsby 用來產生 Nikita 文件的資料。
| node-nikita 專案的目錄結構 |
新增 Meilisearch 外掛程式並啟動 Gatsby
好的：Meilisearch 和 Gatsby 都已安裝。我們將從安裝所有專案相依性開始。在你的終端機中執行以下命令
cd node-nikita/docs/website yarn
完成後，我們將使用 Yarn 安裝官方 Meilisearch 的 Gatsby 外掛程式
yarn add gatsby-plugin-meilisearch
太棒了！我們已準備好啟動 Gatsby。若要執行此操作，只需在你的主控台中執行以下命令即可
yarn develop
這就是 Nikita 文件網站使用者介面的外觀
將 Gatsby 應用程式的內容新增至 Meilisearch
現在我們已安裝外掛程式，並且 Gatsby 應用程式和 Meilisearch 執行個體都在執行中，事情開始變得有趣了！讓我們設定 gatsby-meilisearch-plugin，使內容可搜尋。
文件網站的主要程式碼位於 docs/website 目錄中。
設定外掛程式
我們需要做的第一件事是將你的 Meilisearch 憑證新增至 Meilisearch Gatsby 外掛程式。開啟 docs/website/gatsby-config.js 並在 plugins 陣列底部新增這段程式碼
{ resolve: 'gatsby-plugin-meilisearch', options: { host: 'https://127.0.0.1:7700', // your host URL goes here apiKey: 'masterKey', // your API key goes here indexes: [], }, },
到目前為止，我們的設定會告知外掛程式在哪裡找到我們的 Meilisearch 執行個體，並提供它讀取 Gatsby 內部內容的憑證。現在，我們需要定義要新增至 Meilisearch 的資料，以及如何新增。這會發生在 indexes 欄位中。此欄位可以視為 Gatsby Meilisearch 外掛程式的核心。
indexes 欄位是由多個索引物件組成的陣列。每個索引物件都必須包含以下欄位：indexUid、query 和 transformer。讓我們檢查一下這些欄位。
indexUid
此欄位包含 Meilisearch 索引的名稱。在本指南中，我們將使用 nikita-api-docs
indexUid: 'nikita-api-docs'
query
此欄位包含外掛程式將用來從 Nikita 文件中擷取內容的 GraphQL 查詢。Gatsby 內建對 GraphQL 的支援，它甚至包含一個捆綁的 GraphQL 工具，可於 (https://127.0.0.1:8000/___graphql) 上存取。你可以在專案的官方文件中閱讀更多關於 GraphQL 的內容。
我們的查詢看起來像這樣。
query: `query MyQuery { allMdx { edges { node { frontmatter { title navtitle description } slug rawBody id } } } }`,
在此查詢中，我們首先表示我們只對 markdown 檔案感興趣，方法是將我們的查詢包在 allMdx 陳述式中。我們可以透過兩個非常有用的工具來做到這一點：gatsby-plugin-mdx 和 gatsby-source-filesystem。
然後，我們指定要包含在索引中的文件欄位：title、navtitle、description、slug、id，最後是 rawBody，也就是文件的原始 markdown 內容。
transformer
這是最後一個設定欄位。它會取得我們使用 query 從 Gatsby 擷取的資料，並將其轉換為 Meilisearch 可以理解的格式。
在我們的案例中，資料看起來會有點像這樣
data = { allMdx: { edges: [ { node: { frontmatter: { title: "Introduction", navtitle: "intro", }, body: "Introduction to the Nikita.js", slug: "/introduction", id: "1", }, }, { node: { frontmatter: { title: "Architecture", navtitle: "architecture", }, body: "Architechture of Nikita.js", slug: "/architecture", id: "2", }, }, ], }, };
此資料看起來很棒，但並非 Meilisearch 可以輕易理解的格式。我們可以透過在 transformer 中新增剖析器函式來變更此狀況
transformer: (data) => { data.allMdx.edges.map(({ node }) => { // Node property has been destructured here return { id: node.id, lvl0: node.frontmatter.title, lvl1: node.frontmatter.navtitle, content: node.body, anchor: node.slug, }; }); }
如此一來，gatsby-plugin-meilisearch 將會取得我們使用查詢擷取的原始資料，並將整個物件轉換為陣列。
// It will return a list of transformed structured object [ { id: "1", lvl0: "Introduction", lvl1: "introduction", content: "Introduction to the Nikita.js", anchor: "/introduction" }, { id: "2", lvl0: "Architecture", lvl1: "architecture", content: "Architechture of Nikita.js", anchor: "/architecture" } ]
將所有內容組合在一起並完成外掛程式設定
如果你一直遵循到現在，你 docs/website/gatsby-config.js 結尾的 gatsby-plugin-meilisearch 設定現在應該看起來像這樣
{ resolve: 'gatsby-plugin-meilisearch', options: { host: 'https://127.0.0.1:7700', apiKey: 'masterKey', batchSize: 1, indexes: [ { indexUid: 'nikita-api-docs', settings: { searchableAttributes: ['lvl0', 'lvl1', 'lvl2', 'content'], }, transformer: (data) => data.allMdx.edges .filter( ({ node }) => node.slug.search('guide') !== -1 || node.slug.search('project') !== -1 || node.slug.search('api') !== -1 ) .map(({ node }) => { // Have to update for versioning const currentVersion = node.slug.substring(0, 8).search('project') === -1 ? '/current' : '' return { id: node.id, lvl0: node.frontmatter.navtitle || node.frontmatter.title || '', lvl1: node.frontmatter.title || node.frontmatter.navtitle || '', lvl2: node.frontmatter.description || '', content: node.rawBody, url: `${currentVersion}/${node.slug}`, } }), query: `query MyQuery { allMdx { edges { node { frontmatter { title navtitle description } slug rawBody id } } } }`, }, ], }, },
我們透過將基本資料和憑證新增至 docs/website/gatsby-config.js 開始 gatsby-plugin-meilisearch 設定。
我們透過指定要搜尋的內容應新增至 nikita-api-docs 索引，使用 GraphQL 查詢來選取用於索引的內容，最後使用 transformer 函式來格式化用於索引的資料，繼續進行設定。
建置專案
gatsby-plugin-meilisearch 將在建置過程中擷取並傳送資料以建立 Meilisearch 索引。若要開始執行，請執行以下命令
yarn build
一旦你的內容正在建立索引，你應該會在終端機中看到訊息
success gatsby-plugin-meilisearch - 0.920s - Documents are send to Meilisearch, track the indexing progress using the tasks uids.
你可以透過前往 https://127.0.0.1:7700、輸入你的 API 金鑰並檢查 Nikita 的文件是否已新增至 Meilisearch 來驗證此狀況。
建置前端
現在資料已建立索引，讓我們建置使用者介面並為我們的終端使用者建立絕佳的搜尋體驗。
在此範例中，我們將使用 docs-searchbar.js。這是一個 Meilisearch 的前端 SDK，提供了一種將搜尋欄輕鬆整合到我們文件網站中的方法。
新增搜尋欄元件
讓我們先在專案的前端目錄中安裝 docs-searchbar.js。
# With Yarn yarn add docs-searchbar.js
完成後，我們可以將 docs-searchbar 模組匯入到 website/src/components/shared/AppBar.js 中，方法是在檔案頂部加入以下程式碼
import 'docs-searchbar.js/dist/cdn/docs-searchbar.css'
接著，我們需要加入一個 useEffect Hook，將 docsSearchBar 函式加入到 AppBar.js 中。將此程式碼加在另一個 useEffect Hook 的下方
useEffect(() => { if(window !== undefined){ const docsSearchBar = require('docs-searchbar.js').default docsSearchBar({ hostUrl: 'https://127.0.0.1:7700', apiKey: 'masterKey', indexUid: 'nikita-api-docs', inputSelector: '#search-bar-input', meilisearchOptions: { limit: 5, }, enhancedSearchInput: true, }) } }, [])
docsSearchBar 函式帶有一些不同的參數
hostUrl和apiKey允許搜尋列存取您的 Meilisearch 實例。indexUid告訴搜尋列它應該搜尋哪個索引。inputSelector是一個選取器，匹配我們的使用者輸入查詢的 HTML 元素。在我們的例子中，它是#search-bar-input。別擔心，我們稍後會在 Gatsby 中加入這個元素。- 最後，
enhancedSearchInput告訴docs-searchbar將主題套用到搜尋框，改善其外觀並使其更方便使用者使用。
剩下的就是將搜尋元素加入到 website/src/components/shared/AppBar.js 中。請記得使用我們設定為 inputSelector 的相同 id。將該元素加在 </Link> 標籤之後
<input type="search" id="search-bar-input" />
這樣就完成了！我們完成了！
測試實作
準備好看看這一切辛苦的成果了嗎？在您的終端機中，重新執行以下指令
yarn develop
然後使用您的瀏覽器存取 https://127.0.0.1:8000。您應該會看到您 NikitaJS 文件本地副本，其中包含一個全新的搜尋列
結論
我們希望這篇文章能讓您愉快地認識新的 Meilisearch Gatsby 外掛程式！
如果您有任何問題，請加入我們的 Discord。有關 Meilisearch 的更多資訊，請查看我們的 Github 儲存庫和我們的官方文件。
如何在 React 應用程式中加入 AI 驅動的搜尋
使用 Meilisearch 的 AI 驅動搜尋來建立 React 電影搜尋和推薦應用程式。
使用 Blazity 建立您的 Next.js Shopify 店面
學習如何使用 Next.js 和 Blazity 商務啟動器來建立 Shopify 店面。
