Merge pull request #91 from sli1989/patch

Add CN doc of Algolia search
theme-next · Jan 30, 2018 · ef4e429 · ef4e429
2 parents fb373d6 + 839d659
commit ef4e429
Show file tree

Hide file tree

Showing 2 changed files with 133 additions and 0 deletions.
diff --git a/docs/ALGOLIA-SEARCH.md b/docs/ALGOLIA-SEARCH.md
@@ -0,0 +1,69 @@
+<h1 align="center">Algolia Search</h1>
+
+
+NexT provides search plugin for index your hexo website content. To use this feature, make sure that the version of NexT you are using is after the v5.1.0 release. What you should note here is that only turn on `enable` of `algolia_search` in `next/_config.yml` cannot let you use the algolia search correctly, you need to install corresponding [Hexo Algolia](https://github.com/oncletom/hexo-algolia) plugin to seach your website with Algolia. Follow the steps described below to complete the installation of Algolia search.
+
+1. Register at [Algolia](https://www.algolia.com/), you can log in directly using GitHub or Google Account. Upon Customer’s initial sign-up for an Account, Customer will have a free, fourteen (14) day evaluation period (the “Evaluation Period”) for the Algolia Services commencing on the Effective Date, subject to the limitations on Algolia’s website. After that, Algolia offers a free, branded version for up to 10k records and 100k operations per month.
+
+1. If a tutorial pops up, you can skip it. Go straight to create an `Index` which will be used later.
+
+    ![](http://theme-next.iissnan.com/uploads/algolia/algolia-step-2.png)
+
+1. Algolia requires users to upload their search index data either manually or via provided APIs. Install and configure [Hexo Algolia](https://github.com/oncletom/hexo-algolia) in your Hexo directory. This plugin will index your site and upload selected data to Algolia.
+
+    ```
+    cd hexo
+    npm install --save hexo-algolia
+    ```
+
+1. Go to the `API Keys` page and find your credentials. You will need the `Application ID` and the `Search-only API key` in the following sections. The `Admin API key` need to keep confidential. Never store your Admin API Key as apiKey in the` _config.yml` file: it would give full control of your Algolia index to others and you don't want to face the consequences.
+
+    ![](https://user-images.githubusercontent.com/8521181/35479066-64e35aec-0428-11e8-91f9-1ec3afa45c5c.png)
+
+1. In the `API Keys` page, click the `ALL API KEYS` and the `edit` option in the created APIKEY to activate a pop-up box where you can setup authorizations and restrictions with a great level of precision. Check `Add records`, `Delete records`, `List indices`, `Delete index` features in ACL permissions that will be allowed for the given API key. And then click the `Update` button.
+
+    ![](https://user-images.githubusercontent.com/8521181/35479064-611aa0b4-0428-11e8-85a1-cfb449b486ec.png)
+    ![](https://user-images.githubusercontent.com/8521181/35479084-d4f7ac02-0428-11e8-95a6-c4e3b1bef47b.png)
+
+1. In your site's `_config.yml`, add the following configuration and replace the `applicationID` & `apiKey` & `indexName` with corresponding fields obtained at Algolia.
+
+    ```yml
+    algolia:
+      applicationID: 'Application ID'
+      apiKey: 'Search-only API key'
+      indexName: 'indexName'
+      chunkSize: 5000
+    ```
+
+1. Run the following command to upload index data, keep a weather eye out the output of the command.
+
+    ```
+    $ export HEXO_ALGOLIA_INDEXING_KEY=Search-Only API key # Use Git Bash
+    # set HEXO_ALGOLIA_INDEXING_KEY=Search-Only API key # Use Windows command line
+    $ hexo clean
+    $ hexo algolia
+    ```
+
+    ![](http://theme-next.iissnan.com/uploads/algolia/algolia-step-4.png)
+
+1. In `next/_config.yml`, turn on `enable` of `algolia_search`. You can adjust the text in `labels` according to your needs.
+
+    ```yml
+    # Algolia Search
+    algolia_search:
+      enable: true
+      hits:
+        per_page: 10
+      labels:
+        input_placeholder: Search for Posts
+        hits_empty: "We didn't find any results for the search: ${query}"
+        hits_stats: "${hits} results found in ${time} ms"
+    ```
+
+<h2 align="center">Known Issues</h2>
+
+1. The latest version of the [Hexo-Algolia](https://github.com/oncletom/hexo-algolia) plugin removes the content indexing feature, given Algolia's free account limitation.
+
+1. The [Hexo-Algoliasearch](https://github.com/LouisBarranqueiro/hexo-algoliasearch) plugin provides content indexing functionality, but requires the replacement of keywords in the NEXT theme. The same problem exists with `Record Too Big` for Algolia's free account.
+    - Replace all `applicationID` in `source/js/src/algolia-search.js` with `appId`
+    - Replace all `applicationID` in `layout/_partials/head/head.swig` with `appId`
diff --git a/docs/zh-CN/ALGOLIA-SEARCH.md b/docs/zh-CN/ALGOLIA-SEARCH.md
@@ -0,0 +1,64 @@
+<h1 align="center">Algolia 搜索</h1>
+
+NexT 内部提供 Algolia 的搜索功能，要使用此功能请确保所使用的 NexT 版本在 `v5.1.0` 之后。需要注意的是，仅仅将 `next/_config.yml` 中 `algolia_search` 的 `enable` 打开**并不能让你使用 Algolia 搜索**，你还需要**使用对应的 Hexo-Algolia 插件** 才能真正在博客页面中使用 Algolia 搜索。按照下面介绍的步骤操作即可完成 Algolia 搜索的安装。
+
+1. 前往 [Algolia 注册页面](https://www.algolia.com/)，注册一个新账户。 可以使用 GitHub 或者 Google 账户直接登录，注册后的 14 天内拥有所有功能（包括收费类别的）。之后若未续费会自动降级为免费账户，免费账户 总共有 10,000 条记录，每月有 100,000 的可以操作数。注册完成后，创建一个新的 Index，这个 Index 将在后面使用。
+
+    ![](http://theme-next.iissnan.com/uploads/algolia/algolia-step-2.png)
+
+1. Index 创建完成后，此时这个 Index 里未包含任何数据。接下来需要安装 [Hexo Algolia](https://github.com/oncletom/hexo-algolia) 扩展，这个扩展的功能是搜集站点的内容并通过 API 发送给 Algolia。前往站点根目录，执行命令安装：
+
+    ```
+    npm install --save hexo-algolia
+    ```
+
+1. 在 `API Keys` 页面找到需要使用的一些配置的值，包括 `ApplicationID` 和 `Search-Only API Key`。注意，`Admin API Key` 需要保密保存，不要外泄。
+
+    ![](https://user-images.githubusercontent.com/8521181/35479066-64e35aec-0428-11e8-91f9-1ec3afa45c5c.png)
+
+1. 在 `API Keys` 页面，点击 `ALL API KEYS` 找到新建 INDEX 对应的 key，**编辑权限**，在弹出框中找到 ACL ，**勾选 Add records、 Delete records、List indices、Delete index 权限**，点击 update 更新。
+
+    ![](https://user-images.githubusercontent.com/8521181/35479064-611aa0b4-0428-11e8-85a1-cfb449b486ec.png)
+    ![](https://user-images.githubusercontent.com/8521181/35479084-d4f7ac02-0428-11e8-95a6-c4e3b1bef47b.png)
+
+1. 编辑 `站点配置文件`，新增以下配置，除了 `chunkSize` 字段，替换成在 Algolia 获取到的值：
+
+    ```yml
+    algolia:
+      applicationID: 'applicationID'
+      apiKey: 'apiKey'
+      indexName: 'indexName'
+      chunkSize: 5000
+    ```
+
+1. 当配置完成，在站点根目录下执行一下命令来更新上传 Index。请注意观察命令的输出。
+
+    ```
+    $ export HEXO_ALGOLIA_INDEXING_KEY=Search-Only API key # 使用 Git Bash
+    # set HEXO_ALGOLIA_INDEXING_KEY=Search-Only API key # 使用 Windows CMD 命令行
+    $ hexo clean
+    $ hexo algolia
+    ```
+
+    ![](http://theme-next.iissnan.com/uploads/algolia/algolia-step-4.png)
+
+1. 更改`主题配置文件`，找到 Algolia Search 配置部分，将 `enable` 改为 `true` 即可，根据需要你可以调整 `labels` 中的文本：
+
+    ```yml
+    # Algolia Search
+    algolia_search:
+      enable: true
+      hits:
+        per_page: 10
+      labels:
+        input_placeholder: Search for Posts
+        hits_empty: "We didn't find any results for the search: ${query}"
+        hits_stats: "${hits} results found in ${time} ms"
+    ```
+
+<h2 align="center">已知的问题</h2>
+
+1. 考虑到 Algolia 免费账户的限制，目前 [Hexo-Algolia](https://github.com/oncletom/hexo-algolia) 插件最新版本去掉了正文索引功能。
+1. [Hexo-Algoliasearch](https://github.com/LouisBarranqueiro/hexo-algoliasearch) 插件提供了正文索引功能，不过需要替换 NEXT 主题中的关键字。对于免费账户，`Record Too Big` 的问题同样存在。
+    - 替换 `source/js/src/algolia-search.js` 中所有的 `applicationID` 为 `appId`
+    - 替换 `layout/_partials/head/head.swig` 中所有的 `applicationID` 为 `appId`