用 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    class="search-input"
 6    id="search_input"
 7    placeholder="搜索文档"
 8  >
 9</template>
10
11<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 dropdown
22    })
23  }
24}
25</script>

注意:上面只是最简单的示例。实际上使用可以更灵活,例如装搜索框封装成一个组件,若有兴趣,可前往 we-vue查看实际使用情况。

最后根据自己的喜好及需要,调整下搜索框及搜索下拉弹出层的样式,就完工了。下面是最终效果。

总结

Algolia DocSearch 可以说真如其官网描述的那样,算是目前构建可在线搜索文档的最简单的方式之一了。你只需要关注文档本身,进行少量的配置,其它的 Algolia 全包了。另外,Algolia 还有一些其它优秀产品及服务,诸位可前往官网自行探索。

本文以自己的项目为例,但 Aloglia DocSearch 适合很多类型的网站,使用 Vue.js 官网这类用 HEXO 构建的静态站,又或者像 Easywechat 一样用 Laravel 开发的动态网站(事实上自己早前曾向超哥安利过 DocSearch, 然后竟然真被用上了 ? )。有了搜索功能之后,用户能更方便有找到自己想要的信息,当然,网站的格调也极大的提升了!

原文发布于微信公众号 - 假装我会写代码(bugszoo)

原文发表时间:2018-05-24

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏互联网高可用架构

分布式服务化系统一致性的“最佳实干”

23350
来自专栏Linyb极客之路

12大要点让你的Java开发所向披靡~

比如,没有把一些需要并发执行时使用的线程数设置成可在属性文件中配置。那么你的程序无论在DEV环境中,还是TEST环境中,都可以顺畅无阻地运行,但是一旦部署在PR...

9120
来自专栏企鹅号快讯

Java开发的几个注意点

将一些需要变动的配置写在属性文件中 比如,没有把一些需要并发执行时使用的线程数设置成可在属性文件中配置。那么你的程序无论在DEV环境中,还是TEST环境中,都可...

18360
来自专栏腾讯移动品质中心TMQ的专栏

TBS三方SDK自动化探索

对于非宿主的合作伙伴来说,在TBS接入环节,“共享和下载内核”的能力是最重要的,它从根本上决定着APP是否能够使用预期的X5内核提供服务。一旦出现问题,会导致无...

42400
来自专栏程序员互动联盟

【专业技术第四讲】如何检测浏览器的快慢?

现在做浏览器的大概有下面几个方向吧 1. 从事浏览器外壳的工作,开发基于浏览器的各种应用和扩展; 2. 做浏览器内核优化的,大概又分为几个部分: a. 渲染模块...

350120
来自专栏更流畅、简洁的软件开发方式

【自然框架】通用权限的视频演示(一):添加角色,权限到功能节点和按钮

      写了几个关于权限的东东,好像大家都不大理解,也不太清楚我的权限到底能做什么,所以想来想去还是弄点视频吧,就是屏幕录像,这样大家看起来就方便了吧。  ...

260100
来自专栏Thinks

你的第一个渐进式网站应用(1)

渐进式网站应用程序是结合网站和应用程序中最好的体验。它们对于用户来说从浏览器标签中第一次访问,不需要安装是非常有用的。随着用户逐渐建立与应用程序的关系,它变得越...

10310
来自专栏CSDN技术头条

架构师于小波:魅族实时消息推送架构

【编者按】此文是根据魅族架构师于小波在msup和魅族联合举办的#魅族技术开放日#的演讲中的分享内容整理而成,于小波分享了魅族实时消息推送架构的其中遇到的坑和一些...

40170
来自专栏搜云库

分布式和集群区别?什么是云计算平台?分布式的应用场景?

分布式是指将一个业务拆分不同的子业务,分布在不同的机器上执行,集群是指多台服务器集中在一起,实现同一业务,可以视为一台计算机,一个云计算平台,就是通过一套软件系...

1.2K100
来自专栏WeTest质量开放平台团队的专栏

浅谈服务器性能测试的全生命周期——从测试、结果分析到优化策略

服务器性能测试是一项非常重要而且必要的工作,本文是作者Micheal在对服务器进行性能测试的过程中不断摸索出来的一些实用策略,通过定位问题,分析原因以及解决问题...

29040

扫码关注云+社区

领取腾讯云代金券