选中内容(绿色)时除了会搜索文章名,还会搜索文章内容
点击结果中的文章名进入文章界面后可以按Ctrl+F在页面内搜索
  • 版权:CC BY-SA 4.0
  • 创建:2019-10-14
  • 更新:2020-03-17
使用 Markdown 编写文档并使用 travis 自动构建使用 gitbook 生成静态页面, 最后发布到 github pages


前言

gitbook使用markdown语法进行写作,自动生成简单漂亮的文档页面,还有海量插件可以使用,并且公开文档都免费提供服务,
使用起来很方便,有配套的软件,就算不懂代码的人用起来也非常简单。

但是有个缺点就是国内访问很慢,慢得连github的pages页面的速度都不如,而且不支持同步github组织的仓库,所以可以考虑将gitbook编译成静态页面发布到pages,
而且希望整个发布过程都是自动的,我们自己后面该文档时要做的就只是写文档(直接文本编辑器或者gitbook编辑器都行),写完后提交推送到github,后面的构建、发布全都不用我们自己操作,都自动完成,于是可以用travis,travis对github十分友好,对于公开的仓库,travis也是免费的

方法和步骤

  • 首先保证注册了github(github.com)账号、travis(travis.org)账号
  • 在github建立文档仓库
  • travis开启同步

新建travis项目

开启同步

  • 设置travis项目
    设置

设置项目变量
设置变量
这些变量的名字和功能取决于yml脚本,这里这几个变量含义如下:
GITHUB_TOKEN : github授权码,在github的Settings -> Developer settings -> Personal access tokens中可以生成一个新的 token,注意一定不能勾选Display Value in build log
GIT_NAME,GIT_EMAIL:昵称和邮箱
CUSTOM_DOMAIN:自定义域名,最后github pages中CNAME文件中的内容

  • 设置文档工程(仓库)
    github仓库新建.travis.yml文件:
  1. language: node_js
  2. node_js:
  3. - "8"
  4. # 缓存依赖
  5. cache:
  6. directories:
  7. - $HOME/.npm
  8. before_install:
  9. - export TZ='Asia/Shanghai' # 更改时区
  10. # 依赖安装
  11. install:
  12. - npm install gitbook-cli -g
  13. # 安装 gitbook 插件
  14. - gitbook install
  15. # 构建脚本
  16. script:
  17. # 自定义输出目录 gitbook build src dest
  18. - gitbook build . ./build
  19. # - gitbook build . ./build/$CUSTOM_PATH
  20. # 分支白名单
  21. branches:
  22. only:
  23. - master # 只对 master 分支进行构建
  24. # GitHub Pages 部署
  25. deploy:
  26. provider: pages
  27. skip_cleanup: true
  28. # 在项目仪表盘的 Settings -> Environment Variables 中配置
  29. github_token: $GITHUB_TOKEN
  30. # 将 build 目录下的内容推送到默认的 gh-pages 分支上,并不会连带 build 目录一起
  31. local_dir: build
  32. #fqdn: $CUSTOM_DOMAIN
  33. name: $GIT_NAME
  34. email: $GIT_EMAIL
  35. on:
  36. branch: master

这里CUSTOM_PATH被注释了,如果想域名后面还有子文件夹就这样使用,比如自定义域名gprs.neucrack.com,不使用CUSTOM_PATH,则最后的访问地址就是gprs.neucrack.com,而用了CUSTOM_PATH而且设置CUSTOM_PATH变量值为doc,则最后访问地址就是gprs.neucrack.com/doc

上面的代码自定义域名我也注释了,因为没有使用,如果使用自定义域名就取消注释

还需要注意的是,在进行部署的过程中,默认是使用 git push —force 进行推送的,也就是说你的目标分支的历史提交记录只会有最新的那一条,如果需要提交历史的话,可以添加 keep-history: true 选项。

  • 推送更新
    将新建的.travis.yml文件同步到github,会自动触发travis对项目的构建
    构建
    构建成功后便可以在自定义的域名访问了,通常地址为:用户名/组织名.github.io/项目名,如果使用了类似上面的CUSTOM_PATH的文件夹地址,则访问地址是:用户名/组织名.github.io/项目/CUSTOM_PATH

比如这里有个例子:
构建目标仓库是:https://github.com/Ai-Thinker-Open/GPRS_C_SDK_DOC
没有使用自定义域名以及文件路径,最后访问地址是:https://ai-thinker-open.github.io/GPRS_C_SDK_DOC/

为了让gitbook能同时有中文和英文,官方有做多语言:Multi-Languages,但是缺点是不能使用语言特殊的插件了.

可以在一个工程中建立两个文件夹,比如en和zh两个文件夹,然后每个文件夹内放一个gitbook工程,这样生成后就会有中英文目录了,这种方法简单方便,中英文在同一个分支进行维护.

另外一种方式,为了让两种语言为两个独立的工程(/分支),将两种语言放在两个分支上,为了将两个分支编译后合并到一个分支的两个文件夹(zh和en),需要自己写脚本,稍微复杂一点,优点是两个分支可以分开提交互不影响向,不爱折腾不建议用这种方式;可以参考:https://github.com/Ai-Thinker-Open/GPRS_C_SDK_DOC,生成的页面地址是:https://ai-thinker-open.github.io/GPRS_C_SDK_DOC/zhhttps://ai-thinker-open.github.io/GPRS_C_SDK_DOC/en.

可以参考另一个仓库:MAIXPY Doc, 这份文档系统包含了多语言和多版本支持,做得比较全面
MaixPy

也可以参考cocos creator的文档

参考文档

使用 Travis CI 自动部署 GitBook 到 GitHub Pages

文章有误?有想法想讨论?查看或者发起勘误/讨论 主题
(发起评论需要先登录 github)

/wallpaper/wallhaven-l8976q.jpg