docsify——一个神奇的文档网站生成工具
写项目手册使用到了一个非常好用的框架,个人也是第一次接触,但是看了十分钟文档就能上手了,非常简单,官方文档写的也是很清楚,(除了中文文档经常404之外),各种插件,api也是很简单。
官方文档:https://docsify.js.org/
怎么用:
1. 全局安装docsify
npm i docsify-cli -g
2. 初始化项目
docsify init ./docs
3. 本地预览(跑起来)
docsify serve docs
然后出现端口3000就是已经OK了,可以再浏览器查看了。
4:项目文件
现在再来看看自动生成的文件及目录:
- .nojekyll
- index.html
- README. md
就没有了,是不是很清爽。
其中index.html相当于首页,而README. md就是挂载在首页的一个组件,页面布局是自动解析markdown文件自动构成的。当然也就可以有多个.md文件。
侧边栏(右侧导航)
接着创建 _sidebar.md
文件,保存在根目录下
* [首页](./../pretext/project.md)
* 指南
* [自定义加载文件](./../pretext/Front-end-specification.md)
(用 [ ] 框起来代表可以点击,,没有就只渲染,无法点击。后面()里是.md文件的路径。)
接下来在 index.html 中配置 loadSidebar
选项,默认加载 _sidebar.md
文件
<script>
window.$docsify = {
loadSidebar: true
}
</script>
现在看看,右侧导航栏就成下图:
最后,如果你在.md文件里设置有h1,h2…等,框架可以直接渲染出右侧导航:
目录层级
<script>
window.$docsify = {
loadSidebar: true,
subMaxLevel: 2 //只显示一、二级标题
}
</script>
- 代表右侧渲染出几层的目录。
- 注意:层级是从h1开始算的,如果你是从h3到h4,那么你就需要填写4,如果是从h1到h2,那就填写2就可以了。