Github + Travis + Mkdocs 搭建文档库#

1. 概述#

想搭建一个免费的文档库吗？想搭建一个跟本站点一样的文档库吗？

路人甲：不想... 别看了，以下都是吹牛逼的...

1.1. 要求#

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

1.2. 介绍#

Github： 全球最大同性交友网站

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 留好备用

操作演示

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 选项，避免敏感信息暴露在构建日志中

操作演示

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 服务 )

5.2. 百度收录问题#

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

参考

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

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

5.3. 主题：`Material`#

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

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

6. 结语#

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

7. 参考#

Mkdocs 官网：https://www.mkdocs.org/
Material 主题：https://squidfunk.github.io/mkdocs-material/
Github： https://github.com
Travis: https://travis-ci.org
Python: https://www.python.org/
Travis git 权限问题：https://notes.iissnan.com/2016/publishing-github-pages-with-travis-ci/
Netlify WEB 项目平台（构建、部署、管理） : https://www.netlify.com/ —— Github 官方博客有推荐

最后更新: 2018年10月24日 15:14:26