入坑 docsify，一款神奇的文档生成利器！

清疚 2021-09-11 03:54 404阅读 0赞

Guide 哥是我认识的一个非常优秀的年轻人，胖嘟嘟的身躯里充斥着无穷无尽的才华，他的 [JavaGuide][] 在 GitHub 上已经标星 91K+ 了，空闲的时候我都会上去瞅两眼，毕竟学习使我快乐，嘿嘿。

有一天，我发现，他整的那个在线版看起来非常漂亮，我就问他用什么做的，他就会回我说，“docsify，很方便。”刚好我最近在更新《教妹学 Java》专栏，就也想整个在线版的，方便读者阅读。

### 01、docsify 是什么 ###

> 一款神奇的文档生成利器

自从有了 Markdown， 我就再没用过富文本编辑器，因为 Markdown 的书写有一种心流的感觉。很多博客平台都支持 Markdown 了，即便是不支持，也没关系，可以通过 [mdnice][] 或者 [Md2All][] 转成富文本的格式。

docsify 可以自动地将 Markdown 中的标题生成目录，并且可以配合码云（国内的访问速度比 GitHub Pages 更快）快速搭建一个小型的文档网站，整个页面的配色和布局也十分舒适，让阅读体验在不知不觉中提升了好几个档次。

和 Gitbook 不同，docsify 不会生成静态的 HTML 文件，它会智能地加载和解析 Markdown 文件，这就避免了 HTML 文件对整个文档库的“污染”。

贴一下 docsify 的官网：

> [https://docsify.js.org/][https_docsify.js.org]

点进去后你会感觉非常的赏心悦目，满满的小清新。不得不承认，我的眼睛被它深深地吸引了。

![1179389-65ff9cd9f9d037a2.png][]

### 02、入坑 docsify ###

**第一步**，打开命令行，执行以下命令安装 `docsify-cli`，方便本地初始化和实时预览。

npm i docsify-cli -g

如果这一步非常非常慢的话，可以强制退出，因为 npm 是从国外服务器下载的，受网络影响较大。

淘宝团队帮我们解决了这个烦恼，搞了一个 npm 的国内镜像。可以通过执行下面的命令把 npm 替换成 cnpm。

npm install -g cnpm --registry=https://registry.npm.taobao.org

如果出现 `Error: EACCES: permission denied, access '/usr/local/lib/node_modules'` 错误的话，是因为执行命令时没有获得管理员权限，解决方案就在 npm 前面加上 sudo：

sudo npm install -g cnpm --registry=https://registry.npm.taobao.org

输入密码后就可以执行成功了。然后执行 `cnpm i docsify-cli -g` 命令进行安装。如果还提示权限错误（`Error: EACCES: permission denied`）的话，记得加上 sudo。

PS：sudo 是一个 linux 系统管理指令，允许系统管理员让普通用户执行一些 root 级别的命令。

安装成功后，会提示以下信息。

![1179389-462f77fb6e0e4c93.png][]

**第二步**，执行以下命令创建文档目录并初始化。

docsify init ./docs

进入 docs 目录后，可以看到 README.md（做为主页内容渲染）和 index.html（入口文件）两个文件。

![1179389-c9cefa228cdf1bce.png][]

**第三步**，回到 docs 的上级目录，执行以下命令启动本地服务。

docsify serve docs

![1179389-88eeb6e58e83c4f6.png][]

**第四步**，在浏览器地址栏输入 `http://localhost:3000` 进行预览。

![1179389-625d4e071f6f5787.png][]

### 03、自定义导航栏 ###

打开 index.html 文件，在 body 标签中添加 nav 标签，如下所示：

<body>
      <nav>
          <a href="www.itwanger.com">沉默王二个人博客</a>
      </nav>
      <div id="app"></div>
    </body>

保存后，就可以在浏览器上查看到效果。

![1179389-a67661e88572f3c7.png][]

### 04、定制化配置项 ###

打开 index.html 文件，在 script 标签中对 `window.$docsify` 进行配置，如下所示：

window.$docsify = {
            name: '教妹学Java',
            repo: 'https://github.com/itwanger/TechSisterLearnJava',
    }

1）name：文档标题，会显示在侧边栏顶部。

2）repo：GitHub 上的仓库地址，会在页面右上角渲染一个 GitHub 角标。

保存后，就可以在浏览器上查看到效果。

![1179389-8726cf6638b96e29.png][]

### 05、安装插件 ###

**1）全文搜索**

全文搜索插件会根据当前页面上的超链接获取文档内容，在 localStorage 内建立文档索引。默认过期时间为一天，也可以指定需要缓存的文件列表或者过期时间。

打开 index.html 文件，添加全文搜索配置项，并引入 search.min.js，如下所示：

<body>
      <script>
        window.$docsify = {
          search: {
            paths: 'auto',
            placeholder: '搜索',
            noData: '找不到结果',
            depth: 3,
          },
        }
      </script>
      <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
    </body>

保存后，就可以在浏览器上查看到效果。

![1179389-8edae8b56acafe3a.png][]

**2）图片缩放**

在 index.html 文件中引入 zoom-image.min.js 即可，如下所示：

保存后，就可以在浏览器上查看到效果，鼠标放到一张图片上时会出现缩小或者放大的图标，点击后就可以改变图片的形态。

![1179389-c1218f9f0b4a9445.png][]

**3）复制到剪贴板**

在所有的代码块上添加一个简单的 Click to copy 按钮来允许用户从你的文档中轻易地复制代码。在 index.html 文件中引入 docsify-copy-code 即可，如下所示：

保存后，就可以在浏览器上查看到效果。

![1179389-c44330d082111fae.png][]

**4）字数统计**

提供了统计中文汉字和英文单词的功能，并且排除了一些 markdown 语法的特殊字符例如 `*、-` 等。

打开 index.html 文件，添加 count 配置项，并引入 countable.js，如下所示：

<body>
      <script>
        window.$docsify = {
          count:{
            countable:true,
            fontsize:'0.9em',
            color:'rgb(90,90,90)',
            language:'chinese'
          }
        }
      </script>
    <script src="//unpkg.com/docsify-count/dist/countable.js"></script>
    </body>

保存后，就可以在浏览器上查看到效果。

![1179389-253aa92af2cff479.png][]

### 06、代码高亮 ###

**docsify** 内置的代码高亮工具是 [Prism][]。Prism 默认支持的语言如下：

*  Markup - `markup`, `html`, `xml`, `svg`, `mathml`, `ssml`, `atom`, `rss`
 *  CSS - `css`
 *  C-like - `clike`
 *  JavaScript - `javascript`, `js`

Java 需要在 index.html 文件中添加额外的语法文件，如下所示：

保存后，就可以在浏览器上查看到效果。

![1179389-c2c393b0e5609a3b.png][]

### 07、部署到码云 ###

我们可以把文档网站部署到 GitHub Pages 上，但对于国内用户来说，码云的访问速度显然会更快一些。

如果你是第一次使用 GitHub 的话，我这里已经为你准备好了教程：

> [文科妹子都会用 GitHub，你这个工科生还等什么][GitHub]

在 GitHub 上新建一个仓库，把你的文档全部放到 docs 目录下，我的已经创建好了，就叫 TechSisterLearnJava。

![1179389-86575ddec7e9394d.png][]

接下来，登录码云，选择从 GitHub 导入仓库。

![1179389-44bd94e8bba5f9b5.png][]

选择对应仓库后点击导入。

![1179389-94fed7218652ff6c.png][]

导入成功后，点击「查看仓库」，就可以看到从 GitHub 导入到码云的仓库。点击「服务」，选择「Gitee Pages」。

![1179389-690f7014e838b717.png][]

勾选强制启用 HTTPS，然后点击「启动」按钮。不一会儿，码云 Pages 服务就开启了。

![1179389-0cef268138809a97.png][]

点击网站地址：

> [https://itwanger.gitee.io/zero-learn-java][https_itwanger.gitee.io_zero-learn-java]

就可以看到 docsify 已经成功部署到码云上了。

![1179389-82ef9c8e114b1cff.png][]

### 08、最后 ###

强烈推荐一下《教妹学 Java》专栏，目前已更新 15 节内容（**近 5 万字**），后面每周至少会更新 2 节，预计**更新 130 节**，从 Java 的基础知识到对象和类，再到集合框架、网络编程、并发编程和 Java 虚拟机，基本上全方位覆盖。

专栏中涉及到的图片都花了我很多精力和心思，力争给你一种耳目一新的感觉，随便截几张图给你看看。

![1179389-6d2a51ad1da4554f.png][]

真的用心了

![1179389-1ba2641a3a9f403f.png][]

真的真的用心了

![1179389-6cbe36cdf8c18b66.png][]

思维导图同样用了心

这么好的专栏上哪去找呢？免费给你（反正我也不知道自己是怎么想的）！

GitHub 阅读地址（star 它）：

> [https://github.com/itwanger/javaZero][https_github.com_itwanger_javaZero]

码云阅读地址（star 它）：

> [https://gitee.com/itwanger/javaZero][https_gitee.com_itwanger_javaZero]

docsify 在线阅读地址：

> [https://itwanger.gitee.io/javazero][https_itwanger.gitee.io_javazero]

我知道，我知道，不用你开口，离线版的 PDF 我也准备好了，看这暗黑风格的 PDF，阅读起来绝壁赏心悦目啊。

![1179389-56a33be44184f320.png][]

百度网盘下载（暗黑和亮白，两种）地址：

> [https://pan.baidu.com/s/1qwomiFHW6vZdVo26heMctg][https_pan.baidu.com_s_1qwomiFHW6vZdVo26heMctg] 密码:1thn

PS：整完这个 docsify 后，我累坏了，一瞅时间，凌晨 1 点 32 分了，说实话，眼睛已经迷离了。

[JavaGuide]: https://links.jianshu.com/go?to=https%3A%2F%2Fgithub.com%2FSnailclimb%2FJavaGuide
[mdnice]: https://links.jianshu.com/go?to=https%3A%2F%2Fwww.mdnice.com%2F
[Md2All]: https://links.jianshu.com/go?to=http%3A%2F%2Fmd.aclickall.com%2F
[https_docsify.js.org]: https://links.jianshu.com/go?to=https%3A%2F%2Fdocsify.js.org%2F
[1179389-65ff9cd9f9d037a2.png]: /images/20210809/288a37f31d534db5825c20155e897595.png
[1179389-462f77fb6e0e4c93.png]: /images/20210809/ba05ec2c011c4a00a28ff557f5ce6fcb.png
[1179389-c9cefa228cdf1bce.png]: /images/20210809/38aed53cca004c7caa8f457b75e8ccef.png
[1179389-88eeb6e58e83c4f6.png]: /images/20210809/8beccd55765847b0a605cb1c96f9fdef.png
[1179389-625d4e071f6f5787.png]: /images/20210809/b18430e3f1ad4ec9a0375e06cb55e5d1.png
[1179389-a67661e88572f3c7.png]: /images/20210809/70828972b0d3436987ec2244024b55b4.png
[1179389-8726cf6638b96e29.png]: /images/20210809/c27bdd1bf43045b098d29d925862b128.png
[1179389-8edae8b56acafe3a.png]: /images/20210809/66c8a161f9a84b07b2249246baecd762.png
[1179389-c1218f9f0b4a9445.png]: /images/20210809/d043dca41810441d981edefcd4242ffd.png
[1179389-c44330d082111fae.png]: /images/20210809/b5e281ce1650406394c95c74d92c521d.png
[1179389-253aa92af2cff479.png]: /images/20210809/0a0d5f7ab5cb42e6b099f1b7a143d2a9.png
[Prism]: https://links.jianshu.com/go?to=https%3A%2F%2Fgithub.com%2FPrismJS%2Fprism
[1179389-c2c393b0e5609a3b.png]: /images/20210809/fe91c93911c74614a8e0c9652c8dc8c5.png
[GitHub]: https://links.jianshu.com/go?to=https%3A%2F%2Fmp.weixin.qq.com%2Fs%2FIcbWYOZ_HXc9O8h0o62Wmg
[1179389-86575ddec7e9394d.png]: /images/20210809/0eb1e8ed1f614a46a56411da603020b9.png
[1179389-44bd94e8bba5f9b5.png]: /images/20210809/85cb7325bc4a4fae9d5b5557fb19254b.png
[1179389-94fed7218652ff6c.png]: /images/20210809/7527a1b200444a85a90c20f964919cbd.png
[1179389-690f7014e838b717.png]: /images/20210809/428903404b4d4378af4b13784c765910.png
[1179389-0cef268138809a97.png]: /images/20210809/93d99541d6094a4aa4b8120d3c616122.png
[https_itwanger.gitee.io_zero-learn-java]: https://links.jianshu.com/go?to=https%3A%2F%2Fitwanger.gitee.io%2Fzero-learn-java
[1179389-82ef9c8e114b1cff.png]: /images/20210809/b1de52630ff6475ca67e97da73fc2fe0.png
[1179389-6d2a51ad1da4554f.png]: /images/20210809/b016b544924443b887c8c2535a6c0d8e.png
[1179389-1ba2641a3a9f403f.png]: /images/20210809/5aa3e878067d47ac8de7a687f2f68bac.png
[1179389-6cbe36cdf8c18b66.png]: /images/20210809/9ab44f53572e495e9315730463951f2c.png
[https_github.com_itwanger_javaZero]: https://links.jianshu.com/go?to=https%3A%2F%2Fgithub.com%2Fitwanger%2FjavaZero
[https_gitee.com_itwanger_javaZero]: https://links.jianshu.com/go?to=https%3A%2F%2Fgitee.com%2Fitwanger%2FjavaZero
[https_itwanger.gitee.io_javazero]: https://links.jianshu.com/go?to=https%3A%2F%2Fitwanger.gitee.io%2Fjavazero
[1179389-56a33be44184f320.png]: /images/20210809/9253b9c72549434aa9ace8448ba2fb94.png
[https_pan.baidu.com_s_1qwomiFHW6vZdVo26heMctg]: https://links.jianshu.com/go?to=https%3A%2F%2Fpan.baidu.com%2Fs%2F1qwomiFHW6vZdVo26heMctg