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

清疚 2022-04-25 07:34 374阅读 0赞

## 简介 ##

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

## 效果图如下 ##

预览链接：[https://github.com/ysyluminous/JavaLeaning][https_github.com_ysyluminous_JavaLeaning]

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzMzODQwMjUx_size_16_color_FFFFFF_t_70]

## 快速开始 ##

首先先安装好npm和nodejs,这里就不做过多介绍了 自信安装即可 （[https://blog.csdn.net/zimushuang/article/details/79715679）][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][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_docsify.js.org_zh-cn_quickstart]

预览链接：[https://github.com/ysyluminous/JavaLeaning][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][http_localhost_3000] 。

docsify serve docs

Loading提示  
初始化时会显示 Loading… 内容，你可以自定义提示信息。  
这个东西可有可无，顺带讲一下，在修改上图中所示的 index.html 文件。我们将默认的提示内容“Loding…”改为“正在加载，请稍候。。。”，如下图：  
多页文档  
如果需要创建多个页面，或者需要多级路由的网站，在 docsify 里也能很容易的实现。例如创建一个 [guide.md][] 文件，那么对应的路由就是 /\#/guide。  
假设你的目录结构如下：

那么对应的访问页面将是:

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文件的配置：

接着创建 \_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][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\*\}

[https_cn.vuejs.org]: https://cn.vuejs.org/
[https_github.com_ysyluminous_JavaLeaning]: https://github.com/ysyluminous/JavaLeaning
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzMzODQwMjUx_size_16_color_FFFFFF_t_70]: /images/20220125/6ff55b93ebdd4e62933b33ba06635c5f.png
[https_blog.csdn.net_zimushuang_article_details_79715679]: https://blog.csdn.net/zimushuang/article/details/79715679%EF%BC%89
[README.md]: http://README.md
[https_docsify.js.org_zh-cn_quickstart]: https://docsify.js.org/#/zh-cn/quickstart
[http_localhost_3000]: http://localhost:3000
[guide.md]: http://guide.md
[https_jhildenbiddle.github.io_docsify-themeable_themes_id_simple-dark]: https://jhildenbiddle.github.io/docsify-themeable/#/themes?id=simple-dark