docsify:一个神奇的文档生成工具
原创文章 作者:月光光 2018年01月03日 21:36helloweba.net 标签:JavaScript Vue.js
在开发项目时,我们或许需要一份精致的开发文档,那么使用docsify是不错的选择,docsify是一个文档生成工具,它直接加载 Markdown 文件并动态渲染,同时还可以生成封面页。所以我们只需要写完 Markdown 文档,就可以看到文档页面了。
特性
无需构建无需编译,写完markdown文档直接发布
容易使用并且轻量 (~18kB gzipped)
智能的全文搜索
提供多套主题
丰富的 API
支持 Emoji
兼容 IE10+
支持 SSR (example)
快速上手
我们直接创建一个index.html
文件。
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta charset="UTF-8">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
//...
}
</script>
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
</body>
</html>
新建README.md
文件,作为主页面,编辑:
# Title
## balabala
如果你系统安装了web服务器的话,直接运行web服务,比如我使用PHP,命令行直接启动web服务。
php -S localhost:3000
然后直接在浏览器打开localhost:3000,就可以看到基本的网页框架了。接下来我们就需要写文档了。
当然你也可以直接把构建好的文档放到你的web服务器上,比如nginx、apache或者IIS上预览。
我们也可以安装官方提供的docsify-cli
工具,可以方便创建及本地预览文档网站。
npm i docsify-cli -g
docsify init ./docs
docsify serve docs
docsify提供 LiveReload 功能,可以让实时的预览,默认访问localhost:3000。
多页面
README.md
作为主页面,如果需要创建多个页面,或者需要多级路由的网站,在 docsify 里也能很容易的实现。直接在文档目录下创建对应的 *.md 文件,例如创建一个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
选项。
<script>
window.$docsify = {
loadSidebar: true
}
</script>
<script src="//unpkg.com/docsify"></script>
接着创建 _sidebar.md
文件,内容如下
- [安装](install.md)
- [介绍](guide.md)
然后只要在对应的install.md和guide.md两个文件中写内容就OK了。当然这两个文档都是Markdown格式的,需要按照markcodown语法来编辑。markcodown语法很简单,百度一把,十分钟入门,半小时精通。
主题
目前提供三套主题可供选择,模仿 Vue 和 buble 官网订制的主题样式。还有 @liril-net 贡献的黑色风格的主题。直接修改index.html中的css链接即可。
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/buble.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/dark.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/pure.css">
全文搜索
docsify支持全文搜索,docsify会根据当前页面上的超链接获取文档内容,在 localStorage 内建立文档索引。默认过期时间为一天,当然我们可以自己指定需要缓存的文件列表或者配置过期时间。
<script>
window.$docsify = {
// 完整配置参数
search: {
maxAge: 86400000, // 过期时间,单位毫秒,默认一天
paths: 'auto',
placeholder: '搜索',
noData: '没有记录!'
}
}
</script>
<script src="//unpkg.com/docsify"></script>
<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>
运行后,我们在页面的左上角会有一个搜索框,支持全文搜索的。
想了解更多有关docsify的配置和应用,请访问项目官网:docsify。
共0条评论