有了docsify神器，从此爱上看文档

素颜马尾好姑娘i 2022-09-10 07:11 128阅读 0赞

### 简介 ###

我们在做完项目的时候经常会写一些项目手册，来记录我们在项目开发过程中的一些开发流程、使用方式以及注意事项，分享给将会使用到这个项目的人，方便大家快速上手，让程序顺利运行。

目前比较好的方式就是写成Markdown格式的技术文档，方便我们发布在github上，同时也可以发布到博客分享平台。除此之外我们还可以借助docsify这个工具，来帮助我们快速的搭建一个小型的文档网站，它可以自动将我们写在Markdown中的标题生成目录，整个页面的配色和布局也十分舒适易读，让整个阅读体验提升了好几个level，有了docsify这个神器，再也不害怕看长长的技术文档了。

docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会将 `.md` 转成 `.html` 文件，所有转换工作都是在运行时进行。这将非常实用，如果只是需要快速的搭建一个小型的文档网站，或者不想因为生成的一堆 `.html` 文件“污染” commit 记录，只需要创建一个 `index.html` 就可以开始写文档而且直接部署在[GitHub Pages][]。

先看一些使用docsify生成的技术文档：

[Markdown Preview Enhanced][]

[操作系统][Link 1]

[Awesome Mac][]

它的[docsify中文官方文档][docsify]就是利用docsify生成的，展示效果一目了然。

这是我用docsify生成的豆瓣影音项目文档：[https://hanxueqing.github.io/Douban-Movie/][https_hanxueqing.github.io_Douban-Movie]

### 特性 ###

*  无需构建，写完文档直接发布
 *  容易使用并且轻量 (~19kB gzipped)
 *  智能的全文搜索
 *  提供多套主题
 *  丰富的 API
 *  支持 Emoji
 *  兼容 IE10+
 *  支持 SSR ([example][])

### 快速安装 ###

1. 全局安装docsify

npm i docsify-cli -g

安装成功后显示

![8dd975728dc685a4883e6222022b17e0.png][]

2. 初始化项目

docsify init ./docs

初始化成功后，可以看到 `./docs` 目录下创建的几个文件

`index.html` 入口文件

`README.md` 会做为主页内容渲染

`.nojekyll` 用于阻止 GitHub Pages 会忽略掉下划线开头的文件

直接编辑 `docs/README.md` 就能更新网站内容，当然也可以写多个页面

3. 本地预览网站

运行一个本地服务器，通过 `docsify serve` 可以方便的预览效果，而且提供 LiveReload 功能，可以实时的预览。默认通过 [http://localhost:3000][http_localhost_3000]访问。

docsify serve docs

![92e23515d87a71d86297c546ef598c84.png][]

### 常用配置项 ###

**Github Corner**

通过设置index.html中window.$docsify的 `repo` 参数配置仓库地址或者 `username/repo` 的字符串，会在页面右上角渲染一个 [GitHub Corner][] 挂件，点击即可跳转到Github中对应的项目地址。

![619a138b8ea17aae957a8b7f74276e43.png][]

**封面**

通过设置index.html中window.$docsify的 `coverpage` 参数，即可开启渲染封面的功能。

封面的生成同样是从 markdown 文件渲染来的。开启渲染封面功能后在文档根目录创建 `_coverpage.md` 文件，在文档中编写需要展示在封面的内容。

![logo](https://docsify.js.org/_media/icon.svg)
    
    # 豆瓣影音
    
    > 使用Vue全家桶+Node.js搭建的小型全栈项目.
    
    * 前端框架：vue-cli、vue-router、axios、vuex
    * UI类库：Mint-UI、Vant
    * 后端数据接口：Express、MongoDB
    
    [GitHub](https://github.com/Hanxueqing/Douban-Movie.git)
    [Get Started](#quick-start)

展示效果如图：

![f34228043781c43930068abff28fb263.png][]

目前的背景是随机生成的渐变色，我们自定义背景色或者背景图。可以参考官网文档[封面][Link 2]这一章节自行设置。

**主题**

直接打开 index.html 修改替换 css 地址即可切换主题，官方目前提供五套主题可供选择，模仿 [Vue][] 和 [buble][] 官网订制的主题样式。还有 [@liril-net][liril-net] 贡献的黑色风格的主题。

其他主题docsify-themeable又提供了三种样式可供选择

**多页面**

目前我创建的文档是单页面的，上下滚动即可浏览全部内容。如果想创建多个页面，即点击左侧侧边栏导航跳转到不同url，就需要配置多级路由，这一功能在docsify中也很容易实现，我们需要在index.html文件中的`window.$docsify`中开启loadSidebar选项：

然后在根目录创建自己的\_sidebar.md文件，配置我们需要显示的页面。详细操作步骤参考[官方多页文档教程][Link 3]。

*注：配置了`loadSidebar`后就不会生成默认的侧边栏了。*

**插件**

官方还提供了非常多实用的插件，比如说全文搜索、解析emoji表情、一键复制代码等等，完整版请参考[官方插件列表][Link 4]。

### Github Pages ###

> 和 GitBook 生成的文档一样，我们可以直接把文档网站部署到 GitHub Pages 或者 VPS 上。

GitHub Pages 支持从三个地方读取文件

*  `docs/` 目录
 *  master 分支
 *  gh-pages 分支

我们推荐直接将文档放在 `docs/` 目录下，找到仓库的Settings设置页面

![a6cf43d42a3f65dca0601a4c940ccd21.png][]

开启 **GitHub Pages** 功能并选择 `master branch /docs folder` 选项。

![957d479f0bad68109a2b6f147c6140f9.png][]

发布成功后会显示网站地址，通过这个地址即可在线访问你编写的技术文档了。

![8bd627f05b71fa6ade41b151f44d2afa.png][]

参考：

[https://baijiahao.baidu.com/s?id=1683928475208184783&wfr=spider&for=pc][https_baijiahao.baidu.com_s_id_1683928475208184783_wfr_spider_for_pc]

[https://juejin.cn/post/6844904115466682375][https_juejin.cn_post_6844904115466682375]

[GitHub Pages]: https://links.jianshu.com/go?to=https%3A%2F%2Fdocsify.js.org%2F%23%2Fzh-cn%2Fdeploy
[Markdown Preview Enhanced]: https://links.jianshu.com/go?to=https%3A%2F%2Fshd101wyy.github.io%2Fmarkdown-preview-enhanced%2F%23%2Fzh-cn%2F%3Fid%3Dmarkdown-preview-enhanced
[Link 1]: https://links.jianshu.com/go?to=https%3A%2F%2Faopstudio.github.io%2Fdocs%2F%23%2F
[Awesome Mac]: https://links.jianshu.com/go?to=https%3A%2F%2Fripperhe.com%2Fawesome-mac-html%2F%23%2F%3Fid%3Dawesome-mac
[docsify]: https://links.jianshu.com/go?to=https%3A%2F%2Fdocsify.js.org%2F%23%2Fzh-cn%2F
[https_hanxueqing.github.io_Douban-Movie]: https://links.jianshu.com/go?to=https%3A%2F%2Fhanxueqing.github.io%2FDouban-Movie%2F
[example]: https://links.jianshu.com/go?to=https%3A%2F%2Fgithub.com%2Fdocsifyjs%2Fdocsify-ssr-demo
[8dd975728dc685a4883e6222022b17e0.png]: /images/20220829/3b8bb944db4a4273894cd90d988ecd73.png
[http_localhost_3000]: https://links.jianshu.com/go?to=http%3A%2F%2Flocalhost%3A3000
[92e23515d87a71d86297c546ef598c84.png]: /images/20220829/2cf0e8f4bfae41e0a8f3840f9a063566.png
[GitHub Corner]: https://links.jianshu.com/go?to=http%3A%2F%2Ftholman.com%2Fgithub-corners%2F
[619a138b8ea17aae957a8b7f74276e43.png]: /images/20220829/9232784009a340dd80915ae1599cfeaf.png
[f34228043781c43930068abff28fb263.png]: /images/20220829/68a2ee8fcf58452aabc75c09657263e6.png
[Link 2]: https://links.jianshu.com/go?to=https%3A%2F%2Fdocsify.js.org%2F%23%2Fzh-cn%2Fcover
[Vue]: https://links.jianshu.com/go?to=https%3A%2F%2Fvuejs.org
[buble]: https://links.jianshu.com/go?to=https%3A%2F%2Fbuble.surge.sh
[liril-net]: https://links.jianshu.com/go?to=https%3A%2F%2Fgithub.com%2Fliril-net
[Link 3]: https://links.jianshu.com/go?to=https%3A%2F%2Fdocsify.js.org%2F%23%2Fzh-cn%2Fmore-pages
[Link 4]: https://links.jianshu.com/go?to=https%3A%2F%2Fdocsify.js.org%2F%23%2Fzh-cn%2Fplugins
[a6cf43d42a3f65dca0601a4c940ccd21.png]: /images/20220829/d2d5e8406be94dd6a78ae34acf933978.png
[957d479f0bad68109a2b6f147c6140f9.png]: /images/20220829/b161a8dbd0ec479f9820243bc6a9313a.png
[8bd627f05b71fa6ade41b151f44d2afa.png]: /images/20220829/ecc8396ccd2c47a2bc06fb531a779c9b.png
[https_baijiahao.baidu.com_s_id_1683928475208184783_wfr_spider_for_pc]: https://baijiahao.baidu.com/s?id=1683928475208184783&wfr=spider&for=pc
[https_juejin.cn_post_6844904115466682375]: https://juejin.cn/post/6844904115466682375