使用docsify+Git搭建自己的WiKi网站

0. 前言

身为技术人，一方面需要时刻更新自己的技术储备，学习最新的技术，另一方面在工作和项目开发时，面对遇到的各种各样的BUG，需要记住各式各样的对策。

生而为人，遗忘是最大的敌人。将学习到的知识点，解决BUG的对策，整理成文档，或许是对抗遗忘的最佳方案。

这诸多的技术文档，以怎样的方式进行展示？

每人都有自己的选择方案：

• 有人使用博客系统进行记录，如CSDN、博客园、简书、自建博客；
• 有人使用笔记软件，如印象笔记、有道云笔记；
• 有人使用第三方WiKi系统，如语雀、看云；
• 还有人，使用Git搭建属于自己的WiKi网站（文档网站），分享自己的笔记。

目前，可用的WiKi网站开源项目中，比较火的有Hexo、GitBook、VuePress、docsify等。

每个开源项目都有自己的优点。而docsify，是轻量级最高、自定义化程度最高的项目。

本文将讲述如何使用docsify+Git搭建自己的WiKi网站。

本文首发地址：https://mp.weixin.qq.com/s/CBsg8fcCawYq2LuJcwRH3Q，作者：拾年之璐

1. 要求

在搭建之前，你的计算机需要安装以下环境：

此外，你还需要：

• 掌握Markdown文档语法，docsify只能部署Markdown文档；
• 拥有Gitee/GitHub账号，用来部署WiKi系统；
• 掌握简单的HTML、JS语法，index文件需要自己配置。

接下来我们将从以下几个方面详细讲解如何使用docsify+Git搭建自己的WiKi网站：

• 快速安装docsify
• 自定义配置项
• 部署到Git

2. 快速安装docsify

1、创建好安装docsify的文件夹，比如：

2、在上图的地址栏里输入cmd，按回车，打开命令行：

3、使用如下命令安装 docsify-cli 工具：

npm i docsify-cli -g

4、使用如下命令初始化一个名为docs的项目：

docsify init ./docs

5、使用如下命令本地运行并预览网站：

docsify serve docs

如下图是各个命令的执行过程。自动生成docs项目文件，并显示运行的网站地址为http://localhost:3000。

进入docs项目，有三个默认的初始化文件：

每个文件的作用如下：

• index.html 网站入口文件
• README.md 做为主页内容渲染
• .nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件

浏览器访问 http://localhost:3000，即可看到网站效果：

3. 自定义配置项

默认生成的网站效果，并非我们所需要的。

根据实际需求增加一些插件，更能满足我们的需求。

使用Web开发工具（WebStorm、PhpStorm等）打开docs文件，在编辑器中可以更好地编辑。

3.1 修改主页内容

修改README.md：

本地网站无需重启，刷新即可显示最新的内容：

3.2 定制侧边栏

1、打开index.html文件，找到<script>脚本处，增加配置 loadSidebar 选项，开启侧边栏。

loadSidebar: true, // 增加：自动加载侧边栏

如下图：

2、在根目录创建一个名为_sidebar.md的文件：

如果有如下图所示的系列文档需要在侧边栏进行展示：

3、在_sidebar.md文件中，按照如下格式写入侧边栏内容：

<!-- 侧边栏 docs/_sidebar.md -->

- Laravel基础笔记
  - [1. 创建项目](/laravel/base/1.%20创建项目.md)
  - [2. 路由的基础知识](/laravel/base/2.%20路由的基础知识.md)
  - [3. 控制模块基础知识](/laravel/base/3.%20控制模块基础知识.md)
  - [4. 数据库操作](/laravel/base/4.%20数据库操作.md)
<!-- 以下略 -->

如图：

4、本地预览网站自动加载了侧边栏：

5、在index的配置文件中，增加subMaxLevel配置项，增加生成目录的层级：

subMaxLevel: 4, // 生成目录的最大层级

如下图：

修改后的效果如下图，文章内的标题也可作为侧栏显示出来：

3.3 定制导航栏

1、index页配置 loadNavbar选项，开启导航栏：

loadNavbar: true, // 加载导航栏

如图：

2、在根目录创建一个名为_navbar.md的文件，并按如下格式写入导航栏信息：

<!-- _navbar.md 上面的导航栏  -->

* 我的平台

  * [知行达摩院](https://www.zxdmy.com)
  * [微信公众号](https://img.zxdmy.com/md/20210129164325.jpg)
  * [CSDN](https://cxhit.blog.csdn.net/)
  * [Gitee](https://gitee.com/ZXAcademy)
  * [GitHub](https://github.com/ZXAcademy)


* 联系我们
  * [邮箱](contacts/email.md)
  * [电话](zh-contacts/phone.md)

如图：

3、查看导航栏：

3.4 增加标题与Git右上角标

1、修改index配置信息：

2、查看预览页面：

3.5 增加搜索框

1、修改index配置信息：

引入JS文件：

  <!--搜索插件-->
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

修改配置：

      // 搜索框的完整配置参数
      search: {
        maxAge: 86400000, // 过期时间，单位毫秒，默认一天
        paths: [], // or 'auto'
        placeholder: '输入内容检索',
        noData: '未检索到结果',
        depth: 1,// 搜索标题的最大层级, 1 - 6
        hideOtherSidebarContent: false, // 是否隐藏其他侧边栏内容
      }

如图：

2、查看预览页面：

3.6 增加封面

1、修改index中的配置项coverpage，开启封面：

coverpage: true, // 开启封面

如图：

2、在根目录创建一个名为_coverpage.md的文件，并按如下格式写入封面信息：

<!-- _coverpage.md 封面 -->

![logo](_media/icon2.png)

# zxdmy.com <small></small>

> 知行达摩院 - 学无止境，知行致远！

- 记录课程学习笔记
- 记录科学研究进展
- 记录项目研发历程

[知行达摩院](https://zxdmy.com)
[开始使用](#欢迎使用)

如图：

3、效果：

3.7 更多插件

当然还有更多插件，比如代码复制、图片缩放、翻页、字数统计等。

插件的配置和使用方式大同小异。有的插件需要添加JS和增加配置项，有的插件只需要添加JS。

需要更多插件可查阅官网开发文档：https://docsify.js.org

本文首发地址：https://mp.weixin.qq.com/s/CBsg8fcCawYq2LuJcwRH3Q，作者：拾年之璐

4. 部署到Git

目前有两种部署方案，一种是部署至Gitee，另一种是部署到GitHub。

下文以部署到GitHub为例。

1、新建一个与GitHub用户名同名的公开仓库（Public），如下图所示：

为什么要同名？

这样的话，你的WiKi网站的域名就是：https://zxacademy.github.io/

如果使用其他的仓库名，如blog，那么你的WiKi网站域名就是：https://zxacademy.github.io/blog

为什么要公开仓库？

GitHub私有仓库开启Pages功能需要付费。

2、复制仓库地址，如图所示：

3、访问本地WiKi项目的根目录，右击，选择 Git Bash Here：

4、输入初始化命令：

git init

如图：

这时，项目根目录多了一个名为 .git 的文件夹

这里建议在项目根目录中增加.gitignore 文件，屏蔽.git和.idea文件夹及其子目录文件：

5、在GitHub 的项目页面，复制仓库地址，然后在上面的 bash 窗口中，输入如下命令并执行：

git remote add origin 仓库地址

如：

git remote add origin https://github.com/ZXAcademy/ZXAcademy.git

6、使用如下命令，将码云上的仓库 pull 到本地（注意本地项目中不要有和仓库中重名的文件，比如README.md、LICENSE等初始化仓库时产生的文件）

git pull origin master

如果远程仓库为空，会报如下错误，忽略，继续执行。如图：

7、使用如下命令，将项目所有文件添加到git本地缓冲区：

git add .

这里末尾的点（.），表示当前目录下的所有文件

8、使用如下命令为本次提交添加备注：

git commit -m '新添加的文件内容描述'

如图：

使用如下命令，将项目推送到GitHub：

git push origin master

图：

9、前往GitHub网站查看上传成功的文件：

10、按照下图开启Git Page服务：

然后访问给出的site即可访问自定义的WiKi网站：

https://zxacademy.github.io/zxacademy

为什么我这里直接访问https://zxacademy.github.io 不行呢？

因为我的GitHub用户名为ZXAcademy，含有大写字母，所以不行。

如果以后需要增删改文章，直接修改后，push至Git仓库，即可实时更新WiKi网站。

以上就是使用docsify+Git搭建自己的WiKi网站的全部内容。

本文首发地址：https://mp.weixin.qq.com/s/CBsg8fcCawYq2LuJcwRH3Q，作者：拾年之璐