docsify 生成文档

1、为什么使用docsify

我喜欢使用 markdown 编写一些课件

还喜欢将课件放到码云上（因为 github 不稳定）

但是很显然，这远没有 html 结构浏览器来舒服

docsify 小工具完美解决了问题

小工具的原理很简单，创建一个 docs 目录，目录中有 index.html、readme.md和一个..nojekyll文件

• docs目录：建议将所有的 markdown 文件都放在这个目录或其子目录中
• readme.md 就是一个说明文件，可以删除
• .nokekyi 一个空文件，因为我们可能要创建一个 _sidebar.md 的文件，用来编辑侧边栏导航，如果使用 git 的话，git 会忽略以 _ 开头的文件，这个空文件的目的就是让 git 不要忽略这个 _sidebar.md 文件
• index.html 这个才是最核心的，其内部引入

2、如何使用

首先全局安装

npm i docsify-cli -g

然后初始化项目

docsify init ./docs

上面命令会创建 docsify 文件夹，并自动创建如下三个文件，我们的 markdown 应该放在这个文件夹下

而且这个文件夹应该创建在某个项目或者仓库的根目录下，如

 

其实，此时，就已经可以将 markdown 文件转换为 html 了， 只需要运行 index.html 文件

如何运行呢？当然不是双击，必须以服务器的方式打开

比如 apache，某些 ide 中的服务插件

或者 docsify 本身也能够开启一个服务

如果在doc 目录下，使用如下命令

 docsify serve

如果在 docs 目录外，使用如下命令

 docsify serve docs

通过上面加你的地址加上markdown 文件名称(不需要后缀名 md)，就可以访问此文件了， docsify 会将 markdown 生成一个 html 文件，然后渲染

注意：目录下并不会生成 html 文件，而是存在于内存中，所以这对于 git 来说是很友好的，不用额外上传大量的 html 文件

 

3、使用码云

唯一的问题就是服务是本地的

如何发不成外网呢

有自己的服务器和域名是最好的

如果没有，可以利用 github 或者码云提供的 pages 功能

以码云为例

点击项目上方的服务，在选择 gitee pages

按如下设置后，开启即可

 

本地编辑完 markdown ，提交到码云，然后利用 gitee pages 在线浏览即可