101 lines
2.7 KiB
Markdown
101 lines
2.7 KiB
Markdown
# 多页文档
|
||
|
||
如果需要创建多个页面，或者需要多级路由的网站，在 docsify 里也能很容易的实现。例如创建一个 `guide.md` 文件，那么对应的路由就是 `/#/guide`。
|
||
|
||
假设你的目录结构如下：
|
||
|
||
```text
|
||
-| docs/
|
||
-| README.md
|
||
-| guide.md
|
||
-| zh-cn/
|
||
-| README.md
|
||
-| guide.md
|
||
```
|
||
|
||
那么对应的访问页面将是
|
||
|
||
```text
|
||
docs/README.md => http://domain.com
|
||
docs/guide.md => http://domain.com/guide
|
||
docs/zh-cn/README.md => http://domain.com/zh-cn/
|
||
docs/zh-cn/guide.md => http://domain.com/zh-cn/guide
|
||
```
|
||
|
||
## 定制侧边栏
|
||
|
||
为了获得侧边栏，您需要创建自己的_sidebar.md，你也可以自定义加载的文件名。默认情况下侧边栏会通过 Markdown 文件自动生成，效果如当前的文档的侧边栏。
|
||
|
||
首先配置 `loadSidebar` 选项，具体配置规则见[配置项#loadSidebar](zh-cn/configuration.md#loadsidebar)。
|
||
|
||
```html
|
||
<script>
|
||
window.$docsify = {
|
||
loadSidebar: true
|
||
}
|
||
</script>
|
||
<script src="//unpkg.com/docsify"></script>
|
||
```
|
||
|
||
接着创建 `_sidebar.md` 文件，内容如下
|
||
|
||
```markdown
|
||
* [首页](zh-cn/)
|
||
* [指南](zh-cn/guide)
|
||
```
|
||
|
||
!> 需要在文档根目录创建 `.nojekyll` 命名的空文件，阻止 GitHub Pages 忽略命名是下划线开头的文件。
|
||
|
||
`_sidebar.md` 的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。例如当前路径为 `/zh-cn/more-pages` 则从 `/zh-cn/_sidebar.md` 获取文件，如果不存在则从 `/_sidebar.md` 获取。
|
||
|
||
当然你也可以配置 `alias` 避免不必要的回退过程。
|
||
|
||
```html
|
||
<script>
|
||
window.$docsify = {
|
||
loadSidebar: true,
|
||
alias: {
|
||
'/.*/_sidebar.md': '/_sidebar.md'
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
## 显示目录
|
||
|
||
自定义侧边栏同时也可以开启目录功能。设置 `subMaxLevel` 配置项，具体介绍见 [配置项#sub-max-level](zh-cn/configuration#sub-max-level)。
|
||
|
||
```html
|
||
<script>
|
||
window.$docsify = {
|
||
loadSidebar: true,
|
||
subMaxLevel: 2
|
||
}
|
||
</script>
|
||
<script src="//unpkg.com/docsify"></script>
|
||
```
|
||
|
||
## 忽略副标题
|
||
|
||
当设置了 `subMaxLevel` 时，默认情况下每个标题都会自动添加到目录中。如果你想忽略特定的标题，可以给它添加 `{docsify-ignore}` 。
|
||
|
||
```markdown
|
||
# Getting Started
|
||
|
||
## Header {docsify-ignore}
|
||
|
||
该标题不会出现在侧边栏的目录中。
|
||
```
|
||
|
||
要忽略特定页面上的所有标题，你可以在页面的第一个标题上使用 `{docsify-ignore-all}` 。
|
||
|
||
```markdown
|
||
# Getting Started {docsify-ignore-all}
|
||
|
||
## Header
|
||
|
||
该标题不会出现在侧边栏的目录中。
|
||
```
|
||
|
||
在使用时， `{docsify-ignore}` 和 `{docsify-ignore-all}` 都不会在页面上呈现。
|