github地址
英文文档
中文文档
有了 docsify我们就可以编写和下图一样的文档了，方便文档的查阅与长期维护。
屏幕快照 2018-03-31 下午3.01.00.png
通过 github 进行项目管理，随时随地都可以对文档查阅于修改更新。
首先我们需要先安装 npm（我有一篇文章介绍了 npm，如果遇到问题可以参考） 才能继续后续的安装
首先安装 docsify-cli（命令行界面）：
npm i docsify-cli -g
接下来就开始使用了，这里我以我正在整理的公司一个云平台文档（cloud-doc）为例介绍如何使用。
- 首先在 Desktop 创建一个文件夹：cloud-doc
- cd 到当前目录
以上步骤推荐使用命令行操作，操作步骤截图如下：
屏幕快照 2018-03-31 下午3.31.03.png
初始化项目
如果想在项目的 ./docs 目录里写文档，直接通过 init 初始化项目。
docsify init ./docs
解释：./docs 目录开始是没有的，初始化之后才会出现。为什么说“想在./docs 目录里写文档”？
初始化之后如下图：
屏幕快照 2018-03-31 下午3.39.13.png
开始写文档
初始化成功后，可以看到 ./docs 目录下创建的几个文件
- index.html 入口文件
- README.md 会做为主页内容渲染
- .nojekyll 用于阻止 GitHub Pages 会忽略掉下划线开头的文件
上面这句话是docsify 文档上描述的，但是我们在 ./docs目录下却只看到两个文件,如下图：
屏幕快照 2018-03-31 下午3.38.42.png
别急，我们用 VSCode 打开 cloud-doc 就会看到另一个文件，如图：
屏幕快照 2018-03-31 下午4.20.10.png
我们以后编辑文档，就使用 VSCode。
本地预览网站
运行一个本地服务器通过 docsify serve 可以方便的预览效果，而且提供 LiveReload 功能，可以让实时的预览。默认访问 http://localhost:3000 。
docsify serve docs
Loading提示
初始化时会显示 Loading... 内容，你可以自定义提示信息。
这个东西可有可无，顺带讲一下，在修改上图中所示的 index.html 文件。我们将默认的提示内容“Loding...”改为“正在加载，请稍候。。。”，如下图：
屏幕快照 2018-03-31 下午4.35.35.png
多页文档
如果需要创建多个页面，或者需要多级路由的网站，在 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 选项,这一步也是修改index.html文件的配置：
index.html
<script>
window.$docsify = {
loadSidebar: true
}
</script>
<script src="//unpkg.com/docsify"></script>
接着创建 _sidebar.md文件，这个文件是需要我们自己手动创建的，如下图：
屏幕快照 2018-03-31 下午4.49.31.png
这个文件是干嘛用的呢？他可厉害了，我们想让侧边栏显示什么就在这个文件里写什么：
屏幕快照 2018-03-31 下午4.55.14.png
屏幕快照 2018-03-31 下午4.54.50.png
每一节显示什么内容，当然就需要另外创建每一个目录对应的文件，然后在这个文件里写内容了，注意每一个文件都必须以.md结尾。对于同一章节的内容我们又可以把他们放到一个文件夹里。
屏幕快照 2018-03-31 下午4.58.28.png
编辑好的内容要记得提交：
git add .
git commit -m "创建文档目录"
git push
FAQ :
1、当使用如下命令本地运行服务器的时候：
docsify serve
会报如下错误:
Run npm config delete prefix or nvm use --delete-prefix v8.9.4 --silent to unset it.
解决办法1,使用以下命令，但是每次都需要使用：
nvm use v8.9.4
解决办法2，使用以下办法，一劳永逸，解决问题根本：
sudo rm -rf /usr/local/{lib/node{,/.npm,_modules},bin,share/man}/{npm*,node*,man1/node*}
网友评论