推荐安装 docsify-cli
工具,可以方便创建及本地预览文档网站。
npm i docsify-cli -g
如果想在项目的 ./docs
目录里写文档,直接通过 init
初始化项目。
docsify init ./docs
初始化成功后,可以看到 ./docs
目录下创建的几个文件
index.html
入口文件README.md
会做为主页内容渲染.nojekyll
用于阻止 GitHub Pages 会忽略掉下划线开头的文件运行一个本地服务器通过 docsify serve
可以方便的预览效果,而且提供 LiveReload 功能,可以让实时的预览。默认访问 http://localhost:3000 。
docsify serve docs
如果系统里安装 Python 的话,也可以很轻易的启动一个静态服务器。
cd docs && python -m SimpleHTTPServer 3000
?> 更多命令行工具用法,参考 docsify-cli 文档。
初始化时会显示 Loading...
内容,你可以自定义提示信息。
index.html
<div id="app">加载中</div>
如果更改了 el
的配置,需要将该元素加上 data-app
属性。
index.html
<div data-app id="main">加载中</div>
<script>
window.$docsify = {
el: '#main'
}
</script>
如果需要创建多个页面,或者需要多级路由的网站,在 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
默认情况下,侧边栏会根据当前文档的标题生成目录。也可以设置文档链接,通过 Markdown 文件生成,效果如当前的文档的侧边栏。
首先配置 loadSidebar
选项,具体配置规则见配置项#loadSidebar。
<script>
window.$docsify = {
loadSidebar: true
}
</script>
<script src="//unpkg.com/docsify"></script>
接着创建 _sidebar.md
文件,内容如下
* [首页](zh-cn/)
* [指南](zh-cn/guide)
!> 需要在文档根目录创建 .nojekyll
命名的空文件,阻止 GitHub Pages 忽略命名是下划线开头的文件。
_sidebar.md
的加载逻辑是从每层目录下获取文件,如果当前目录不存在该文件则回退到上一级目录。例如当前路径为 /zh-cn/more-pages
则从 /zh-cn/_sidebar.md
获取文件,如果不存在则从 /_sidebar.md
获取。
当然你也可以配置 alias
避免不必要的回退过程。
<script>
window.$docsify = {
loadSidebar: true,
alias: {
'/.*/_sidebar.md': '/_sidebar.md'
}
}
</script>
自定义侧边栏同时也可以开启目录功能。设置 subMaxLevel
配置项,具体介绍见 配置项#sub-max-level。
<script>
window.$docsify = {
loadSidebar: true,
subMaxLevel: 2
}
</script>
<script src="//unpkg.com/docsify"></script>
当设置了 subMaxLevel
时,默认情况下每个标题都会自动添加到目录中。如果你想忽略特定的标题,可以给它添加 {docsify-ignore}
。
# Getting Started
## Header {docsify-ignore}
该标题不会出现在侧边栏的目录中。
要忽略特定页面上的所有标题,你可以在页面的第一个标题上使用 {docsify-ignore-all}
。
# Getting Started {docsify-ignore-all}
## Header
该标题不会出现在侧边栏的目录中。
在使用时, {docsify-ignore}
和 {docsify-ignore-all}
都不会在页面上呈现。