Docsify是什么

一个神奇的文档站点生成器。

docsify 可以快速帮你生成文档网站。不同于 GitBook、Hexo 的地方是它不会生成静态的 .html 文件,所有转换工作都是在运行时。如果你想要开始使用它,只需要创建一个 index.html 就可以开始编写文档并直接部署在 GitHub Pages

Docsify特性

  • 无需构建,写完文档直接发布
  • 容易使用并且轻量 (压缩后 ~21kB)
  • 智能的全文搜索
  • 提供多套主题
  • 丰富的 API
  • 支持 Emoji
  • 兼容 IE11
  • 支持服务端渲染 SSR

搭建方法

新建 GitHub repository

登录 GitHub 账号,新建 respository,名字为:doc.kakarrot.com

Docsify安装

1
2
3
node -v # 查看node版本
npm -v # 查看npm版本
npm i docsify-cli -g #-g表示全局安装,npm默认为当前项目安装

Docsify部署

1
docsify init ./docs #新建博客文件夹

现在就可以在 localhost:4000 查看网页了

文件目录概览

初始化成功后,可以看到 ./docs 目录下创建的几个文件

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

直接编辑 docs/README.md 就能更新文档内容。

本地预览

通过运行 docsify serve 启动一个本地服务器,可以方便地实时预览效果。默认访问地址 http://localhost:3000

1
docsify serve docs

修改配置

index.html文件内windows.$docsify中进行添加配置。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta charset="UTF-8">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
//...
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>

Hexo 部署到 GitHub

doc.kakarrot.com下新建文件CNAME

更新文档,每次提交更新仓库。

CNAME
1
kakarrot.com

域名解析

登录阿里云域名管理 添加 1 条解析记录

记录类型 主机记录 记录值
CNAME doc kakarrot.com

文档上线

解析后稍等 3-5min,强制刷新浏览器即可看到新站点。

博客同步

将源文件夹放至坚果云等同步网盘,实时同步。