返回介绍

多页文档

发布于 2020-11-22 06:30:29 字数 7372 浏览 1857 评论 0 收藏 0

如果需要创建多个页面,或者需要多级路由的网站,在 docsify 里也能很容易的实现。例如创建一个 guide.md 文件,那么对应的路由就是 /#/guide

假设你的目录结构如下:

.
└── docs
    ├── README.md
    ├── guide.md
    └── zh-cn
        ├── README.md
        └── guide.md

那么对应的访问页面将是

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。

<!-- index.html -->

<script>
  window.$docsify = {
    loadSidebar: true
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

接着创建 _sidebar.md 文件,内容如下

<!-- docs/_sidebar.md -->

* [首页](zh-cn/)
* [指南](zh-cn/guide)

需要在 ./docs 目录创建 .nojekyll 命名的空文件,阻止 GitHub Pages 忽略命名是下划线开头的文件。

嵌套的侧边栏

你可能想要浏览到一个目录时,只显示这个目录自己的侧边栏,这可以通过在每个文件夹中添加一个 _sidebar.md 文件来实现。

_sidebar.md 的加载逻辑是从每层目录下获取文件,如果当前目录不存在该文件则回退到上一级目录。例如当前路径为 /zh-cn/more-pages 则从 /zh-cn/_sidebar.md 获取文件,如果不存在则从 /_sidebar.md 获取。

当然你也可以配置 alias 避免不必要的回退过程。

<script>
  window.$docsify = {
    loadSidebar: true,
    alias: {
      '/.*/_sidebar.md': '/_sidebar.md'
    }
  }
</script>

你可以在一个子目录中创建一个 README.md 文件来作为路由的默认网页。

用侧边栏中选定的条目名称作为页面标题

一个页面的 title 标签是由侧边栏中选中条目的名称所生成的。为了更好的 SEO ,你可以在文件名后面指定页面标题。

<!-- docs/_sidebar.md -->
* [Home](/)
* [Guide](guide.md "The greatest guide in the world")

显示目录

自定义侧边栏同时也可以开启目录功能。设置 subMaxLevel 配置项,具体介绍见 配置项#sub-max-level。

<!-- index.html -->

<script>
  window.$docsify = {
    loadSidebar: true,
    subMaxLevel: 2
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

忽略副标题

当设置了 subMaxLevel 时,默认情况下每个标题都会自动添加到目录中。如果你想忽略特定的标题,可以给它添加 <!-- {docsify-ignore} -->

# Getting Started

## Header <!-- {docsify-ignore} -->

该标题不会出现在侧边栏的目录中。

要忽略特定页面上的所有标题,你可以在页面的第一个标题上使用 <!-- {docsify-ignore-all} -->

# Getting Started <!-- {docsify-ignore-all} -->

## Header

该标题不会出现在侧边栏的目录中。

在使用时, <!-- {docsify-ignore} --><!-- {docsify-ignore-all} --> 都不会在页面上呈现。

如果你对这篇内容有疑问,欢迎到本站社区发帖提问 参与讨论,获取更多帮助,或者扫码二维码加入 Web 技术交流群。

扫码二维码加入Web技术交流群

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。
列表为空,暂无数据
    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。
    原文