起源於最近想要把之前隨手在 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 會卡住，可以睡一覺再起來看。