docsify,一款神奇的文档网站生成器,可以快速生成文档网站。不同于 GitBook、Hexo 的地方是,它不会生成静态的 .html 文件,所有转换工作都是在运行时。如只需要创建一个 index.html 就可以开始编写文档并直接部署在github pages上(小清新的样式,干净简洁)
docsify更多配置参考官方文档说明:https://docsify.js.org/#/zh-cn/quickstart
安装node.js、docsify环境
# node环境安装配置
# 使用npm指令安装docsify
npm i docsify-cli g
初始化项目(构建本地存档)
# 创建一个项目构建项目存档(可同步到github或者其他版本管理仓库中便于维护)
# 初始化项目
docsify init ./docs
# 项目构建完成,则可看到对应项目下生成文件
- index.html 入口文件
- README.md 主页内容渲染
- .nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件
文档更新、本地预览
# 编辑index.html文件,更新文档内容
# 本地预览
docsify serve docs
创建项目构建本地存档,手动生成index.html,构建内容如下所示
<!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>
借助python启动静态服务器预览网站
# python2
cd docs && python -m SimpleHTTPServer 3000
# python3
cd docs && python -m http.server 3000
创建远程仓库存放文档内容
# 构建思路和hexo项目部署类似,借助github.io提供的二级域名进行构建
# github pages支持从三个地方读取文件
- docs/目录 # master/docs
- master分支 # master分支(/(root))
- gh-pages分支 # 在子仓库中构建gp-pages
# 创建不同的子仓库,用于分类存储笔记信息:
访问路径:https://[userName].github.io/[repoName]/#/
在指定仓库下配置自定义域名(或者直接在github pages配置页面中手动配置)
方式1:在指定仓库下添加CNAME文件,引入域名
# 域名可自定义前缀
docs.xxx.com
方式2:Settings->Pages->custom domain
由于之前笔记梳理一直基于Typora编辑+github管理的概念,对于图片资源的管理也是基于assets资源文件夹引用的方式处理(考虑到资源安全性和第三方的不可预测性,所以没有选择基于图床的方式存储资源,而是在md文件基础上构建一个同名的.assets文件夹存储图片资源),在hexo项目构建笔记迁移的时候对于图片资源的处理暂时没有一个比较友好的方案(如果是采用本地引用的方式则可能导致项目后期维护、迭代的问题,hexo项目推荐使用图床方式加载图片资源)
从多个方面考虑,采用docsify+typora+github的方式构建个人知识库,即很好地解决了此前项目笔记的迁移,又能够在docsify的扩展基础上更好地维护自身的知识体系、便于随时翻阅巩固
在docsify项目中,可以直接将此前的md文件进行迁移,随后在导航栏中配置相应的路径引用即可
github发布项目,随后在gitee仓库中构建配置,引入项目,开启gitee pages服务
同步更新:可采用手动更新的方式,或者通过构建:
从github中导入项目至gitee仓库,选择导入GitHub仓库,授予权限,随后页面展示所有的github仓库信息,选择导入即可。
同步:导入完成之后,输入具有访问权限的账号信息,点击确认做强制同步即可
发布
github pages部署
在对应子仓库中Settings->Pages->部署docsify文档,则可通过username.github.io/repoName访问对应的内容
github.io自定义域名配置
腾讯云域名配置:构建自定义域名映射,例如blog.xxx.com
在github.io主仓库中配置Pages->CNAME配置,填充自定义域名
因此可通过blog.xxx.com/repoName访问当对应子仓库的内容