Markdown + Daux.io + GitHub Actions & Pages

起源於最近想要把之前隨手在 hackmd.io 打的筆記放到 GitHub 上讓朋友共編,先放個最後的成果: WildfootW / Security-Note ,當 main branch 有新的 push 時會自動生成 Daux.io 的 static html 檔,並且 push 到 gh-pages branch。

一開始是打算參考 OneJar 的文章 (免費無限建立自己的 GitBook 圖文教學 – 利用 GitHub Pages + GitHub Actions 自動發佈) 直接照做,但是有幾個問題:

  1. gitbook 已經遺棄開源社群,把原本的 gitbook 改為 legacy ,另外做了一個毫不相干的服務。
  2. OneJar 寫的 GitHub Actions 是從頭到尾只有一個步驟,用他自己寫的  Dockerfile,也就是說 push gh-pages 要用到的 token 也要 Pass 給他做的 Docker,身為一個有資安潔癖的人實在有點困擾。

於是才決定改用 Daux.io 來做,順便研究 CI。

我們最主要的結構如下:

  1. .github/workflows/documentation.yml ─ GitHub Actions 需要的檔案,檔名可自訂。
  2. docs/chapter…/articles… ─ 文章的目錄和文章本身
  3. docs/config.json ─ Daux.io 生成書的設定檔,內容相當直覺,可以去 Daux.io 的 repo 看看。

docs 裡面的東西都是 Daux.io 要用的,直接看他的文件就好。

稍微講解下我理解的 GitHub Actions 的運作(但我沒仔細看過文件,有錯請各位指教),GitHub Actions 會在他被觸發的時候有一個環境,可以是 Linux 或 Windows 都有支援,像是我的這個 repo ─ Security-Note ,runs-on 選 ubuntu,他的 $GITHUB_WORKSPACE = /home/runner/work/Security-Note/Security-Note 接下來的 jobs 都會從這邊執行。

接下來解釋下,GitHub Actions 的這個設定檔,幾乎都是從 Daux.io 那邊抄來的,但是 Daux.io 那邊是使用本身自帶的 Daux.io Binary,而我不想在每個 repo 都放一份 Daux.io ,所以那個部分改用 Docker 取代(順帶一提,GitHub Actions 的環境似乎有自帶 Docker)。

name: Documentation

on:
  push:
    branches: [ main ]

jobs:
  documentation:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with:
        persist-credentials: false
    - name: Generate documentation
      run: docker run --rm -w /build -v $GITHUB_WORKSPACE:/build daux/daux.io daux generate
    - name: Deploy 🚀
      uses: JamesIves/github-pages-deploy-action@3.7.1
      with:
        FOLDER: "static"
        BRANCH: gh-pages
        GITHUB_TOKEN: ${{ secrets.GH_PAGES_TOKEN }}

首先 on 的那個部分很直覺,就是說 push 到 main 的時候會觸發這個 Actions

jobs 裡面分成好幾個步驟:

  1. checkout@2 把 repo 的內容 clone 進 $GITHUB_WORKSPACE
  2. 用 daux/daux.io 的 Docker File 生成 HTML 的 static files
  3. 把 HTML 的 static files push 到 gh-pages branch

另外要說的部份是第三個步驟要 push 回 repo ,所以要去 Settings / Developer settings / Personal access tokens 增加一個 token 包括 public_repo, repo:status,再在 Settings / Actions secrets 增加 GH_PAGES_TOKEN (符合設定檔裡的名稱)。

基本上把這個設定檔 push 上去 repo 和設定完 Secret 就會動了,但有時候 GitHub Actions 會卡住,可以睡一覺再起來看。

Leave a Reply

Your email address will not be published. Required fields are marked *