用 Algolia DocSearch 輕鬆實現文檔全站搜索

話說，有兩件事能讓程序員抓狂，一是寫文檔，二是看別人的代碼發現沒寫文檔……

沒錯，咱程序員就是這麼「雙標」。

不過麻煩歸麻煩，出來混，文檔仍是要寫的，否則哪天回頭翻本身的項目，連本身都不知道寫了個啥，就很尷尬了。固然，文檔一般是爲別人寫的，特別是一些工具類的庫或者開源軟件，從最簡單的 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 查看實際使用狀況。

   最後根據本身的喜愛及須要，調整下搜索框及搜索下拉彈出層的樣式，就完工了。下面是最終效果。

   

總結

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

本文以本身的項目爲例，但 Aloglia DocSearch 適合不少類型的網站，使用 Vue.js 官網這類用 HEXO 構建的靜態站，又或者像 Easywechat 同樣用 Laravel 開發的動態網站（事實上本身早前曾向超哥安利過 DocSearch, 而後居然真被用上了 ）。有了搜索功能以後，用戶能更方便有找到本身想要的信息，固然，網站的格調也極大的提高了！