GitHub + Travis + Mkdocs 搭建文件庫

flc1125發表於2019-08-08
Github

原文：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

相關文章