feat(search): add local search (#231)

* feat(search): add local search * docs: add docs for search
2020-04-15 15:46:50 +08:00
parent b6ce753ae7
commit 90184ca3e7
92 changed files with 4843 additions and 1214 deletions
--- a/exampleSite/config.toml
+++ b/exampleSite/config.toml
@@ -93,6 +93,17 @@ enableEmoji = true
      keywords = ["Theme", "Hugo"]
      # site default theme ("light", "dark", "auto")
      defaultTheme = "auto"
+      # Search
+      [languages.en.params.search]
+        enable = true
+        # type of search engine ("lunr", "algolia")
+        type = "algolia"
+        # index length of the content
+        contentLength = 5000
+        [languages.en.params.search.algolia]
+          index = "index.en"
+          appID = "PASDMWALPK"
+          searchKey = "b42948e51daaa93df92381c8e2ac0f93"
      # Home Page Info
      [languages.en.params.home]
        # Home Page Profile
@@ -327,6 +338,17 @@ enableEmoji = true
      keywords = ["Theme", "Hugo"]
      # 网站默认主题 ("light", "dark", "auto")
      defaultTheme = "auto"
+      # 搜索
+      [languages.zh-cn.params.search]
+        enable = true
+        # 搜索引擎的类型 ("lunr", "algolia")
+        type = "algolia"
+        # 文章内容索引长度
+        contentLength = 5000
+        [languages.zh-cn.params.search.algolia]
+          index = "index.zh-cn"
+          appID = "PASDMWALPK"
+          searchKey = "b42948e51daaa93df92381c8e2ac0f93"
      # 主页信息设置
      [languages.zh-cn.params.home]
        # 主页个人信息
@@ -561,6 +583,17 @@ enableEmoji = true
      keywords = ["Thème", "Hugo"]
      # site default theme ("light", "dark", "auto")
      defaultTheme = "auto"
+      # Search
+      [languages.fr.params.search]
+        enable = true
+        # type of search engine ("lunr", "algolia")
+        type = "algolia"
+        # index length of the content
+        contentLength = 5000
+        [languages.fr.params.search.algolia]
+          index = "index.fr"
+          appID = "PASDMWALPK"
+          searchKey = "b42948e51daaa93df92381c8e2ac0f93"
      # Home Page Info
      [languages.fr.params.home]
        # Home Page Profile
@@ -847,6 +880,12 @@ enableEmoji = true
    animateCSS = ''
    # smooth-scroll@16.1.2 https://github.com/cferdinandi/smooth-scroll
    smoothScrollJS = ''
+    # autocomplete.js@0.37.1 https://github.com/algolia/autocomplete.js
+    autocompleteJS = ''
+    # lunr.js@2.3.8 https://lunrjs.com/
+    lunrJS = ''
+    # algoliasearch@4.1.0 https://github.com/algolia/algoliasearch-client-javascript
+    algoliasearchJS = ''
    # sharer@0.4.0 https://github.com/ellisonleao/sharer.js
    sharerJS = ''
    # lazysizes@5.2.0 https://github.com/aFarkas/lazysizes
@@ -858,7 +897,7 @@ enableEmoji = true
    lightgalleryZoomJS = ''
    # typeit@6.5.1 https://github.com/alexmacarthur/typeit
    typeitJS = ''
-    # katex@0.11.1 https://github.com/KaTeX/KaTeX
+    # katex@0.11.1 https://katex.org/
    katexCSS = ''
    katexJS = ''
    katexAutoRenderJS = ''
@@ -867,17 +906,17 @@ enableEmoji = true
    katexMhchemJS = ''
    # mermaid@8.4.8 https://github.com/knsv/mermaid
    mermaidJS = ''
-    # aplayer@1.10.1 https://github.com/MoePlayer/APlayer
-    aplayerCSS = ''
-    aplayerJS = ''
-    # meting@2.0.1 https://github.com/metowolf/MetingJS
-    metingJS = ''
    # echarts@4.6.0 https://echarts.apache.org/
    echartsJS = ''
    echartsMacaronsJS = ''
    # mapbox-gl@1.8.1 https://docs.mapbox.com/mapbox-gl-js
    mapboxGLCSS = ''
    mapboxGLJS = ''
+    # aplayer@1.10.1 https://github.com/MoePlayer/APlayer
+    aplayerCSS = ''
+    aplayerJS = ''
+    # meting@2.0.1 https://github.com/metowolf/MetingJS
+    metingJS = ''
    # gitalk@1.6.2 https://github.com/gitalk/gitalk
    gitalkCSS = ''
    gitalkJS = ''
@@ -962,7 +1001,7 @@ enableEmoji = true
 # Options to make hugo output files
 # 用于 Hugo 输出文档的设置
 [outputs]
-  home = ["HTML", "RSS"]
+  home = ["HTML", "RSS", "JSON"]
  page = ["HTML", "MarkDown"]
  section = ["HTML", "RSS"]
  taxonomy = ["HTML", "RSS"]
--- a/exampleSite/content/about.en.md
+++ b/exampleSite/content/about.en.md
@@ -54,11 +54,12 @@ It is based on the original [LeaveIt Theme](https://github.com/liuzc/LeaveIt/) a

 #### Extended Features

+* :(fas fa-search): **Search** supported by [Lunr.js](https://lunrjs.com/) or [algolia](https://www.algolia.com/)
 * :(fas fa-code): Automatically **highlighting** code
 * :(far fa-images): **Images gallery** supported by [lightgallery.js](https://github.com/sachinchoolur/lightgallery.js)
-* :(fab fa-font-awesome): Extended markdown syntax for **[Font Awesome](https://fontawesome.com/) icons**
-* :(far fa-sticky-note): Extended markdown syntax for **ruby annotation**
-* :(fas fa-percentage): Extended markdown syntax for **fraction**
+* :(fab fa-font-awesome): Extended Markdown syntax for **[Font Awesome](https://fontawesome.com/) icons**
+* :(far fa-sticky-note): Extended Markdown syntax for **ruby annotation**
+* :(fas fa-percentage): Extended Markdown syntax for **fraction**
 * :(fas fa-square-root-alt): **Mathematical formula** supported by [$ \KaTeX $](https://katex.org/)
 * :(fas fa-project-diagram): **Diagrams** shortcode supported by [mermaid](https://github.com/knsv/mermaid)
 * :(fas fa-chart-pie): **Interactive data visualization** shortcode supported by [ECharts](https://echarts.apache.org/)
@@ -82,9 +83,13 @@ Thanks to the authors of following resources included in the theme:
 * [Font Awesome](https://fontawesome.com/)
 * [Fork Awesome](https://forkaweso.me/Fork-Awesome/)
 * [Animate.css](https://daneden.github.io/animate.css/)
+* [Smooth Scroll](https://github.com/cferdinandi/smooth-scroll)
+* [autocomplete.js](https://github.com/algolia/autocomplete.js)
+* [Lunr.js](https://lunrjs.com/)
+* [algoliasearch](https://github.com/algolia/algoliasearch-client-javascript)
+* [Sharer.js](https://github.com/ellisonleao/sharer.js)
 * [lazysizes](https://github.com/aFarkas/lazysizes)
 * [lightgallery.js](https://github.com/sachinchoolur/lightgallery.js)
-* [Smooth Scroll](https://github.com/cferdinandi/smooth-scroll)
 * [TypeIt](https://typeitjs.com/)
 * [$ \KaTeX $](https://katex.org/)
 * [mermaid](https://github.com/knsv/mermaid)
--- a/exampleSite/content/about.fr.md
+++ b/exampleSite/content/about.fr.md
@@ -59,11 +59,12 @@ It is based on the original [LeaveIt Theme](https://github.com/liuzc/LeaveIt/) a

 #### Extended Features

+* :(fas fa-search): **Search** supported by [Lunr.js](https://lunrjs.com/) or [algolia](https://www.algolia.com/)
 * :(fas fa-code): Automatically **highlighting** code
 * :(far fa-images): **Images gallery** supported by [lightgallery.js](https://github.com/sachinchoolur/lightgallery.js)
-* :(fab fa-font-awesome): Extended markdown syntax for **[Font Awesome](https://fontawesome.com/) icons**
-* :(far fa-sticky-note): Extended markdown syntax for **ruby annotation**
-* :(fas fa-percentage): Extended markdown syntax for **fraction**
+* :(fab fa-font-awesome): Extended Markdown syntax for **[Font Awesome](https://fontawesome.com/) icons**
+* :(far fa-sticky-note): Extended Markdown syntax for **ruby annotation**
+* :(fas fa-percentage): Extended Markdown syntax for **fraction**
 * :(fas fa-square-root-alt): **Mathematical formula** supported by [$ \KaTeX $](https://katex.org/)
 * :(fas fa-project-diagram): **Diagrams** shortcode supported by [mermaid](https://github.com/knsv/mermaid)
 * :(fas fa-chart-pie): **Interactive data visualization** shortcode supported by [ECharts](https://echarts.apache.org/)
@@ -87,9 +88,13 @@ Thanks to the authors of following resources included in the theme:
 * [Font Awesome](https://fontawesome.com/)
 * [Fork Awesome](https://forkaweso.me/Fork-Awesome/)
 * [Animate.css](https://daneden.github.io/animate.css/)
+* [Smooth Scroll](https://github.com/cferdinandi/smooth-scroll)
+* [autocomplete.js](https://github.com/algolia/autocomplete.js)
+* [Lunr.js](https://lunrjs.com/)
+* [algoliasearch](https://github.com/algolia/algoliasearch-client-javascript)
+* [Sharer.js](https://github.com/ellisonleao/sharer.js)
 * [lazysizes](https://github.com/aFarkas/lazysizes)
 * [lightgallery.js](https://github.com/sachinchoolur/lightgallery.js)
-* [Smooth Scroll](https://github.com/cferdinandi/smooth-scroll)
 * [TypeIt](https://typeitjs.com/)
 * [$ \KaTeX $](https://katex.org/)
 * [mermaid](https://github.com/knsv/mermaid)
--- a/exampleSite/content/about.zh-cn.md
+++ b/exampleSite/content/about.zh-cn.md
@@ -54,6 +54,7 @@ lightgallery: true

 #### 扩展功能

+* :(fas fa-search): 支持基于 [Lunr.js](https://lunrjs.com/) 或 [algolia](https://www.algolia.com/) 的**搜索**
 * :(fas fa-code): 支持**代码高亮**
 * :(far fa-images): 支持基于 [lightgallery.js](https://github.com/sachinchoolur/lightgallery.js) 的**图片画廊**
 * :(fab fa-font-awesome): 支持 **[Font Awesome](https://fontawesome.com/) 图标**的扩展 Markdown 语法
@@ -82,9 +83,13 @@ LoveIt 主题中用到了以下项目，感谢它们的作者：
 * [Font Awesome](https://fontawesome.com/)
 * [Fork Awesome](https://forkaweso.me/Fork-Awesome/)
 * [Animate.css](https://daneden.github.io/animate.css/)
+* [Smooth Scroll](https://github.com/cferdinandi/smooth-scroll)
+* [autocomplete.js](https://github.com/algolia/autocomplete.js)
+* [Lunr.js](https://lunrjs.com/)
+* [algoliasearch](https://github.com/algolia/algoliasearch-client-javascript)
+* [Sharer.js](https://github.com/ellisonleao/sharer.js)
 * [lazysizes](https://github.com/aFarkas/lazysizes)
 * [lightgallery.js](https://github.com/sachinchoolur/lightgallery.js)
-* [Smooth Scroll](https://github.com/cferdinandi/smooth-scroll)
 * [TypeIt](https://typeitjs.com/)
 * [$ \KaTeX $](https://katex.org/)
 * [mermaid](https://github.com/knsv/mermaid)
--- a/exampleSite/content/posts/theme-documentation-basics.en.md
+++ b/exampleSite/content/posts/theme-documentation-basics.en.md
@@ -204,6 +204,17 @@ Note that some of these parameters are explained in details in other sections of
  # {{< version 0.1.1 new small >}} which hash function used for SRI, when empty, no SRI is used
  # ("sha256", "sha384", "sha512", "md5")
  fingerprint = ""
+  # {{< version 0.2.0 new small >}} Search
+  [params.search]
+    enable = true
+    # type of search engine ("lunr", "algolia")
+    type = "lunr"
+    # index length of the content
+    contentLength = 5000
+    [params.search.algolia]
+      index = ""
+      appID = ""
+      searchKey = ""
  # Header info
  [params.header]
    # desktop header mode ("fixed", "normal", "auto")
@@ -455,6 +466,12 @@ Note that some of these parameters are explained in details in other sections of
    animateCSS = ''
    # {{< link "https://github.com/cferdinandi/smooth-scroll" "smooth-scroll" >}}@16.1.2
    smoothScrollJS = ''
+    # {{< version 0.2.0 new small >}} {{< link "https://github.com/algolia/autocomplete.js" "autocomplete.js" >}}@0.37.1
+    autocompleteJS = ''
+    # {{< version 0.2.0 new small >}} {{< link "https://lunrjs.com/" "lunr.js" >}}@2.3.8
+    lunrJS = ''
+    # {{< version 0.2.0 new small >}} {{< link "https://github.com/algolia/algoliasearch-client-javascript" "algoliasearch" >}}@4.1.0
+    algoliasearchJS = ''
    # {{< link "https://github.com/ellisonleao/sharer.js" "sharer" >}}@0.4.0
    sharerJS = ''
    # {{< link "https://github.com/aFarkas/lazysizes" "lazysizes" >}}@5.2.0
@@ -475,17 +492,17 @@ Note that some of these parameters are explained in details in other sections of
    katexMhchemJS = ''
    # {{< link "https://github.com/knsv/mermaid" "mermaid" >}}@8.4.8
    mermaidJS = ''
-    # {{< link "https://github.com/MoePlayer/APlayer" "aplayer" >}}@1.10.1
-    aplayerCSS = ''
-    aplayerJS = ''
-    # {{< link "https://github.com/metowolf/MetingJS" "meting" >}}@2.0.1
-    metingJS = ''
    # {{< link "https://echarts.apache.org/" "echarts" >}}@4.6.0
    echartsJS = ''
    echartsMacaronsJS = ''
    # {{< version 0.2.0 new small >}} {{< link "https://docs.mapbox.com/mapbox-gl-js" mapbox-gl >}}@1.8.1
    mapboxGLCSS = ''
    mapboxGLJS = ''
+    # {{< link "https://github.com/MoePlayer/APlayer" "aplayer" >}}@1.10.1
+    aplayerCSS = ''
+    aplayerJS = ''
+    # {{< link "https://github.com/metowolf/MetingJS" "meting" >}}@2.0.1
+    metingJS = ''
    # {{< link "https://github.com/gitalk/gitalk" "gitalk" >}}@1.6.2
    gitalkCSS = ''
    gitalkJS = ''
@@ -558,13 +575,24 @@ Note that some of these parameters are explained in details in other sections of

 # Options to make hugo output files
 [outputs]
-  home = ["HTML", "RSS"]
+  # {{< version 0.2.0 changed small >}}
+  home = ["HTML", "RSS", "JSON"]
  page = ["HTML", "MarkDown"]
  section = ["HTML", "RSS"]
  taxonomy = ["HTML", "RSS"]
  taxonomyTerm = ["HTML"]
 ```

+{{< admonition tip "Tips about CDN Configuration" >}}
+Full HTML tags or URLs are supported for CDN configuration:
+
+```toml
+smoothScrollJS = '<script src="https://cdn.jsdelivr.net/npm/smooth-scroll@16.1.3/dist/smooth-scroll.min.js" integrity="sha256-vP+F+14A1ogChQs5Osd5LJl/ci9TbzjiZjjEbcqOXrY=" crossorigin="anonymous"></script>'
+# Or
+smoothScrollJS = 'https://cdn.jsdelivr.net/npm/smooth-scroll@16/dist/smooth-scroll.min.js'
+```
+{{< /admonition >}}
+
 ![Complete configuration preview](/images/theme-documentation-basics/complete-configuration-preview.png "Complete configuration preview")

 ### 3.2 Favicons, Browserconfig, Manifest
@@ -733,3 +761,50 @@ Translations strings are used for common default values used in the theme. Trans
 To override these values, create a new file in your local i18n folder `i18n/<languageCode>.toml` and inspire yourself from `themes/LoveIt/i18n/en.toml`.

 By the way, as these translations could be used by other people, please take the time to propose a translation by [making a PR](https://github.com/dillonzq/LoveIt/pulls) to the theme!
+
+## 5 Search
+
+{{< version 0.2.0 >}}
+
+Based on [Lunr.js](https://lunrjs.com/) or [algolia](https://www.algolia.com/), searching is supported in **LoveIt** theme.
+
+### 5.1 Output Configuration
+
+In order to generate `index.json` for searching, add `JSON` output file type to the `home` of the `outputs` part in your [site configuration](#site-configuration).
+
+```toml
+[outputs]
+  home = ["HTML", "RSS", "JSON"]
+```
+
+### 5.2 Search Configuration
+
+Based on `index.json` generated by Hugo, you could activate searching.
+
+Here is the search configuration in your [site configuration](#site-configuration):
+
+```toml
+[params.search]
+  enable = true
+  # type of search engine ("lunr", "algolia")
+  type = "lunr"
+  # index length of the content
+  contentLength = 5000
+  [params.search.algolia]
+    index = ""
+    appID = ""
+    searchKey = ""
+```
+
+{{< admonition note "How to choose the type of search engine?" >}}
+* `lunr`: simple, no need to synchronize `index.json`, no limit for `contentLength`,
+  but high bandwidth and low performance (Especially for Chinese which needs a large segmentit library)
+* `algolia`: high performance and low bandwidth, but need to synchronize `index.json` and limit for `contentLength`
+{{< /admonition >}}
+
+{{< admonition tip "Tips about algolia" >}}
+You need to upload `index.json` files to algolia to activate searching.
+You could upload the `index.json` files by browsers but a script may be a better choice.
+To be compatible with Hugo multilingual mode,
+you need to upload different `index.json` for each language to the different index of algolia, such as `zh-cn/index.json` or `fr/index.json`...
+{{< /admonition >}}
--- a/exampleSite/content/posts/theme-documentation-basics.fr.md
+++ b/exampleSite/content/posts/theme-documentation-basics.fr.md
@@ -209,6 +209,17 @@ Note that some of these parameters are explained in details in other sections of
  # {{< version 0.1.1 new small >}} which hash function used for SRI, when empty, no SRI is used
  # ("sha256", "sha384", "sha512", "md5")
  fingerprint = ""
+  # {{< version 0.2.0 new small >}} Search
+  [params.search]
+    enable = true
+    # type of search engine ("lunr", "algolia")
+    type = "lunr"
+    # index length of the content
+    contentLength = 5000
+    [params.search.algolia]
+      index = ""
+      appID = ""
+      searchKey = ""
  # Header info
  [params.header]
    # desktop header mode ("fixed", "normal", "auto")
@@ -460,6 +471,12 @@ Note that some of these parameters are explained in details in other sections of
    animateCSS = ''
    # {{< link "https://github.com/cferdinandi/smooth-scroll" "smooth-scroll" >}}@16.1.2
    smoothScrollJS = ''
+    # {{< version 0.2.0 new small >}} {{< link "https://github.com/algolia/autocomplete.js" "autocomplete.js" >}}@0.37.1
+    autocompleteJS = ''
+    # {{< version 0.2.0 new small >}} {{< link "https://lunrjs.com/" "lunr.js" >}}@2.3.8
+    lunrJS = ''
+    # {{< version 0.2.0 new small >}} {{< link "https://github.com/algolia/algoliasearch-client-javascript" "algoliasearch" >}}@4.1.0
+    algoliasearchJS = ''
    # {{< link "https://github.com/ellisonleao/sharer.js" "sharer" >}}@0.4.0
    sharerJS = ''
    # {{< link "https://github.com/aFarkas/lazysizes" "lazysizes" >}}@5.2.0
@@ -480,17 +497,17 @@ Note that some of these parameters are explained in details in other sections of
    katexMhchemJS = ''
    # {{< link "https://github.com/knsv/mermaid" "mermaid" >}}@8.4.8
    mermaidJS = ''
-    # {{< link "https://github.com/MoePlayer/APlayer" "aplayer" >}}@1.10.1
-    aplayerCSS = ''
-    aplayerJS = ''
-    # {{< link "https://github.com/metowolf/MetingJS" "meting" >}}@2.0.1
-    metingJS = ''
    # {{< link "https://echarts.apache.org/" "echarts" >}}@4.6.0
    echartsJS = ''
    echartsMacaronsJS = ''
    # {{< version 0.2.0 new small >}} {{< link "https://docs.mapbox.com/mapbox-gl-js" mapbox-gl >}}@1.8.1
    mapboxGLCSS = ''
    mapboxGLJS = ''
+    # {{< link "https://github.com/MoePlayer/APlayer" "aplayer" >}}@1.10.1
+    aplayerCSS = ''
+    aplayerJS = ''
+    # {{< link "https://github.com/metowolf/MetingJS" "meting" >}}@2.0.1
+    metingJS = ''
    # {{< link "https://github.com/gitalk/gitalk" "gitalk" >}}@1.6.2
    gitalkCSS = ''
    gitalkJS = ''
@@ -563,13 +580,24 @@ Note that some of these parameters are explained in details in other sections of

 # Options to make hugo output files
 [outputs]
-  home = ["HTML", "RSS"]
+  # {{< version 0.2.0 changed small >}}
+  home = ["HTML", "RSS", "JSON"]
  page = ["HTML", "MarkDown"]
  section = ["HTML", "RSS"]
  taxonomy = ["HTML", "RSS"]
  taxonomyTerm = ["HTML"]
 ```

+{{< admonition tip "Tips about CDN Configuration" >}}
+Full HTML tags or URLs are supported for CDN configuration:
+
+```toml
+smoothScrollJS = '<script src="https://cdn.jsdelivr.net/npm/smooth-scroll@16.1.3/dist/smooth-scroll.min.js" integrity="sha256-vP+F+14A1ogChQs5Osd5LJl/ci9TbzjiZjjEbcqOXrY=" crossorigin="anonymous"></script>'
+# Or
+smoothScrollJS = 'https://cdn.jsdelivr.net/npm/smooth-scroll@16/dist/smooth-scroll.min.js'
+```
+{{< /admonition >}}
+
 ![Complete configuration preview](/images/theme-documentation-basics/complete-configuration-preview.png "Complete configuration preview")

 ### 3.2 Favicons, Browserconfig, Manifest
@@ -738,3 +766,50 @@ Translations strings are used for common default values used in the theme. Trans
 To override these values, create a new file in your local i18n folder `i18n/<languageCode>.toml` and inspire yourself from `themes/LoveIt/i18n/en.toml`.

 By the way, as these translations could be used by other people, please take the time to propose a translation by [making a PR](https://github.com/dillonzq/LoveIt/pulls) to the theme!
+
+## 5 Search
+
+{{< version 0.2.0 >}}
+
+Based on [Lunr.js](https://lunrjs.com/) or [algolia](https://www.algolia.com/), searching is supported in **LoveIt** theme.
+
+### 5.1 Output Configuration
+
+In order to generate `index.json` for searching, add `JSON` output file type to the `home` of the `outputs` part in your [site configuration](#site-configuration).
+
+```toml
+[outputs]
+  home = ["HTML", "RSS", "JSON"]
+```
+
+### 5.2 Search Configuration
+
+Based on `index.json` generated by Hugo, you could activate searching.
+
+Here is the search configuration in your [site configuration](#site-configuration):
+
+```toml
+[params.search]
+  enable = true
+  # type of search engine ("lunr", "algolia")
+  type = "lunr"
+  # index length of the content
+  contentLength = 5000
+  [params.search.algolia]
+    index = ""
+    appID = ""
+    searchKey = ""
+```
+
+{{< admonition note "How to choose the type of search engine?" >}}
+* `lunr`: simple, no need to synchronize `index.json`, no limit for `contentLength`,
+  but high bandwidth and low performance (Especially for Chinese which needs a large segmentit library)
+* `algolia`: high performance and low bandwidth, but need to synchronize `index.json` and limit for `contentLength`
+{{< /admonition >}}
+
+{{< admonition tip "Tips about algolia" >}}
+You need to upload `index.json` files to algolia to activate searching.
+You could upload the `index.json` files by browsers but a script may be a better choice.
+To be compatible with Hugo multilingual mode,
+you need to upload different `index.json` for each language to the different index of algolia, such as `zh-cn/index.json` or `fr/index.json`...
+{{< /admonition >}}
--- a/exampleSite/content/posts/theme-documentation-basics.zh-cn.md
+++ b/exampleSite/content/posts/theme-documentation-basics.zh-cn.md
@@ -207,6 +207,17 @@ hugo
  # {{< version 0.1.1 new small >}} 哪种哈希函数用来 SRI, 为空时表示不使用 SRI
  # ("sha256", "sha384", "sha512", "md5")
  fingerprint = ""
+  # {{< version 0.2.0 new small >}} 搜索
+  [params.search]
+    enable = true
+    # 搜索引擎的类型 ("lunr", "algolia")
+    type = "lunr"
+    # 文章内容索引长度
+    contentLength = 5000
+    [params.search.algolia]
+      index = ""
+      appID = ""
+      searchKey = ""
  # 页面头部导航栏信息
  [params.header]
    # 桌面端导航栏模式 ("fixed", "normal", "auto")
@@ -457,6 +468,12 @@ hugo
    animateCSS = ''
    # {{< link "https://github.com/cferdinandi/smooth-scroll" "smooth-scroll" >}}@16.1.2
    smoothScrollJS = ''
+    # {{< version 0.2.0 new small >}} {{< link "https://github.com/algolia/autocomplete.js" "autocomplete.js" >}}@0.37.1
+    autocompleteJS = ''
+    # {{< version 0.2.0 new small >}} {{< link "https://lunrjs.com/" "lunr.js" >}}@2.3.8
+    lunrJS = ''
+    # {{< version 0.2.0 new small >}} {{< link "https://github.com/algolia/algoliasearch-client-javascript" "algoliasearch" >}}@4.1.0
+    algoliasearchJS = ''
    # {{< link "https://github.com/ellisonleao/sharer.js" "sharer" >}}@0.4.0
    sharerJS = ''
    # {{< link "https://github.com/aFarkas/lazysizes" "lazysizes" >}}@5.2.0
@@ -477,17 +494,17 @@ hugo
    katexMhchemJS = ''
    # {{< link "https://github.com/knsv/mermaid" "mermaid" >}}@8.4.8
    mermaidJS = ''
-    # {{< link "https://github.com/MoePlayer/APlayer" "aplayer" >}}@1.10.1
-    aplayerCSS = ''
-    aplayerJS = ''
-    # {{< link "https://github.com/metowolf/MetingJS" "meting" >}}@2.0.1
-    metingJS = ''
    # {{< link "https://echarts.apache.org/" "echarts" >}}@4.6.0
    echartsJS = ''
    echartsMacaronsJS = ''
    # {{< version 0.2.0 new small >}} {{< link "https://docs.mapbox.com/mapbox-gl-js" mapbox-gl >}}@1.8.1
    mapboxGLCSS = ''
    mapboxGLJS = ''
+    # {{< link "https://github.com/MoePlayer/APlayer" "aplayer" >}}@1.10.1
+    aplayerCSS = ''
+    aplayerJS = ''
+    # {{< link "https://github.com/metowolf/MetingJS" "meting" >}}@2.0.1
+    metingJS = ''
    # {{< link "https://github.com/gitalk/gitalk" "gitalk" >}}@1.6.2
    gitalkCSS = ''
    gitalkJS = ''
@@ -560,13 +577,24 @@ hugo

 # 用于 Hugo 输出文档的设置
 [outputs]
-  home = ["HTML", "RSS"]
+  # {{< version 0.2.0 changed small >}}
+  home = ["HTML", "RSS", "JSON"]
  page = ["HTML", "MarkDown"]
  section = ["HTML", "RSS"]
  taxonomy = ["HTML", "RSS"]
  taxonomyTerm = ["HTML"]
 ```

+{{< admonition tip "关于 CDN 配置的技巧" >}}
+在 CDN 的配置中, 完整的 HTML 标签和 URL 都是支持的:
+
+```toml
+smoothScrollJS = '<script src="https://cdn.jsdelivr.net/npm/smooth-scroll@16.1.3/dist/smooth-scroll.min.js" integrity="sha256-vP+F+14A1ogChQs5Osd5LJl/ci9TbzjiZjjEbcqOXrY=" crossorigin="anonymous"></script>'
+# 或者
+smoothScrollJS = 'https://cdn.jsdelivr.net/npm/smooth-scroll@16/dist/smooth-scroll.min.js'
+```
+{{< /admonition >}}
+
 ![完整配置下的预览](/images/theme-documentation-basics/complete-configuration-preview.zh-cn.png "完整配置下的预览")

 ### 3.2 网站图标, 浏览器配置, 网站清单
@@ -736,3 +764,47 @@ defaultContentLanguage = "zh-cn"
 要覆盖默认值, 请在项目的 i18n 目录 `i18n/<languageCode>.toml` 中创建一个新文件，并从 `themes/LoveIt/i18n/en.toml` 中获得提示.

 另外, 由于你的翻译可能会帮助到其他人, 请花点时间通过 [创建一个 PR](https://github.com/dillonzq/LoveIt/pulls) 来贡献主题翻译, 谢谢!
+
+## 5 搜索
+
+{{< version 0.2.0 >}}
+
+基于 [Lunr.js](https://lunrjs.com/) 或 [algolia](https://www.algolia.com/), **LoveIt** 主支持搜索功能.
+
+### 5.1 输出配置
+
+为了生成搜索功能所需要的 `index.json`, 请在你的 [网站配置](#site-configuration) 中添加 `JSON` 输出文件类型到 `outputs` 部分的 `home` 字段中.
+
+```toml
+[outputs]
+  home = ["HTML", "RSS", "JSON"]
+```
+
+### 5.2 搜索配置
+
+基于 Hugo 生成的 `index.json` 文件, 你可以激活搜索功能.
+
+这是你的 [网站配置](#site-configuration) 中的搜索部分:
+
+```toml
+[params.search]
+  enable = true
+  # type of search engine ("lunr", "algolia")
+  type = "lunr"
+  # index length of the content
+  contentLength = 5000
+  [params.search.algolia]
+    index = ""
+    appID = ""
+    searchKey = ""
+```
+
+{{< admonition note "怎样选择搜索引擎的类型?" >}}
+* `lunr`: 简单, 无需同步 `index.json`, 没有 `contentLength` 的限制, 但占用带宽大且性能低 (特别是中文需要一个较大的分词依赖库)
+* `algolia`: 高性能并且占用带宽低, 但需要同步 `index.json` 且有 `contentLength` 的限制
+{{< /admonition >}}
+
+{{< admonition tip "关于 algolia 的使用技巧" >}}
+你需要上传 `index.json` 到 algolia 来激活搜索功能. 你可以使用浏览器来上传 `index.json` 文件但是一个自动化的脚本可能是更好的选择.
+为了兼容 Hugo 的多语言模式, 你需要上传不同语言的 `index.json` 文件到对应的 algolia index, 例如 `zh-cn/index.json` 或 `fr/index.json`...
+{{< /admonition >}}
--- a/exampleSite/content/posts/theme-documentation-content.en.md
+++ b/exampleSite/content/posts/theme-documentation-content.en.md
@@ -68,6 +68,7 @@ license: ""
 tags: []
 categories: []
 hiddenFromHomePage: false
+hiddenFromSearch: false

 featuredImage: ""
 featuredImagePreview: ""
@@ -103,6 +104,7 @@ comment: true
 * **tags**: the tags for the content.
 * **categories**: the categories for the content.
 * **hiddenFromHomePage**: if `true`, the content will not be shown in the home page, but this behaviour is configurabl in the [site configuration](../theme-documentation-basics/#site-configuration).
+* **hiddenFromSearch**: {{< version 0.2.0 >}} if `true`, the content will not be shown in the search results.
 * **featuredImage**: the featured image for the content.
 * **featuredImagePreview**: the featured image for the content preview in the home page.
 * **toc**: if `true`, the content will show the table of the contents.
@@ -114,6 +116,10 @@ comment: true
 * **share**: the same as `params.share` in the [site configuration](../theme-documentation-basics/#site-configuration).
 * **comment**: if `true`, the comment will be used.

+{{< admonition tip >}}
+Not all of the above front matters need to be set in each of your posts. It is necessary only if the front matters and your [site configuration](../theme-documentation-basics/#site-configuration) are inconsistent.
+{{< /admonition >}}
+
 ## 3 Content Summaries

 **LoveIt** theme uses the summary of the content to display abstract information in the home page. Hugo can generate summaries of your content.
--- a/exampleSite/content/posts/theme-documentation-content.fr.md
+++ b/exampleSite/content/posts/theme-documentation-content.fr.md
@@ -73,6 +73,7 @@ license: ""
 tags: []
 categories: []
 hiddenFromHomePage: false
+hiddenFromSearch: false

 featuredImage: ""
 featuredImagePreview: ""
@@ -108,6 +109,7 @@ comment: true
 * **tags**: the tags for the content.
 * **categories**: the categories for the content.
 * **hiddenFromHomePage**: if `true`, the content will not be shown in the home page, but this behaviour is configurabl in the [site configuration](../theme-documentation-basics/#site-configuration).
+* **hiddenFromSearch**: {{< version 0.2.0 >}} if `true`, the content will not be shown in the search results.
 * **featuredImage**: the featured image for the content.
 * **featuredImagePreview**: the featured image for the content preview in the home page.
 * **toc**: if `true`, the content will show the table of the contents.
@@ -119,6 +121,10 @@ comment: true
 * **share**: the same as `params.share` in the [site configuration](../theme-documentation-basics/#site-configuration).
 * **comment**: if `true`, the comment will be used.

+{{< admonition tip >}}
+Not all of the above front matters need to be set in each of your posts. It is necessary only if the front matters and your [site configuration](../theme-documentation-basics/#site-configuration) are inconsistent.
+{{< /admonition >}}
+
 ## 3 Content Summaries

 **LoveIt** theme uses the summary of the content to display abstract information in the home page. Hugo can generate summaries of your content.
--- a/exampleSite/content/posts/theme-documentation-content.zh-cn.md
+++ b/exampleSite/content/posts/theme-documentation-content.zh-cn.md
@@ -1,7 +1,6 @@
 ---
 weight: 2
 title: "主题文档 - 内容"
-subtitle: ""
 date: 2020-03-05T16:30:05+08:00
 lastmod: 2020-03-05T16:30:05+08:00
 draft: false
@@ -12,18 +11,13 @@ license: ""

 tags: ["内容", "markdown"]
 categories: ["documentation"]
-hiddenFromHomePage: false

 featuredImage: "/images/theme-documentation-content/featured-image.jpg"
-featuredImagePreview: ""

 toc: true
 autoCollapseToc: false
 math: true
 mapbox:
-    accessToken: ""
-    lightStyle: ""
-    darkStyle: ""
    navigation: true
    geolocate: true
    scale: true
@@ -68,6 +62,7 @@ license: ""
 tags: []
 categories: []
 hiddenFromHomePage: false
+hiddenFromSearch: false

 featuredImage: ""
 featuredImagePreview: ""
@@ -103,6 +98,7 @@ comment: true
 * **tags**: 文章的标签.
 * **categories**: 文章所属的类别.
 * **hiddenFromHomePage**: 如果设为 `true`, 这篇文章将不会显示在主页上, 但是此行为可以在 [网站配置](../theme-documentation-basics/#site-configuration) 中设置的.
+* **hiddenFromSearch**: {{< version 0.2.0 >}} 如果设为 `true`, 这篇文章将不会显示在搜索结果中.
 * **featuredImage**: 文章的特色图片.
 * **featuredImagePreview**: 用在主页预览的文章特色图片.
 * **toc**: 如果设为 `true`, 这篇文章会显示右侧目录.
@@ -114,6 +110,11 @@ comment: true
 * **share**: 和 [网站配置](../theme-documentation-basics/#site-configuration) 中的 `params.share` 对象相同.
 * **comment**: 如果设为 `true`, 将启用评论系统.

+{{< admonition tip >}}
+不是所有的上述前置参数都必须在你的每篇文章中设置.
+只有在文章的参数和你的 [网站设置](../theme-documentation-basics/#site-configuration) 不一致时才有必要这么做.
+{{< /admonition >}}
+
 ## 3 内容摘要

 **LoveIt** 主题使用内容摘要在主页中显示大致文章信息。Hugo 支持生成文章的摘要.
--- a/exampleSite/content/posts/theme-documentation-extended-shortcodes.zh-cn.md
+++ b/exampleSite/content/posts/theme-documentation-extended-shortcodes.zh-cn.md
@@ -12,7 +12,6 @@ license: ""

 tags: ["shortcodes"]
 categories: ["documentation"]
-hiddenFromHomePage: false

 featuredImage: "/images/theme-documentation-extended-shortcodes/featured-image.jpg"
 featuredImagePreview: "/images/theme-documentation-extended-shortcodes/featured-image-preview.jpg"
@@ -20,19 +19,6 @@ featuredImagePreview: "/images/theme-documentation-extended-shortcodes/featured-
 toc: true
 autoCollapseToc: true
 math: false
-mapbox:
-    accessToken: ""
-    lightStyle: ""
-    darkStyle: ""
-    navigation: true
-    geolocate: true
-    scale: true
-    fullscreen: true
-lightgallery: true
-linkToMarkdown: true
-share:
-  enable: true
-comment: true
 ---

 **LoveIt** 主题在 Hugo 内置的 shortcode 的基础上提供多个扩展的 shortcode.