用 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 包

1yarn add -D docsearch.js

然后,修改文檔頁面組件,加入搜索輸入框和 docsearch 初始化代碼

 1<template> 2  <input 3    v-show="$route.path.indexOf('/doc') === 0" 4    type="text" 5     6     7    placeholder="搜索文檔" 8  > 9</template>1011<script>12import 'docsearch.js/dist/cdn/docsearch.min.css'13import docsearch from 'docsearch.js'14export default {15  mounted () {16    docsearch({17      apiKey: 'feb33c2506cdece7f0267859a856767a',18      indexName: 'wevue',19      inputSelector: '#search_input',20      algoliaOptions: { 'facetFilters': ['version:v2_0'] },21      debug: false // Set debug to true if you want to inspect the dropdown22    })23  }24}25</script>

注意:上面只是最簡單的示例。實際上使用可以更靈活,例如裝搜索框封裝成一個組件,若有興趣,可前往 we-vue查看實際使用情況。

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

總結

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

本文以自己的項目為例,但 Aloglia DocSearch 適合很多類型的網站,使用 Vue.js 官網這類用 HEXO 構建的靜態站,又或者像 Easywechat 一樣用 Laravel 開發的動態網站(事實上自己早前曾向超哥安利過 DocSearch, 然后竟然真被用上了 ? )。有了搜索功能之后,用戶能更方便有找到自己想要的信息,當然,網站的格調也極大的提升了!