feat: Algolia DocSearch Integration (#201)

README.md

@@ -29,7 +29,6 @@ https://vuepress.vuejs.org/
 
 VuePress is still a work in progress. There are a few things that it currently does not support but are planned:
 
-- Algolia DocSearch Integration
 - Blogging support
 
 Contributions are welcome!

docs/config/README.md

@@ -98,6 +98,24 @@ The `serviceWorker` option only handles the service worker. To make your site fu
 Also, only enable this if you are able to deploy your site with SSL, since service worker can only be registered under HTTPs URLs.
 :::
 
+### algolia
+
+- Type: `Object`
+- Default: `undefined`
+
+The `algolia` option allows you to use [algolia docsearch](https://github.com/algolia/docsearch) to replace the simple built-in search. To enable it, you need to provide at least `apiKey` and `indexName`:
+
+```js
+module.exports = {
+  algolia: {
+    apiKey: '<API_KEY>',
+    indexName: '<INDEX_NAME>'
+  }
+}
+```
+
+For more options, refer to [Algolia DocSearch's documentation](https://github.com/algolia/docsearch#docsearch-options). 
+
 ### locales
 
 - Type: `{ [path: string]: Object }`

docs/guide/README.md

@@ -31,7 +31,6 @@ Each markdown file is compiled into HTML with [markdown-it](https://github.com/m
 
 VuePress is still a work in progress. There are a few things that it currently does not support but are planned:
 
-- Algolia DocSearch Integration
 - Blogging support
 
 Contributions are welcome!

docs/guide/i18n.md

@@ -56,6 +56,8 @@ module.exports = {
         label: 'English',
         // text for the edit-on-github link
         editLinkText: 'Edit this page on GitHub',
+        // algolia docsearch options for current locale
+        algolia: {},
         nav: [
           { text: 'Nested', link: '/nested/' }
         ],
@@ -71,6 +73,7 @@ module.exports = {
         nav: [
           { text: '嵌套', link: '/zh/nested/' }
         ],
+        algolia: {},
         sidebar: {
           '/zh/': [/* ... */],
           '/zh/nested/': [/* ... */]

docs/zh/config/README.md

@@ -97,6 +97,24 @@ module.exports = {
 当然，仅仅只在你的网站部署后能用 SSL 的时候开启它，因为 service worker 只能在 HTTPs 的链接下注册。
 :::
 
+### algolia
+
+- 类型: `Object`
+- 默认值: `undefined`
+
+使用 `algolia` 选项可以让你用 [algolia docsearch](https://github.com/algolia/docsearch) 取代默认的基于 headers 的搜索 。为了使其生效，你必须提供至少 `apiKey` 和 `indexName` 这两个选项：
+
+```js
+module.exports = {
+  algolia: {
+    apiKey: '<API_KEY>',
+    indexName: '<INDEX_NAME>'
+  }
+}
+```
+
+其他可用的选项请参考 [docsearch options](https://github.com/algolia/docsearch#docsearch-options)。
+
 ### locales
 
 - 类型: `{ [path: string]: Object }`

docs/zh/guide/README.md

@@ -29,7 +29,6 @@ VuePress 由两部分组成：一部分是支持用 Vue 开发主题的极简静
 
 VuePress 仍然处于开发中，这里有一些目前还不支持、但已经在计划中的特性：
 
-- Algolia DocSearch 的集成
 - 博客系统
 
 我们欢迎你为 VuePress 的开发作出贡献。

docs/zh/guide/i18n.md

@@ -53,6 +53,7 @@ module.exports = {
         selectText: 'Languages',
         label: 'English',
         editLinkText: 'Edit this page on GitHub',
+        algolia: {},
         nav: [
           { text: 'Nested', link: '/nested/' }
         ],
@@ -68,6 +69,8 @@ module.exports = {
         label: '简体中文',
         // 编辑链接文字
         editLinkText: '在 GitHub 上编辑此页',
+        // 当前 locale 的 algolia docsearch 选项
+        algolia: {},
         nav: [
           { text: '嵌套', link: '/zh/nested/' }
         ],

lib/default-theme/AlgoliaSearchBox.vue

@@ -0,0 +1,131 @@
+<template>
+  <form id="search-form" class="algolia-search-wrapper search-box">
+    <input id="algolia-search-input" class="search-query">
+  </form>
+</template>
+
+<script>
+export default {
+  props: ['options'],
+  mounted () {
+    this.initialize()
+  },
+  methods: {
+    initialize () {
+      Promise.all([
+        import(/* webpackChunkName: "docsearch" */ 'docsearch.js/dist/cdn/docsearch.min.js'),
+        import(/* webpackChunkName: "docsearch" */ 'docsearch.js/dist/cdn/docsearch.min.css')
+      ]).then(([docsearch]) => {
+        docsearch = docsearch.default
+        docsearch(Object.assign(this.options, {
+          debug: true,
+          inputSelector: '#algolia-search-input'
+        }))
+      })
+    }
+  },
+  watch: {
+    options (newValue) {
+      this.$el.innerHTML = '<input id="algolia-search-input" class="search-query">'
+      this.initialize(newValue)
+    }
+  }
+}
+</script>
+
+<style lang="stylus">
+@import './styles/config.styl'
+
+.algolia-search-wrapper
+  & > span
+    vertical-align middle
+  .algolia-autocomplete
+    line-height normal
+    .ds-dropdown-menu
+      background-color #fff
+      border 1px solid #999
+      border-radius 4px
+      font-size 16px
+      margin 6px 0 0
+      padding 4px
+      text-align left
+      &:before
+        border-color #999
+      [class*=ds-dataset-]
+        border none
+        padding 0
+      .ds-suggestions
+        margin-top 0
+      .ds-suggestion
+        border-bottom 1px solid $borderColor
+    .algolia-docsearch-suggestion--highlight
+      color #2c815b
+    .algolia-docsearch-suggestion
+      border-color $borderColor
+      padding 0
+      .algolia-docsearch-suggestion--category-header
+        padding 5px 10px
+        margin-top 0
+        background $accentColor
+        color #fff
+        font-weight 600
+        .algolia-docsearch-suggestion--highlight
+          background rgba(255, 255, 255, 0.6)
+      .algolia-docsearch-suggestion--wrapper
+        padding 0
+      .algolia-docsearch-suggestion--title
+        font-weight 600
+        margin-bottom 0
+        color $textColor
+      .algolia-docsearch-suggestion--subcategory-column
+        vertical-align top
+        padding 5px 7px 5px 5px
+        border-color $borderColor
+        background #f1f3f5
+        &:after
+          display none
+      .algolia-docsearch-suggestion--subcategory-column-text
+        color #555
+    .algolia-docsearch-footer
+      border-color $borderColor
+    .ds-cursor .algolia-docsearch-suggestion--content
+      background-color #e7edf3 !important
+      color $textColor
+
+@media (min-width: $MQMobile)
+  .algolia-search-wrapper
+    .algolia-autocomplete
+      .algolia-docsearch-suggestion
+        .algolia-docsearch-suggestion--subcategory-column
+          float none
+          width 150px
+          min-width 150px
+          display table-cell
+        .algolia-docsearch-suggestion--content
+          float none
+          display table-cell
+          width 100%
+          vertical-align top
+        .ds-dropdown-menu
+          min-width 515px !important
+
+@media (max-width: $MQMobile)
+  .algolia-search-wrapper
+    .ds-dropdown-menu
+      min-width calc(100vw - 4rem) !important
+      max-width calc(100vw - 4rem) !important
+    .algolia-docsearch-suggestion--wrapper
+      padding 5px 7px 5px 5px !important
+    .algolia-docsearch-suggestion--subcategory-column
+      padding 0 !important
+      background white !important
+    .algolia-docsearch-suggestion--subcategory-column-text:after
+      content " > "
+      font-size 10px
+      line-height 14.4px
+      display inline-block
+      width 5px
+      margin -3px 3px 0
+      vertical-align middle
+
+</style>

lib/default-theme/Navbar.vue

@@ -12,19 +12,30 @@
       </span>
     </router-link>
     <div class="links">
-      <SearchBox v-if="$site.themeConfig.search !== false"/>
+      <AlgoliaSearchBox v-if="isAlgoliaSearch" :options="algolia"/>
+      <SearchBox v-else-if="$site.themeConfig.search !== false"/>
       <NavLinks class="can-hide"/>
     </div>
   </header>
 </template>
 
 <script>
 import SidebarButton from './SidebarButton.vue'
+import AlgoliaSearchBox from '@AlgoliaSearchBox'
 import SearchBox from './SearchBox.vue'
 import NavLinks from './NavLinks.vue'
 
 export default {
-  components: { SidebarButton, NavLinks, SearchBox }
+  components: { SidebarButton, NavLinks, SearchBox, AlgoliaSearchBox },
+  computed: {
+    algolia () {
+      return this.$themeLocaleConfig.algolia || this.$site.themeConfig.algolia || {}
+    },
+    isAlgoliaSearch () {
+      const algolia = this.algolia
+      return algolia && algolia.apiKey && algolia.indexName
+    }
+  }
 }
 </script>
 

lib/noop.js

@@ -0,0 +1 @@
+module.exports = {}

lib/prepare.js

@@ -111,6 +111,13 @@ async function resolveOptions (sourceDir) {
     !fs.existsSync(path.resolve(vuepressDir, 'theme'))
   )
 
+  // resolve algolia
+  const isAlgoliaSearch = (
+    siteConfig.algolia ||
+    Object.keys(siteConfig.locales && siteConfig.themeConfig && siteConfig.themeConfig.locales || {})
+      .some(base => siteConfig.themeConfig.locales[base].algolia)
+  )
+
   const options = {
     siteConfig,
     sourceDir,
@@ -123,6 +130,7 @@ async function resolveOptions (sourceDir) {
     themePath: null,
     notFoundPath: null,
     useDefaultTheme,
+    isAlgoliaSearch,
     markdown: createMarkdown(siteConfig)
   }
 

lib/webpack/createBaseConfig.js

@@ -7,6 +7,7 @@ module.exports = function createBaseConfig ({
   publicPath,
   themePath,
   notFoundPath,
+  isAlgoliaSearch,
   markdown
 }, { debug } = {}, isServer) {
   const Config = require('webpack-chain')
@@ -39,6 +40,9 @@ module.exports = function createBaseConfig ({
       .set('@source', sourceDir)
       .set('@app', path.resolve(__dirname, '../app'))
       .set('@temp', path.resolve(__dirname, '../app/.temp'))
+      .set('@AlgoliaSearchBox', isAlgoliaSearch
+        ? path.resolve(__dirname, '../default-theme/AlgoliaSearchBox.vue')
+        : path.resolve(__dirname, '../noop.js'))
       .end()
     .extensions
       .merge(['.js', '.jsx', '.vue', '.json'])

package.json

@@ -51,6 +51,7 @@
     "copy-webpack-plugin": "^4.5.1",
     "css-loader": "^0.28.11",
     "diacritics": "^1.3.0",
+    "docsearch.js": "^2.5.2",
     "es6-promise": "^4.2.4",
     "escape-html": "^1.0.3",
     "file-loader": "^1.1.11",