docs: more updates

Author: yyx990803

docs/config/README.md

@@ -98,24 +98,6 @@ 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/default-theme-config/README.md

@@ -199,8 +199,6 @@ Make sure to define the fallback configuration last.
 VuePress checks each sidebar config from top to bottom. If the fallback configuration was first, VuePress would incorrectly match `/foo/` or `/bar/four.html` because they both start with `/`.
 :::
 
-
-
 ### Auto Sidebar for Single Pages
 
 If you wish to automatically generate a sidebar that contains only the header links for the current page, you can use `YAML front matter` on that page:
@@ -221,6 +219,38 @@ sidebar: false
 ---
 ```
 
+## Search Box
+
+### Built-in Search
+
+You can disable the built-in search box with `themeConfig.search: false`, and customize how many suggestions to be shown with `themeConfig.searchMaxSuggestions`:
+
+``` js
+module.exports = {
+  themeConfig: {
+    search: false,
+    searchMaxSuggestions: 10
+  }
+}
+```
+
+### Algolia Search
+
+The `themeConfig.algolia` option allows you to use [Algolia DocSearch](https://community.algolia.com/docsearch/) to replace the simple built-in search. To enable it, you need to provide at least `apiKey` and `indexName`:
+
+```js
+module.exports = {
+  themeConfig: {
+    algolia: {
+      apiKey: '<API_KEY>',
+      indexName: '<INDEX_NAME>'
+    }
+  }
+}
+```
+
+For more options, refer to [Algolia DocSearch's documentation](https://github.com/algolia/docsearch#docsearch-options).
+
 ## Prev / Next Links
 
 Prev and next links are automatically inferred based on the sidebar order of the active page. You can also explicitly overwrite or disable them using `YAML front matter`:
@@ -245,9 +275,9 @@ module.exports = {
     // Customising the header label
     // Defaults to "GitHub"/"GitLab"/"Bitbucket" depending on `themeConfig.repo`
     repoLabel: 'Contribute!',
-    
+
     // Optional options for generating "Edit this page" link
- 
+
     // if your docs are in a different repo from your main project:
     docsRepo: 'vuejs/vuepress',
     // if your docs are not at the root of the repo:

docs/guide/deploy.md

@@ -24,10 +24,6 @@ The following guides are based on a few shared assumptions:
 
 2. Inside your project, create `deploy.sh` with the following content (with highlighted lines uncommented appropriately) and run it to deploy:
 
-::: tip
-You can also run this script in your CI setup to enable automatic deployment on each push.
-:::
-
 ``` bash{13,20,23}
 #!/usr/bin/env sh
 
@@ -56,17 +52,21 @@ git commit -m 'deploy'
 cd -
 ```
 
+::: tip
+You can also run the above script in your CI setup to enable automatic deployment on each push.
+:::
+
 ## GitLab Pages and GitLab CI
 
-1. Set correct `base` in `docs/.vuepress/config.js`. 
+1. Set correct `base` in `docs/.vuepress/config.js`.
 
    If you are deploying to `https://<USERNAME or GROUP>.gitlab.io/`, you can omit `base` as it defaults to `"/"`.
 
    If your are deploying to `https://<USERNAME or GROUP>.gitlab.io/<REPO>/`, (i.e. your repository is at `https://gitlab.com/<USERNAME>/REPO>`), set `base` to `"/<REPO>/"`.
- 
+
 2. Set `dest` in `.vuepress/config.js` to `public`.
 
-3. Create a file called `.gitlab-ci.yml` in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content. 
+3. Create a file called `.gitlab-ci.yml` in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content.
 
 ```
 image: node:9.11.1
@@ -85,7 +85,7 @@ pages:
   only:
   - master
 ```
-   
+
 
 ## Netlify
 

docs/guide/markdown.md

@@ -13,15 +13,7 @@ Inbound links ending in `.md` or `.html` are converted to `<router-link>` for SP
 Each sub-directory in your static site should contain a `README.md`. It will automatically be converted to `index.html`.
 
 ::: tip
-When writing the relative path to a directory's `index.html`, don't forget to close it off with a `/`, otherwise you will get a 404.
-
-```md
-<!-- You'll get a 404 -->
-[About Page](/about)
-
-<!-- This is correct -->
-[About Page](/about/)
-```
+When writing the relative path to a directory's `index.html`, don't forget to close it off with a `/`, otherwise you will get a 404. For example, use `/config/` instead of `/config`.
 :::
 
 If you want to link to another markdown file within a directory, remember to:
@@ -56,10 +48,10 @@ Given the following directory structure:
 
 ### External Links
 
-- Outbound links automatically gets `target="_blank"`:
+Outbound links automatically gets `target="_blank"`:
 
-  - [vuejs.org](https://vuejs.org)
-  - [VuePress on GitHub](https://github.com/vuejs/vuepress)
+- [vuejs.org](https://vuejs.org)
+- [VuePress on GitHub](https://github.com/vuejs/vuepress)
 
 ## Front Matter
 

docs/zh/config/README.md

@@ -97,24 +97,6 @@ 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/default-theme-config/README.md

@@ -149,11 +149,13 @@ module.exports = {
 ```
 .
 ├─ README.md
-├─ foo
+├─ contact.md
+├─ about.md
+├─ foo/
 │  ├─ README.md
 │  ├─ one.md
 │  └─ two.md
-└─ bar
+└─ bar/
    ├─ README.md
    ├─ three.md
    └─ four.md
@@ -166,23 +168,33 @@ module.exports = {
 module.exports = {
   themeConfig: {
     sidebar: {
-      // sidebar for pages under /foo/
       '/foo/': [
-        '',
-        'one',
-        'two'
+        '',     /* /foo/ */
+        'one',  /* /foo/one.html */
+        'two'   /* /foo/two.html */
       ],
-      // sidebar for pages under /bar/
+
       '/bar/': [
-        '',
-        'three',
-        'four'
+        '',      /* /bar/ */
+        'three', /* /bar/three.html */
+        'four'   /* /bar/four.html */
+      ],
+
+      // fallback
+      '/': [
+        '',        /* / */
+        'contact', /* /contact.html */
+        'about'    /* /about.html */
       ]
     }
   }
 }
 ```
 
+::: warning
+确保 fallback 侧边栏被最后定义。VuePress 会按顺序遍历侧边栏配置来寻找匹配的配置。
+:::
+
 ### 自动生成侧栏
 
 如果你希望自动生成一个仅仅包含了当前页面标题（headers）链接的侧边栏，你可以通过 `YAML front matter` 来实现：
@@ -203,6 +215,38 @@ sidebar: false
 ---
 ```
 
+## 搜索框
+
+### 内置搜索
+
+你可以通过设置 `themeConfig.search: false` 来禁用默认的搜索框，或是通过 `themeConfig.searchMaxSuggestions` 来调整默认搜索框显示的搜索结果数量：
+
+``` js
+module.exports = {
+  themeConfig: {
+    search: false,
+    searchMaxSuggestions: 10
+  }
+}
+```
+
+### Algolia 搜索
+
+你可以通过 `themeConfig.algolia` 选项来用 [Algolia DocSearch](https://community.algolia.com/docsearch/) 替换内置的搜索框。要启用 Algolia 搜索，你需要至少提供 `apiKey` 和 `indexName`：
+
+```js
+module.exports = {
+  themeConfig: {
+    algolia: {
+      apiKey: '<API_KEY>',
+      indexName: '<INDEX_NAME>'
+    }
+  }
+}
+```
+
+更多选项请参考 [Algolia DocSearch 的文档](https://github.com/algolia/docsearch#docsearch-options)。
+
 ## 上 / 下一篇链接
 
 上一篇和下一篇文章的链接将会自动地根据当前页面的侧边栏的顺序来获取。你也可以使用 `YAML front matter` 来明确地重写或者禁用它：
@@ -227,7 +271,7 @@ module.exports = {
     // 自定义仓库链接文字。默认从 `themeConfig.repo` 中自动推断为
     // "GitHub"/"GitLab"/"Bitbucket" 其中之一，或是 "Source"。
     repoLabel: '查看源码',
-    
+
     // 以下为可选的编辑链接选项
 
     // 假如你的文档仓库和项目本身不在一个仓库：

docs/zh/guide/deploy.md

@@ -1,46 +1,66 @@
 # 部署
 
-下述的指南，将假定你将文档放置在项目的 `docs` 目录中，并使用默认的构建输出位置。
+下述的指南基于以下条件：
+
+- 文档放置在项目的 `docs` 目录中；
+- 使用的是默认的构建输出位置；
+- VuePress 以本地依赖的形式被安装到你的项目中，并且配置了如下的 npm scripts:
+
+``` json
+{
+  "scripts": {
+    "docs:build": "vuepress build docs"
+  }
+}
+```
 
 ## GitHub Pages
 
-1. 将 `.vuepress/config.js` 的 `base` 设置成你仓库的名字，举个例子，如果你的仓库是 `https://github.com/foo/bar`, 部署的页面将会通过 `https://foo.github.io/bar` 来访问，此时，你应该将 `base` 设置为 `"/bar/"`。
+1. 在 `docs/.vuepress/config.js` 中设置正确的 `base`。
+
+  如果你打算发布到 `https://<USERNAME>.github.io/`，则可以省略这一步，因为 `base` 默认即是 `"/"`。
+
+  如果你打算发布到 `https://<USERNAME>.github.io/<REPO>/`（也就是说你的仓库在 `https://github.com/<USERNAME>/REPO>`），则将 `base` 设置为 `"/<REPO>/"`。
+
+2. 在你的项目中，创建一个如下的 `deploy.sh` 文件（请自行判断去掉高亮行的注释）:
+
+``` bash{13,20,23}
+#!/usr/bin/env sh
 
-2. 在你的项目中运行:
+# 确保脚本抛出遇到的错误
+set -e
 
-``` bash
-# 构建静态文件
-vuepress build docs
+# 生成静态文件
+npm run docs:build
 
-# 切换到你的输出目录
+# 进入生成的文件夹
 cd docs/.vuepress/dist
 
+# 如果是发布到自定义域名
+# echo 'www.example.com' > CNAME
+
 git init
 git add -A
 git commit -m 'deploy'
 
-# push 到你仓库的 gh-pages 分支
-# 将 <USERNAME>/<REPO> 替换成你的信息
-git push -f [email protected]:<USERNAME>/<REPO>.git master:gh-pages
+# 如果发布到 https://<USERNAME>.github.io
+# git push -f [email protected]:<USERNAME>/<USERNAME>.github.io.git master
+
+# 如果发布到 https://<USERNAME>.github.io/<REPO>
+# git push -f [email protected]:<USERNAME>/<REPO>.git master:gh-pages
+
+cd -
 ```
 
+::: tip
 你可以在你的持续集成的设置中，设置在每次 push 代码时自动运行上述脚本。
+:::
 
 ## Netlify
 
-1. 确保你已经有了构建你的文档的的 npm scripts：
-
-``` json
-{
-  "scripts": {
-    "build-docs": "vuepress build docs"
-  }
-}
-```
-
-2. 在 Netlify 中, 创建一个新的 Github 项目，并做一下设置:
+1. 在 Netlify 中, 创建一个新的 Github 项目，使用以下设置:
 
   - **Build Command:** `npm run build-docs` 或者 `yarn build-docs`
   - **Publish directory:** `docs/.vuepress/dist`
 
-3. 点击 deploy 按钮！
+2. 点击 deploy 按钮！