Github+docsify打造个人文档web工具

简介

在日常开发中 前后端对接时 经常要写很多文档Api。docsify就是一个强大的文档生成工具 界面清新好 支持语法高亮和Markdown 语法，并且docsify 扩展了一些 Markdown 语法可以让文档更易读。像vue.js官网(https://cn.vuejs.org/)就是docsify 其中的一种注意 并且是目前用的的最多的主题

效果图如下

预览链接：https://github.com/ysyluminous/JavaLeaning

快速开始

首先先安装好npm和nodejs,这里就不做过多介绍了 自信安装即可 （https://blog.csdn.net/zimushuang/article/details/79715679）

安装docsify 推荐安装 docsify-cli 工具，可以方便创建及本地预览文档网站。

npm i docsify-cli -g
初始化项目

进入指定文件目录 如下：F:\ideWork\githubWork\test_docs
运行 docsify init ./docs
在这里插入图片描述
初始化成功后，可以看到 ./docs 目录下创建的几个文件

index.html 入口文件
README.md 会做为主页内容渲染
.nojekyll 用于阻止 GitHub Pages 会忽略掉下划线开头的文件
在这里插入图片描述

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

docsify serve docs
一个基本的文档网站就搭建好了，docsify还可以自定义导航栏，自定义侧边栏以及背景图和一些开发插件等等
更多配置请参考官方文档 https://docsify.js.org/#/zh-cn/quickstart

下面介绍docsify如何部署到Github 使用免费的站点
和 GitBook 生成的文档一样，我们可以直接把文档网站部署到 GitHub Pages 或者 VPS 上

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

docs/ 目录
master 分支
gh-pages 分支
上传文件至Github仓库 官方推荐直接将文档放在 docs/ 目录下，在设置页面开启 GitHub Pages 功能并选择 master branch /docs folder 选项。
在这里插入图片描述

此时等待几秒钟 就可以访问了 我这里使用了自定义域名

Github如何配置自定义域名
在根目录下创建CNAME文件 并配置你的阿里云或其它网站购买的域名
在这里插入图片描述

设置页面 Custom domain 更改域名
在这里插入图片描述

进入域名平台 进行解析 添加继续记录 ；类型为CNAME
在这里插入图片描述

解析后 等待十分钟既可开启了

官方文档 https://docsify.js.org/#/zh-cn/quickstart

预览链接：https://github.com/ysyluminous/JavaLeaning

有了 docsify我们就可以编写和下图一样的文档了，方便文档的查阅与长期维护。

通过 github 进行项目管理，随时随地都可以对文档查阅于修改更新。
首先我们需要先安装 npm（我有一篇文章介绍了 npm，如果遇到问题可以参考） 才能继续后续的安装
首先安装 docsify-cli（命令行界面）：
npm i docsify-cli -g

接下来就开始使用了，这里我以我正在整理的公司一个云平台文档（cloud-doc）为例介绍如何使用。
首先在 Desktop 创建一个文件夹：cloud-doc
cd 到当前目录
以上步骤推荐使用命令行操作，操作步骤截图如下：

初始化项目
如果想在项目的 ./docs 目录里写文档，直接通过 init 初始化项目。
docsify init ./docs

解释：./docs 目录开始是没有的，初始化之后才会出现。为什么说“想在./docs 目录里写文档”？
初始化之后如下图：

开始写文档

初始化成功后，可以看到 ./docs 目录下创建的几个文件
index.html 入口文件
README.md 会做为主页内容渲染
.nojekyll 用于阻止 GitHub Pages 会忽略掉下划线开头的文件
上面这句话是docsify 文档上描述的，但是我们在 ./docs目录下却只看到两个文件,如下图

我们以后编辑文档，就使用 VSCode。
本地预览网站
运行一个本地服务器通过 docsify serve 可以方便的预览效果，而且提供 LiveReload 功能，可以让实时的预览。默认访问 http://localhost:3000 。

 docsify serve docs

Loading提示
初始化时会显示 Loading… 内容，你可以自定义提示信息。
这个东西可有可无，顺带讲一下，在修改上图中所示的 index.html 文件。我们将默认的提示内容“Loding…”改为“正在加载，请稍候。。。”，如下图：
多页文档
如果需要创建多个页面，或者需要多级路由的网站，在 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文件的配置：

                                   
<script>
  window.$docsify = {
    loadSidebar: true
  }
</script>
<script src="//unpkg.com/docsify"></script>

接着创建 _sidebar.md文件，这个文件是需要我们自己手动创建的，如下图：

屏幕快照 2018-03-31 下午4.49.31.png
这个文件是干嘛用的呢？他可厉害了，我们想让侧边栏显示什么就在这个文件里写什么：
每一节显示什么内容，当然就需要另外创建每一个目录对应的文件，然后在这个文件里写内容了，注意每一个文件都必须以.md结尾。对于同一章节的内容我们又可以把他们放到一个文件夹里。

屏幕快照 2018-03-31 下午4.58.28.png
编辑好的内容要记得提交：
git add .
git commit -m “创建文档目录”
git push

插件

https://jhildenbiddle.github.io/docsify-themeable/#/themes?id=simple-dark

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*}