用 Algolia DocSearch 輕鬆實現文件全站搜尋

田勇發表於2018-05-24
Go

話說，有兩件事能讓程式設計師抓狂，一是寫文件，二是看別人的程式碼發現沒寫文件……

沒錯，我們程式設計師就是這麼“雙標”。 :smile:

不過麻煩歸麻煩，出來混，文件還是要寫的，不然哪天回頭翻自己的專案，連自己都不知道寫了個啥，就很尷尬了。當然，文件通常是為別人寫的，特別是一些工具類的庫或者開源軟體，從最簡單的 readme，到成體系的線上 wiki，再到自建線上文件網站，這大概是很多開源作者都有過的歷程。

而對於線上文件網站，搜尋功能能讓查閱文件更加輕鬆，我也一直想著為自己的文件站搞個搜尋功能，但看完一些全文搜尋工具的教程後給整懵逼了，也遲遲沒正式動手。直到最近發現了這貨 —— Algolia DocSearch，前後不到 3 小時（包括申請時等待的時間）就弄好了。

了卻心頭大事後，也驚異於它好用，簡直是難得的良心軟體。如此幸事，豈能不裝一逼？……

Algolia DocSearch 的基本原理和主要優勢

相對於其它一些全文搜尋方案，Algolia DocSearch 的主要優勢在於它是專門針對線上文件搜尋這一需求的。不需要繁瑣的配置，也不需要自己有資料庫等軟硬體支援，而只需在自己網站中插入少量程式碼就可以實現強大的文件搜尋功能了。

根據官方的說明，在你通過申請後，其伺服器會定期抓取（免費使用者抓取週期是 24 小時）你的網站內容並分析，對文件的各級標題、段落等內容建立索引，這樣，在網站中加入搜尋框之後，使用者輸入關鍵時是便可以請求 DocSearch 的介面並顯示搜尋結果了。這些請求、結果顯示相關的邏輯都封裝好了，你要做的只是要按要求插入程式碼、樣式以及那個搜尋框。

官方網站中的原理示意圖

實現步驟

  1. 在 Algolia DocSearch 官網 填寫自己的文件網站的地址和郵箱進行申請

    DocSearch 可以免費使用，而且不用註冊，因為他們覺得，任何人都應該能夠有能力構建方便搜尋的文件（可以說相當有情懷吧）。當然，也有收費的服務可供選用，差異在於技術支援和請求頻率限制等方面不同。

  2. 收到確認郵件並確認

    提交申請之後不久，你所填寫的郵箱就會收到一封詢問郵件。裡面說明你的網站技術上是否支援寫用 DocSearch。如果支援，還會詢問你是否能修改原始碼向其中注入需要的程式碼。你需要回復郵件進行確認。

  3. DocSearch 對你的文件網站首次爬取頁面資料，並向你傳送需要注入的程式碼及相關操作指導。

    第 2 和 第 3 步都需要對方人工處理，而且根據你的網站複雜程式，需要等待的時間會有差異，不過就我個人經驗而言還是很快的。前後不到兩個小時。

    郵件內容大致如下：

    郵件

  4. 根據第 3 步裡收到的郵件提示，修改網站程式碼

    可以看到，郵件主要包括 apiKey 等配置資訊，而且對於如何使用也描述得非常清楚了。系統甚至分析出我網站 url 中使用了 v1_6 和 v2_0 區分不同版本的文件，併為此提供相關的引數 algoliaOptions: { 'facetFilters': ["version:$VERSION"] }, 以及詳細使用例子說明，簡直無微不至，催人尿下……

    因為自己網站用 vue 單檔案元件寫的，所以我選擇使用 npm 包，而並沒有完全照著郵件裡來，但這實質是一樣的。

    首先，安裝 docsearch.js 包

    yarn add -D docsearch.js

    然後，修改文件頁面元件，加入搜尋輸入框和 docsearch 初始化程式碼

    <template>
  <input
    v-show="$route.path.indexOf('/doc') === 0"
    type="text"
    class="search-input"
    id="search_input"
    placeholder="搜尋文件"
  >
</template>

<script>
import 'docsearch.js/dist/cdn/docsearch.min.css'
import docsearch from 'docsearch.js'

export default {
  mounted () {
    docsearch({
      apiKey: 'feb33c2506cdece7f0267859a856767a',
      indexName: 'wevue',
      inputSelector: '#search_input',
      algoliaOptions: { 'facetFilters': ['version:v2_0'] },
      debug: false // Set debug to true if you want to inspect the dropdown
    })
  }
}
</script>

    注意：上面只是最簡單的示例。實際上使用可以更靈活，例如裝搜尋框封裝成一個元件，若有興趣，可前往 we-vue 檢視實際使用情況。

    最後根據自己的喜好及需要，調整下搜尋框及搜尋下拉彈出層的樣式，就完工了。下面是最終效果。

    doc_search_example

總結

Algolia DocSearch 可以說真如其官網描述的那樣，算是目前構建可線上搜尋文件的最簡單的方式之一了。你只需要關注文件本身，進行少量的配置，其它的 Algolia 全包了。另外，Algolia 還有一些其它優秀產品及服務，諸位可前往官網自行探索。

本文以自己的專案為例，但 Aloglia DocSearch 適合很多型別的網站，使用 Vue.js 官網這類用 HEXO 構建的靜態站，又或者像 Easywechat 一樣用 Laravel 開發的動態網站（事實上自己早前曾向超哥安利過 DocSearch, 然後竟然真被用上了 :smile: ）。有了搜尋功能之後，使用者能更方便有找到自己想要的資訊，當然，網站的格調也極大的提升了！

相關文章