docusaurus 是facebook 开源的一款文档脚手架工具,可以快速的进行文档生成,基于markdown
同时已经内置了gh-pages 发布的命令,对于ci 工具,我们只需要简单的配置就可以了
环境准备
- 创建github空项目
很简单直接鼠标点击就可以了 - 创建docusaurus demo站点
npx docusaurus-init
- 修改名称
docusaurus 有自己的项目布局要求,修改之后的如下
- 配置修改
因为使用gh-pages 存在一个资源加载路径的问题,docusaurus 很不错已经帮助我们提供了配置了,只需要修改就可以了
如下:
./website/siteConfig.js
添加circleci 集成
- 添加ci集成
这个可以打开circleci 网站进行授权,或者通过github 市场添加 - 配置circleci 构建文件
circleci 有自己的构建路径说明mkdir .circleci
touch config.yml
内容如下:
version: 2
jobs:
build:
docker:
- image: circleci/node:8.11.4
filters: ## 分支过滤,很重要,不然gh-pages 会报错, branches:
only:
- master
steps:
- checkout
- run:
name: Deploying to GitHub Pages
command: |
git config --global user.email "1141591465@qq.com" ## git 的一些配置
git config --global user.name "rongfengliang"
echo "machine github.com login rongfengliang password $GITHUB_TOKEN" > ~/.netrc ## 基于github token 的登录
cd website && yarn install && GIT_USER=rongfengliang yarn run publish-gh-pages ## npm script 执行说明:
GIT_USER 用户比较重要,同时注意权限的设置,需要具有write 的权限,GITHUB_TOKEN 是一个环境变量,可以在circleci 构建
环境变量配置界面添加
构建&&查看效果
- 添加circleci 构建
- 构建
修改代码,提交,就会触发构建 - 效果
- 构建好的gh-pages
- 说明
如果提示gh-pages 不存在,可以手工创建,并删除代码,提交就可以了
参考资料
https://github.com/graphql-faas/continuous-api-management
https://docusaurus.io/docs/en/publishing
https://circleci.com/docs/