GitHub + Travis + Mkdocs 搭建文档库

原文:https://flc.io/more/github-travis-mkdocs-d...

参考仓库:https://github.com/flc1125/docs/

1. 概述

想搭建一个免费的文档库吗?想搭建一个与原文一样的文档库吗?

路人甲:不想... 别看了,以下都是吹牛逼的... :mask: :mask:

1.1. 要求

  • 了解 Python
  • 有 Github 账号
  • 熟悉 Markdown 语法

1.2. 介绍

Github: 全球最大同性交友网站 :sweat_smile: :sweat_smile:

GitHub is a development platform inspired by the way you work. From open source to business, you can host and review code, manage projects, and build software alongside 28 million developers.

Travis: 持续集成服务(Continuous Integration,简称 CI)

Test and Deploy with Confidence
Easily sync your GitHub projects with Travis CI and you’ll be testing your code in minutes!

Mkdocs: 基于 Python 的开源文档库生成器

MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

2. Mkdocs

2.1. 安装

pip install mkdocs

mkdocs -V # 检测是否安装成功

需安装Python,支持的版本:2.7、3.4、3.5、3.6、3.7

2.2. 创建文档库

mkdocs new my-docs # mkdocs new [项目目录]

2.3. 启用内置服务

# 启用服务,http://127.0.0.1:8000
mkdocs serve

# 指定IP 端口
mkdocs serve -a 0.0.0.0:8000 # mkdocs serve -a [ip:port]

支持编辑保存,自动编译渲染

2.4. 编译构建站点

mkdocs build

2.5. Github Pages

编译并发布至 Github gh-pages 分支(前提配置使用 Github 仓库)

mkdocs gh-deploy

提交版本库(master 分支),注意忽略 site 目录。echo '/site' > .gitignore

如果只是搭建文档库,编辑后手动发布,那么你已经具备此技能了...

而下面则将开始介绍 “手动” 改为 “自动” 发布

3. Github

3.1 申请 Token

  • 访问地址:https://github.com/settings/tokens
  • 点击右侧 Generate new token 按钮
  • Token description 输入 Token 描述,随意
  • 勾选权限 Select scopes 下的 repo 下所有
  • 点击生成,将生成的 token 留好备用

操作演示

GitHub + Travis + Mkdocs 搭建文档库

4. Travis

4.1. Travis 设置

  • 进入集成服务列表: https://travis-ci.org/account/repositories

    PS: 如项目不存在,点击左侧的 Sync account 按钮。

  • 找到对应的仓库,点击右侧的开关,开启服务

  • 点击右侧 Settings 进入设置界面

  • Settings 栏位下 Environment Variables 下新增环境变量名和对应值:

    环境变量名 环境变量值
    GITHUB_TOKEN d19b9d0e7fdc5095ed1f47cb04d19b69af2dc10c

    环境变量值为上步骤生成的 Token
    注意禁用右侧的Display value in build log 选项,避免敏感信息暴露在构建日志中

操作演示

GitHub + Travis + Mkdocs 搭建文档库

4.2. 构建配置 .travis.yml

仓库根目录创建文件 .travis.yml, 内容如下:

language: python

python:
  - "3.6"

install:
  - pip install mkdocs
  - echo -e "machine github.com\n  login ${GITHUB_TOKEN}" > ~/.netrc

script:
  - mkdocs gh-deploy --force --clean

branches:
  only:
    - master

5. 附录

5.1. Github Pages 自定义域名

  • 文档根目录新增文件:CNAME,内填写对应域名即可,参考文档
  • 域名解析,通过添加 CNAME 类型,指向到 Github,参考文档

Github Pages 会自动识别 CNAME 绑定域名(还提供免费的 HTTPS 服务 :smile: :smile:)

5.2. 百度收录问题

因依靠 Github Pages 服务提供 WEB 服务。而 Github Pages 服务对百度做了屏蔽处理,以至于百度无法收录(谷歌正常)。如介意,可使用云存储或自搭服务器方式存储。

参考:

https://flc.io 使用的是 又拍云 云存储, 服务接近免费,支持 CDN,WEBP 等。还有免费的 HTTPS 证书申请。(不是广告 :joy: :joy:)
对应 构建配置参考

PS:类似这样的云存储,还有阿里云 OSS,亚马逊 S3,腾讯云 COS,七牛云等

5.3. 主题:Material

https://flc.io 使用的开源主题 Material,如何使用,请参考官网。

感受:美观、响应式、扩展丰富

6. 结语

本方案提供的是一个实现 自动化集成发布 & 免费的 WEB 服务 思路。而基于该方案,可衍生出更多的服务,如 Hexo 等第三方框架的自动化搭建,自动化测试等。

7. 参考

个人主页:http://flc.io

flc1125
讨论数量: 8
flc1125

@cnguu :expressionless: 已调整

3个月前 评论
cnguu

直接用 VuePress 吧,离线也能访问,我的站:https://gleehub.com

3个月前 评论
flc1125

@cnguu 你是来砸场子的吗 :mask:

3个月前 评论
cnguu

@flc1125 多一个分享,多一个选择

3个月前 评论
flc1125

@cnguu :+1:谢谢分享,膜拜大神!!! :cow: :beers: 牛两个啤~~

3个月前 评论

好吧,Github Pages不仅做博客,竟然还能做文档库 :joy:

2个月前 评论

问下,这个自动是什么时候触发的?不用执行mkdocs gh-deploy这个吗

2个月前 评论
flc1125

@lovecn 如果是你持续集成,一般是推送代码至远端仓库的时候,会触发。

如使用 Travis CI 可设置推送至 master 分支后进行触发。详细的可以了解下 Travis CI 的官方文档,https://docs.travis-ci.com/user/customizin...

2个月前 评论

请勿发布不友善或者负能量的内容。与人为善,比聪明更重要!