101 lines
2.6 KiB
Markdown
101 lines
2.6 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
|
|||
|
```
|
|||
|
|
|||
|
## 定制侧边栏
|
|||
|
|
|||
|
默认情况下,侧边栏会根据当前文档的标题生成目录。也可以设置文档链接,通过 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}` 都不会在页面上呈现。
|