---
title: Docsify
top: true
cover: true
toc: true
mathjax: false
summary: >-
实用Docisy搭建个人博客
tags:
- Docsify
- 博客搭建教程
categories:
- "折腾"
reprintPolicy: cc_by
author: TianZD
abbrlink: 2eeac462
date: 2022-04-27 12:23:53
coverImg:
img:
password:
---
# Docsify
[toc]
[codesheep微信文章](https://mp.weixin.qq.com/s?__biz=MzU4ODI1MjA3NQ==&mid=2247510629&idx=1&sn=48e481b9f176ebeb2d68342af3f33317&chksm=fddd7ca1caaaf5b73efe05dcb5b87c570344708e2a7bddffb5c8bd08638b631e595a4d2b646c&mpshare=1&scene=1&srcid=0223V1apWEBHMQrFHzWwPQiN&sharer_sharetime=1645581220908&sharer_shareid=9615bd3fd5ee967a5d2b03b78f23d393#rd)
## 框架对比
其实做这种网站，完全不用自己手写，现成的工具太多了，这地方随便举几个典型例子吧。
### Hexo
这是一个大家用得非常广泛的静态博客，两年前咱们这里就已经演示过它的使用以及部署上线。
工具地址：https://hexo.io
### VuePress
一款基于Vue框架驱动的静态网站生成器，比较符合用于知识文档网站的建站需求，现在用的小伙伴也很多。
工具地址：https://vuepress.vuejs.org/
### docsify
docsify同样是一个很好用的知识文档网站生成框架，轻量简便，而且无需构建，写完内容就可以直接发布，界面干净又卫生。
工具地址：https://docsify.js.org/
- 无需构建，写完文档直接发布
- 容易使用并且轻量 (压缩后 ~21kB)
- 智能的全文搜索
- 提供多套主题
- 丰富的 API
- 支持 Emoji
- 兼容 IE11
- 支持服务端渲染 SSR ([示例](https://github.com/docsifyjs/docsify-ssr-demo))
### Gitbook
GitBook也是一个可以用来制作知识库文档以及精美电子书网站的工具框架，不少技术电子书文档都是用它来做的。
工具地址：https://github.com/GitbookIO/gitbook
## 前置环境
docsify唯一需要的一个前置工具就是`npm`工具
查看是否安装及版本
如果没有的话，直接在本地电脑上安装一个`node.js`环境就可以了。
不管是macOS还是Windows系统，直接去`https://nodejs.org/`官网下载个安装包就可以了，直接下一步下一步即可，安装完成之后会包含npm工具。
## 安装Docsify
```bash
npm install -g docsify-cli
docsify -v //查看版本
```
## 开始
### 新建项目文件夹
接下来我们从零开始来新建一个本地的项目文件夹。
可以在任何地方新建，名字也可以随便命名，这里取名为`repository`，代表的意思是知识仓库
### 初始化网站
进入到上述新建的项目文件夹`repository`，执行如下命令即可初始化网站，非常简单：
```bash
docsify init
```
初始化成功之后，命令行里也会输出对应初始化成功的打印信息。
### 启动本地预览
```bash
docsify serve
```
我们会发现docsify会帮我们在`localhost:3000`启动一个知识库网站。
然后在浏览器打开`http://localhost:3000`即可看见网站效果。
当然，这时候的页面看起来非常简陋，几乎什么也没有。
接下来我们来看一看网站的文件结构，这个工具是如何做到这么快就可以启动一个网站的呢。
## 项目结构
上文执行完`docsify init`命令成功初始化网站后，docsify会在项目文件夹里自动帮我们生成以下两个文件：
- `index.html`：网站主入口文件和配置文件
- `README.md`：网站内容文件。支持Markdown格式，docsify可以帮我们把该Markdown源文件渲染成网页进行展示。
所以我们只需要直接编辑生成的这个README.md文件就能更新网站的内容。
`coverpage`：封面
`navbar`：导航栏
`sidebar`：侧边栏
`logo.ico`：网页图标
## 配置
https://blog.csdn.net/Lonelyooacz/article/details/103490545
### 页面和URL路径
如果需要创建多个页面，或者需要多级路由的网站，在docsify里能很容易实现。
打比方说，你的目录结构如下：
```
.
└── repository
├── README.md
├── test.md
└── content
├── README.md
└── bigdata.md
```
那么对应的页面访问URL地址将是:
```
repository/README.md => http://127.0.0.1:3000/
repository/test.md => http://127.0.0.1:3000/test
repository/content/README.md => http://127.0.0.1:3000/content/
repository/content/bigdata.md => http://127.0.0.1:3000/content/bigdata
```
所以只需要在项目目录里添加其他`.md`文件，或者目录层级，即可形成多页面网站，非常简单易懂！
### 修改主题
docsify提供了多套主题可供使用。
直接修改`index.html`中引入的CSS文件即可修改网站主题。
目前提供有好几套主题可供选择：
```html
```
### 设置封面
像上文刚刚这样创建出来的网站其实是没有封面的，如果需要添加封面，可以通过在`index.html`中设置`coverpage`参数为`true`来实现：
```html
coverpage: true
```
这样既可开启封面功能。
封面功能开启之后，我们可以直接去项目文件夹里创建一个`_coverpage.md`文件来制作封面内容。
比如我们这地方，添加了`_coverpage.md`文件之后，在里面写上如下几段文字：
```markdown
- 本站取名为r2coding，即Road To Coding，意为编程自学之路，是自学编程以来所用资源和分享内容的大聚合。旨在为编程自学者提供一系列清晰的学习路线、靠谱的资源、高效的工具、和务实的文章，方便自己也方便他人。**网站内容会持续保持更新，欢迎收藏品鉴！**
## 记住，一定要善用 `Ctrl+F` 哦！
[**联系作者**](https://github.com/rd2coding/Road2Coding)
[**开启阅读**](README.md)
```
在网页上渲染之后，即可看到如下效果：
所以其操作是非常简单的。
### 设置导航栏
像上文刚刚这样创建出来的网站顶部右上角其实是没有导航栏的，如果需要添加导航栏，可以通过在`index.html`中设置`loadNavbar`参数来开启：
```
loadNavbar: true
```
导航栏功能开启之后，我们可以直接去项目文件夹里创建一个`_navbar.md`文件来制作导航栏菜单内容。
比如我们这地方，添加了`_navbar.md`导航栏之后的效果大致如下：
### 设置章鱼猫
可以通过在`index.html`中设置`repo`参数来开启网站右上角的章鱼猫链接的小图标功能
```
repo: 'https://github.com/rd2coding/Road2Coding'
```
设置完成后的效果如下，还是很萌的，鼠标移到上面，小尾巴还能摇一摇。
### 设置logo
可以通过在`index.html`中设置`name`参数或者`logo`参数来开启网站侧边栏左上角的标题或者logo显示功能：
```
name: 'Road To Coding',
logo: 'https://cdn.jsdelivr.net/gh/justacoder99/r2coding@master/img/r2coding_logo_sidebar.1na4hwjnopq8.png'
```
比如这地方设置了logo图片之后，效果大致如下：
### 设置tabs
在`index.html`中添加 docsify-tabs 插件。
```html
```
查看[选项](https://jhildenbiddle.github.io/docsify-tabs/#/?id=options)部分并根据需要进行配置。
```html
window.$docsify = {
// ...
tabs: {
persist : true, // default
sync : true, // default
theme : 'classic', // default
tabComments: true, // default
tabHeadings: true // default
}
};
```
查看[自定义](https://jhildenbiddle.github.io/docsify-tabs/#/?id=customization)部分并根据需要设置主题属性。
```html
```
使用HTML 注释定义选项卡集`tabs:start`。`tabs:end`
HTML 注释用于标记选项卡集的开始和结束。当 Markdown 在您的 docsify 站点（例如 GitHub、GitLab 等）之外呈现为 HTML 时，使用 HTML 注释可防止显示与选项卡相关的标记。
```markdown
...
```
使用**标题 + 粗体**标记定义选项卡集中的选项卡。
标题文本将用作选项卡标签，所有后续内容将与该选项卡相关联，直到下一个选项卡或`tab:end`评论的开始。使用标题 + 粗体标记允许使用标准标记定义选项卡，并确保选项卡内容在您的 docsify 站点（例如 GitHub、GitLab 等）之外呈现时显示带有标题。
```markdown
#### **English**
Hello!
#### **French**
Bonjour!
#### **Italian**
Ciao!
```
#### **English**
Hello!
#### **French**
Bonjour!
#### **Italian**
Ciao!
效果：
### alert插件
https://github.com/fzankl/docsify-plugin-flexible-alerts
### 首页html文件
```html
Tian's Blog
🏃🏃🏃💨 加载中...
```
## Nginx部署准备
对于这类网站的部署，我们当然可以部署到`GitHub Pages`服务或者`Gitee Pages`服务上去
也直接将其部署到云服务器上去。
### 安装服务器软件
这里选用Nginx这个Web服务器来驱动网站，因为Nginx服务器除了本身非常轻量，稳定，不耗资源之外，而且性能还好，还特别能扛并发。
- 首先准备一个`nginx-1.17.10.tar.gz`的安装包，我们将其直接上传到云服务器的`root`⽬录下
- 在`/usr/local/`下创建`nginx`⽂件夹并进⼊
```shell
cd /usr/local/
mkdir nginx
cd nginx
```
- 将Nginx安装包解压到`/usr/local/nginx`中即可
```shell
tar zxvf /root/nginx-1.17.10.tar.gz -C ./
```
解压完之后，在`/usr/local/nginx`⽬录中会出现⼀个`nginx-1.17.10`的目录
- 预先安装额外的几个依赖
```shell
yum -y install pcre-devel
yum -y install openssl openssl-devel
```
- 接下来编译安装Nginx即可
```shell
cd nginx-1.17.10
./configure
make && make install
```
安装完成后， Nginx的可执行文件位置位于
```shell
/usr/local/nginx/sbin/nginx
```
其配置⽂件则位于：
```
/usr/local/nginx/conf/nginx.conf
```
- 启动Nginx
直接执⾏如下命令即可
```shell
/usr/local/nginx/sbin/nginx
```
- 如果想停⽌Nginx服务，可执⾏：
```shell
/usr/local/nginx/sbin/nginx -s stop
```
- 如果修改了配置⽂件后想重新加载Nginx，可执⾏：
```shell
/usr/local/nginx/sbin/nginx -s reload
```
### 上传网站到云服务器
比如，我们可以直接在`/usr/local/nginx/`目录中创建一个`www`文件夹，用于存放我们本地的项目文件夹。
然后我们可以直接将本地的项目文件夹`repository`上传到`www`目录里即可
### Nginx配置和访问
接下来我们打开路径`/usr/local/nginx/conf/nginx.conf`下的Nginx服务器配置文件，修改其中最关键的一个`location /`下的`root`目录配置为项目文件夹的路径即可
```shell
location / {
root /usr/local/nginx/www/repository;
index index.html index.htm;
}
```
然后我们直接在浏览器中访问云服务器的公网IP，就可以访问该知识库网站了：
最后再将域名和这个IP一绑定，就OK了
## nginx服务器添加密码访问
### 通过htpasswd命令生成用户名及对应密码数据库文件
```shell
htpasswd -c /htpasswd/passwd.db test
```
说明：此命令是使用Crypt算法生产一个加密文件passwd.db。
- test是用户名
- /htpasswd/passwd.db 是密码文件存放地址
- htpasswd apache的生产密码的插件
把 passwd.db文件设置为777权限
```shell
chmod 777 文件名
```
### nginx域名配置文件修改
```shell
location / {
root html;
index index.html index.htm index index.jpg;
auth_basic 'Restricted'; # 认证名称，随意填写
auth_basic_user_file /htpasswd/passwd.db; # 认证的密码文件，需要生产。
}
```
如果没有安装apache，可以安装如下软件，就有htpasswd这个命令了
```shell
yum -y install httpd-tools
yum -y install httpd #安装httpd
which htpasswd #查看是否安装
rpm -qf /usr/bin/htpasswd #查看是否安装
htpasswd -cb /usr/local/nginx/conf/htpasswd ceshi 123789 #生成密码文件
chmod 400 /usr/local/nginx/conf/htpasswd #为了安全设置文件权限
```
然后重启nginx服务器即可实现nginx服务器添加密码
```shell
#3、检查语法并重启
/usr/local/nginx/sbin/nginx -t
/usr/local/nginx/sbin/nginx -s reload
```
## 定时git pull和重启nginx
前提：www中已经设置了git仓库，这里为www下的NoteBooks文件夹
- 拉取最新代码
```shell
git pull
```
- 在NoteBooks下新建自动化脚本
```shell
vim 111gitpull.sh
```
- 输入：
```shell
#!/bin/bash
cd /usr/local/nginx/www/NoteBooks
git pull
/usr/local/nginx/sbin/nginx -s reload
```
- 设置自动启动，这里每30分钟拉取一次
进入root用户
编辑cron脚本
```shell
crontab -e
```
输入：
```shell
*/30 * * * * /usr/local/nginx/www/NoteBooks/111gitpull.sh
```
- 将服务自动启动
```shell
vim /etc/rc.d/rc.local
```
这个脚本的末尾加上：
```shell
/sbin/service crond start
```
## 配置Gittalk
### 第一步：创建OAuth Application
这里假设你的[github](https://so.csdn.net/so/search?q=github&spm=1001.2101.3001.7020)仓库已经创建好，docsify也已经安装使用中。申请授权地址[点击这里](https://github.com/settings/applications/new)
几个参数解释：
- Application name：项目名，随便填
- Homepage URL：博客地址，也就是要访问的地址，我的是https://waldeincheng.github.io/Python-Notes
- Application description：应用描述，随便填，我的是waldeincheng’s blog
- Authorization callback URL:可以指向新的URL,或者跟上面的Homepage URL一样即可
完成后会生成相应的`clientID`和`clientSecret`
### 第二步：配置gittalk
docsify下有一个index.html配置文件，打开，添加上
```
```
配置：
- , css文件放到index.html里的`\`标签里
- `clientID`:刚刚获取的ID
- `clientSecret`:刚刚获取的授权密码
- `repo`:仓库名
- `owner`：github用户名
- `admin`：[‘github用户名’]
保存修改，git提交上去就行了，显示格式如图
## Windows自动启动Docsify
使用 `.bat` 的话，会显示一个短暂的黑窗口所以要想后台静默运行，需要用到 `.vbs` 脚本
### 创建vbs脚本
在docsify目录下新建一个vbs文件，内容如下
```vbscript
set ws=WScript.CreateObject("WScript.Shell")
ws.Run "docsify serve",0
```
该脚本含义为在当前目录下执行 `docsify serve` 命令
### 开启启动
windows 开机会自动调用下列两个文件夹下的可执行文件
用户目录的自启文件夹：
```text
C:\Users\用户名\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup
```
> 注意用户名，每个用户都不相同
所有用户都会执行的全局自启文件夹
```text
C:\ProgramData\Microsoft\Windows\Start Menu\Programs\StartUp
```
在脚本上右键创建快捷方式，然后将这个快捷方式放到上述两个文件夹任意一个即可