Links
- Documentation
- CLI
- CDN: UNPKG | jsDelivr
Features
- No statically built html files
- Simple and lightweight (~18kB gzipped)
- Smart full-text search plugin
- Multiple themes
- Useful plugin API
- Compatible with IE10+
- Support SSR (example)
Quick start
index.html.<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>
<body>
<div id="app"></div>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>
Browser Support
Showcase
| Project | Description |
|---|---|
| Snipaste | Snip & Paste |
| puck | A small & magical php framework. |
| Samaritan | An Algorithmic Trading Framework for Digital Currency. |
| Vudash | Powerful, Flexible, Open Source dashboards for anything |
| Trilogy | No-hassle SQLite with a Promise-based, document store style API. |
| Mybatis-Plus | An enhanced toolkit of Mybatis to simplify development |
| JS MythBusters | An optimization handbook from a high level point of view. |
| hire-me | A path to getting an awesome tech gig. |
| vue-amap | A Map Component Library Base on Vue 2.x and Gaode Map. |
| samlify | Node.js SAML2 library |
| palettify | A color palette effects assistant |
| commitlint | Lint commit messages |
| vue-data-tables | A simple and customizable data table，based on vue2 and element-ui. |
| Noty | A Dependency-free notification library |
Similar projects
| Project | Description |
|---|---|
| docute | |
| docpress | Documentation website generator |
Contributing
- Fork it!
- Create your feature branch:
git checkout -b my-new-feature - Commit your changes:
git commit -am 'Add some feature' - Push to the branch:
git push origin my-new-feature - Submit a pull request
Development
npm run bootstrap && npm run dev
open http://localhost:3000
from https://github.com/QingWei-Li/docsify, https://github.com/docsifyjs/docsify
要添加更多的页面，见此：https://docsify.now.sh/more-pages
--------------------------------------------------------------
docsify-ssr-demo
Deploy
npm i
npm run deploy
from https://github.com/QingWei-Li/docsify-ssr-demo
-------
docsify本地部署
右击选择git bash在命令行中输入 npm i docsify-cli -g
点击clone or download接着再点击DownloadZIP下载压缩包
解压缩后进入到fq-book-master/docs目录中右击打开git bash输入docsify init .
打开index.html，在repo下方添加lodaSidebar: true并保存
接着使用docsify serve完成本地部署，在浏览器中输入localhost:3000即可看到效果.
更多详细教程请看docsify官网文档说明.
-------------
利用githubPage+docsify搭建项目文档
需求
有时候,我们做了一个项目,我们自己能看懂项目,但是我们需要给他人提供API文档,但是我们又没有多余的服务器和域名,这个时候咋办？那么我们就可以用到GitHubPage+docsify搭建我们的项目文档.
步骤
进入你项目的根目录,在命令行输入以下命令创建项目文档目录(docs):
1
docsify init ./docs
这个命令执行完成之后,你会看见你的项目文档多了一个docs目录.你的项目文档就可以写在这个目录里面.
进入这个目录会看见以下文件:
- index.html 入口文件
- README.md 会做为主页内容渲染
- .nojekyll 用于阻止 GitHub Pages 会忽略掉下划线开头的文件
- 直接编辑 docs/README.md 就能更新网站内容,当然也可以写多个页面.
在README.md写你的项目文档就可以了.
预览文档:
1
docsify serve docs
如果你觉得构建得差不多了,你就可以将它放置到GitHub上面.
首先你得保证你的项目已经托管到GitHub上面.
推荐直接将文档放在 docs/ 目录下,在设置页面开启 GitHub Pages 功能并选择 master branch /docs folder 选项：
在GitHub里面,点击进入项目,设置master branch /docs folder:
完成之后,它会提示你的文档目录已经生成,并且已经可以通过GitHub的子域名进行访问.
--------------------------------------------
个人博客的方案推荐-Docsify
直到我遇到了docsify，我更愿意将它称为第四阶段“动态生成网页托管”。
Docsify是什么
官方的描述是这样子的：一个神奇的文档网站生成工具
docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 .md 转成 .html 文件，所有转换工作都是在运行时进行。
这将非常实用，如果只是需要快速的搭建一个小型的文档网站，或者不想因为生成的一堆 .html 文件“污染” commit 记录，只需要创建一个 index.html 就可以开始写文档而且直接部署在 GitHub Pages。
第一次看到这样的描述的时候，我就觉得它也很适合用来构建一个博客系统，事实证明确实如此。
Docsify有什么
Markdown支持
在2019年写博客，几乎主流的选择都是使用 Markdown 标记性语言，它很轻量，能让关注在内容本身而不是调格式上。
但是，Docsify 提供的 Markdown 是原生的美好的感觉，不需要你刻意遵循什么，想怎么写就怎么写的自由；相对的，Hexo 和 Jekyll 都需要遵循一些特殊的格式，比如 {{ 日期 }} 等。这是我很喜爱它的一点。
官方内置的 Markdown 解析器是marked，如果不喜欢还可以参考文档来自定义。
###CSS支持
docsify 提供了内置的5款主题，分别 vue.css buble.css dark.css pure.css dolphin.css，我个人是比较喜欢绿色的主题的，所以选了还是默认的 vue.css 风格。另外，Github 上还有很多优秀的第三方主题可供选择。
当然作为一个开放的系统，它也允许用户自定义，如果有兴趣，撸一个符合自己审美好看的主题也蛮不错的。
详细的主题 Demo 可以看这里~
Javascript支持
流程图 & 序列图
有 js 的支持，对我来说意味着能够加入扩展 Markdown 语法，比如流程图、序列图等的支持。我很喜欢 Typora 这款 MD 编辑器，它自身加入了流程图和序列图等的支持，这对于技术博客来说还是很有用的一大功能。而借助 docsify 的插件系统，简单的配置了一下就能加入这些功能，然后就能做到桌面端编辑和网页端展示是完全一样的效果。
评论系统
docsify 官方支持 Disqus 和 Gitalk 两种评论系统，如果有需要的话也可以很轻易的配置。我个人是比较推荐使用 Gitalk 的，毕竟 Github 账号很多人都有。
还有其他很有用的功能,官方都提供了，具体可以看这里的插件列表。如果需要实现一些特殊的功能也可以自定义，拥有可修改能力就感觉拥有一切一样，这感觉还是很美好的。
数据独立
这是我最喜欢也是最重要的一点，它不需要你像 Hexo 等系统一样，编写 md 文件，然后通过工具转化为 html 网页静态托管。在 docsify 你只需要专注编写 md 内容本身，保存的也是 md 文件本身，docsify 就会自己读取 md 文件然后渲染成网页展示。
我认为这是一件很棒的事情，不用再过多的依赖工具本身，编写->部署->托管的三个步骤中，我只需要在意第一个步骤就好了。甚者，由于没有了中间文件，我能直接管理 md 源文件，也相当于一个很好的备份，将数据掌握在自己手中的感觉。
你的整个目录将会很整洁，就像这样：
├── index.html
├── p01.解决方案
│ ├── Markdown标题格式化.md
├── p02.效率之道
│ ├── 2019年科学的复合密码管理策略.md
│ ├── 一个5年工科生的软件解决方案与吐槽.md
│ └── 我的Vim配置.md
├── p03.生活随想
│ └── 给大学新生学子的一个思考.md
└── README.md
引入 docsify 后唯一增加的一份文件只是一个 index.html 而已，而你原来管理数据的方式还是完全没变化.
Docsify缺什么
事实上，docsify 也不是完美的，它也有一些小缺点，但是我们可以通过自定义来修补它。
侧边栏目录
由于 Web 技术本身的限制，docsify 想要读取你服务端的文件需要用户主动提供路径，否则随便就能读取文件，想想还是很可怕的。
要想增加侧边栏显示目录，docsify 需要用户自行提供 _sidebar.md 文件，里面用 List 记录着你的目录结构。
但是，很明显，你只想好好写文章，并不想管理这些部署的事情，每新增一篇文章都要同步修改一遍 _sidebar.md 文件，还是很麻烦的一件事情。因此，我想到了请一个佣人来帮我完成这件事情，那就是 Travis CI，一个比较流行的 Github 上的自动化部署服务。然后再花 30s 写一行脚本来生成这个目录。
find . -mindepth 2 -name "*.md" | awk -F'/' 'BEGIN {RS=".md"} {arr[$2]=arr[$2]"\n - ["$3"](/"$2"/"$3")"} END { num = asorti(arr, indices); for (i=1; i<=num; ++i) if (indices[i]) print "- "indices[i], arr[indices[i]]}' > _sidebar.md
具体如何配置 Travis CI 与 Github 之间的联动我这里就不放教程了，官网上有教程.
目录折叠
这是一个在 docsify 的仓库 issue 中呼声比较高的一个功能，很遗憾这个功能现在还没有，所以就自己做一个吧。
得益于 docsify 预留了接口给用户自定义插件，借助钩子（hook）的功能，就可以实现目录折叠，文档多了没有折叠功能，浏览起来还是很不方便的。具体的实现可以参考仓库里的这个文件：https://github.com/Wsine/blog/blob/master/index.html项目部署
Docusaurus，VuePress，GitBook、Docsify均支持配置文件形式的部署方式，可以方便的部署到Github Pages静态服务器上，通过.gitlab-ci.yml部署到GitLab Page.
--------------------
