唠唠闲话

相关链接
官方文档：docsify
参考教程：使用 docsify 写开源文档+部署到云服务器
B 站视频：使用git和docsify进行远程服务器博客搭建

安装及初始化

安装 nodejs，这里安装的是 v18 版本

1
2
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - # 再次执行第一行代码
sudo apt-get install -y nodejs

用 npm 安装 docsify

1
npm i docsify-cli -g

初始化项目

1
2
docsify init ./docs
docsify serve docs

默认在 3000 端口启动，本地可以通过 http://localhost:3000 访问。

目录结构

1
2
3
4
5
# tree . -a
docs
├── .nojekyll
├── README.md
└── index.html

这里 index.html 用于定制样式，余下的 Markdown 文件为文档内容。

.nojekyll 文件（ChatGPT）：在部署 docsify 文档网站时，我们通常会将整个仓库上传到 GitHub 或 GitLab 等代码托管平台，并且使用该平台提供的静态网站托管服务来让用户可以在线浏览文档。但是，在使用该服务时，平台可能会默认忽略以 _ 开头的文件，从而导致 docsify 中一些特殊文件无法被正确处理或显示，例如 _sidebar.md、_coverpage.md 等。此时，我们可以在仓库根目录下创建一个名为 .nojekyll 的空文件，来告诉平台不要忽略这些文件。

定制化

这部分对 index.html 进行修改，也涉及三个常用文件：_sidebar.md、_coverpage.md 和 _navbar.md，其分别控制侧边导航栏、封面和顶部导航栏。

在 index.html 后边追加这段 js 代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<script>
  window.$docsify = {
    name: 'RexWzh',
    repo: 'https://github.com/RexWzh',
    loadNavbar: true, // 加载自定义顶部导航栏
    loadSidebar: true, // 加载自定义侧边栏
    maxLevel: 2, // 默认情况下会抓取文档中所有标题渲染成目录，可配置最大支持渲染的标题层级。
    subMaxLevel: 4, // 生成目录的最大层级
    mergeNavbar: true, // 小屏设备下合并导航栏到侧边栏
    alias: { // 定义路由别名，可以更自由的定义路由规则。 支持正则
      '/.*/_sidebar.md': '/_sidebar.md',//防止意外回退
      '/.*/_navbar.md': '/_navbar.md'
    },
    coverpage: true, // 封面
    search: {
      placeholder: '搜索',
      noData: '找不到结果!',
      depth: 3
    },
  }
</script>

name 参数和 repo 参数根据自己的情况修改，下边讲解其他参数。

侧边导航栏

侧边栏的内容可以通过 _sidebar.md 文件来配置，该文件需要放在 docs 目录下，其内容格式如下：

1
2
3
4
5
- [README](README.md)
- 编程实战
  - [Rubik S Cube](编程实战/python/rubik-s-cube.md)
- 编程教程
  - [Julia Algebra](编程教程/julia/julia-algebra.md)

可以通过执行 docsify generate . 根据当前目录的文件结构生成 _sidebar.md 文件。

20230619001659

顶部导航栏

顶部导航栏的内容通过 _navbar.md 文件来配置，参考格式：

1
2
3
4
5
6
7
8
* 演示
  * [后台管理]()
  * [小程序端]()

* 项目地址
  * [后台平台]()
  * [后台管理]()
  * [学习教程]()

实现效果：
20230619001902

封面配置

封面配置通过 _coverpage.md 文件来配置，参考格式：

1
2
3
4
5
![logo](images/logo.png)
# 实验室工作文档
> 实验室文档及相关教程
[GitHub](https://github.com/RexWzh)
[Get Started](README.md)

实现效果：
20230619002345

代码高亮及复制

在 index.html 后边追加

需要支持的语言

1
2
3
<script src="//unpkg.com/prismjs/components/prism-bash.js"></script>
<script src="//unpkg.com/prismjs/components/prism-sql.js"></script>
<script src="//unpkg.com/prismjs/components/prism-python.js"></script>

以及剪贴板功能

1
<script src="//unpkg.com/docsify-copy-code"></script>

服务器部署

这部分可以参照之前的博客：

  1. 使用 GitHub 部署静态网站 hexo | 博客框架搭建：上传到 Github 后开启 Github Page。
  2. 使用 Nginx 部署的方法：服务器教程(番外) | hexo 博客部署

下边重点介绍服务器部署的方法。

远程同步 – 使用 Git 钩子

远程同步 – 直接连接

下边是一种更简单粗暴的方式。

将本地仓库复制到远程服务器，比如 /var/www/docs 目录

1
scp -r docs <remote_server>:/var/www/docs

服务端将仓库设置为裸仓库

1
2
3
cd /var/www/docs
git config --bool core.bare true
git config receive.denyCurrentBranch updateInstead

本地端连接仓库

1
2
git remote add origin <remote_server>:/var/www/docs
git push origin main

配置 Nginx

特殊定制

设置访问密码