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

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

[TOC]

### 0. 前言

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

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

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

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

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

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

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

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

### 1. 要求

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

| 名称 | 简介                 | 官网                  |
| ---- | -------------------- | --------------------- |
| Git  | 分布式版本控制系统   | https://git-scm.com   |
| npm  | Node.js 的包管理工具 | https://www.npmjs.com |

此外，你还需要：

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

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

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

### 2. 快速安装docsify

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

![图：存放项目的文件夹](https://img.zxdmy.com/md/20210531203448.png)

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

![图：打开此文件夹命令行窗口](https://img.zxdmy.com/md/20210531203451.png)

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

```shell
npm i docsify-cli -g
```

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

```shell
docsify init ./docs
```

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

```shell
docsify serve docs
```

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

![图：创建项目](https://img.zxdmy.com/md/20210531203453.png)

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

![图：初始文件](https://img.zxdmy.com/md/20210531203457.png)

每个文件的作用如下：

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

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

![图：默认主页](https://img.zxdmy.com/md/20210531203459.png)

### 3. 自定义配置项

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

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

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

#### 3.1 修改主页内容

修改`README.md`：

![图：修改README文件](https://img.zxdmy.com/md/20210531203502.png)

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

![图：新内容](https://img.zxdmy.com/md/20210531203506.png)

#### 3.2 定制侧边栏

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

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

如下图：

![图：定制侧边栏](https://img.zxdmy.com/md/20210531203509.png)

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

![图：定制侧边栏](https://img.zxdmy.com/md/20210531203511.png)

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

![图：侧栏需要显示的内容](https://img.zxdmy.com/md/20210531203514.png)

3、在`_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)

```

如图：

![图：侧边栏书写格式](https://img.zxdmy.com/md/20210531203532.png)

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

![图：新的侧边栏](https://img.zxdmy.com/md/20210531203536.png)

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

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

如下图：

![图：修改目录层级](https://img.zxdmy.com/md/20210531203539.png)

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

![图：修改后的目录层级](https://img.zxdmy.com/md/20210531203545.png)

#### 3.3 定制导航栏

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

```js
loadNavbar: true, // 加载导航栏
```

如图：

![图：配置导航栏](https://img.zxdmy.com/md/20210531203549.png)

2、在根目录创建一个名为`_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)
```

如图：

![图：导航栏书写格式](https://img.zxdmy.com/md/20210531203551.png)

3、查看导航栏：

![图：导航栏效果](https://img.zxdmy.com/md/20210531203555.png)

#### 3.4 增加标题与Git右上角标

1、修改`index`配置信息：

![图：配置标题与角标](https://img.zxdmy.com/md/20210531203559.png)

2、查看预览页面：

![图：修改效果](https://img.zxdmy.com/md/20210531203602.png)

#### 3.5 增加搜索框

1、修改`index`配置信息：

`引入JS文件`：

```js
  
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
```

`修改配置`：

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

如图：

![图：配置搜索框](https://img.zxdmy.com/md/20210531203605.png)

2、查看预览页面：

![图：搜索框效果](https://img.zxdmy.com/md/20210531203609.png)

#### 3.6 增加封面

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

```js
coverpage: true, // 开启封面
```

如图：

![图：配置封面](https://img.zxdmy.com/md/20210531203613.png)

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

```

![logo](_media/icon2.png)

# zxdmy.com <small></small>

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

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

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

如图：

![图：封面书写格式](https://img.zxdmy.com/md/20210531203619.png)

3、效果：

![图：封面效果](https://img.zxdmy.com/md/20210531203623.png)

#### 3.7 更多插件

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

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

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

### 4. 部署到Git

>   目前有两种部署方案，一种是`部署至Gitee`，另一种是`部署到GitHub`。
>
>   下文以部署到GitHub为例。

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

![图：创建Git项目](https://img.zxdmy.com/md/20210531203627.png)

>   **为什么要同名？**
>
>   这样的话，你的WiKi网站的域名就是：https://zxacademy.github.io/
>
>   如果使用其他的仓库名，如`blog`，那么你的WiKi网站域名就是：https://zxacademy.github.io/blog
>
>   **为什么要公开仓库？**
>
>   GitHub私有仓库开启Pages功能需要付费。

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

![图：复制Git项目地址](https://img.zxdmy.com/md/20210531203631.png)

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

![图：打开Git Bash](https://img.zxdmy.com/md/20210531203636.png)

4、输入`初始化命令`：

```bash
git init
```

如图：

![图：初始化Git](https://img.zxdmy.com/md/20210531203639.png)

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

![图：初始化效果](https://img.zxdmy.com/md/20210531203642.png)

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

![图：增加忽略文件](https://img.zxdmy.com/md/20210531203646.png)