這篇筆記是關於我如何把 Quarto 文件發布至 GitHub Pages，以及碰到的錯誤和解決方法。
上回的 Quarto 初體驗筆記有一項尚未進行的工作：自動發布至 GitHub Pages。當時，我已經用 ChatGPT 幫我生成一個 YAML 檔案，放在 repository 的 .github/workflow 目錄下，但我並沒有進一步去除錯它，只是先放著，等有空再回來處理。
後來，在我的臉書貼文底下，我看到 鮑承佑 (老鮑伯) 大大留言提供有關 GitHub Pages 配置的線索和範例，便順藤摸瓜，把這個待辦事項給處理完了。這裡一併感謝老鮑伯的分享。
對 Quarto 有興趣的朋友，如果有報名 Hello World Dev Conference 2025，不妨去現場聆聽老鮑伯主講的議程：終究要有 Markdown 何不一開始就 Quarto？
以下重點整理我如何把 Quarto 文件發布至 GitHub Pages，以及碰到的錯誤和解決方法。
步驟
我參考的文件主要是這個：Quarto Actions: Basics 裡面的 GitHub Pages 小節。按照該小節的說明，只需兩個步驟：
步驟 1：把 GitHub Actions 工作流程加入你的 repostory
把 quarto-publish-example.yml 複製到 .github/workflows/quarto-publish.yml。然後取消兩塊註解：
- 取消註解區塊「Publish to GitHub Pages (and render)」，以便使用 GitHub Actions。
- 取消註解區塊「permissions」，這樣 GitHub Actions 才有足夠的修改權限。（詳見稍後的程式碼）
步驟 2：在本機電腦執行一次 quarto publish gh-pages
在本機電腦執行以下命令，一次即可：
quarto publish gh-pages
這可以讓 Quarto 替你的 GitHub repository 建立一個名為 gh-pages 的分支，並執行第一次的文件發布。若執行成功，便能看到發布於 GitPages 的網頁。
完成上述步驟之後，把這個工作流程檔案 (quarto-publish.yml）推送至 GitHub，以便觸發 GitHub 平台自動執行發布流程。
我的 workflow 檔案
以下是我的 GitHub workflow 檔案，修改自官方範例 quarto-publish-example.yml。稍後會說明我修改了哪些地方。
on:
push:
branches:
- main
pull_request:
name: Render and Publish
# you need these permissions to publish to GitHub pages
permissions:
contents: write
pages: write
jobs:
build-deploy:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Set up Quarto
uses: quarto-dev/quarto-actions/setup@v2
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
# To install LaTeX to build PDF book
tinytex: true
# uncomment below and fill to pin a version
# version: SPECIFIC-QUARTO-VERSION-HERE
# add software dependencies here and any libraries
# 安裝中文字體（避免 PDF 中文字變成豆腐）
- name: Install CJK fonts
run: |
sudo apt-get update
sudo apt-get install -y fonts-noto-cjk
fc-list | grep Noto
# NOTE: If Publishing to GitHub Pages,
# set the permissions correctly (see top of this yaml)
- name: Publish to GitHub Pages (and render)
uses: quarto-dev/quarto-actions/publish@v2
with:
target: gh-pages
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
要特別說明的是，我加了安裝中文字體的配置（其實不需要，因為這裡是要發布成網頁）：
# 安裝中文字體（避免 PDF 中文字變成豆腐）
- name: Install CJK fonts
run: |
sudo apt-get update
sudo apt-get install -y fonts-noto-cjk
fc-list | grep Noto其中的 fc-list 命令不是必要的，可移除。這是因為我的 GitHub worflow 曾經因為找不到指定的中文字體而執行失敗，錯誤訊息如下圖（擷取自 GitHub 網站的 log）：
從 fc-list 命令的輸出結果得知思源宋體的字體名稱是 "Noto Serif CJK TC"，然後便可在專案根目錄下的組態檔 _quarto.yml 中指定 PDF 的主要字體：
format:
html:
theme: cosmo
epub:
toc: true
pdf:
documentclass: book
papersize: a4
toc: true
toc-depth: 3
number-sections: true
fontsize: 11pt
mainfont: "Noto Serif CJK TC"成果
錯誤：HTTP 403（權限不足）
最後，記錄一個錯誤狀況：運行 GitHub workflow 失敗，錯誤訊息是 HTTP 403 權限不足。如下圖：
前面提過，workflow 檔案裡面要設定適當的寫入權限：
# you need these permissions to publish to GitHub pages
permissions:
contents: write
pages: write剛開始，我沒有注意到這個部分的設定，所以我用的是另一個方法：修改 GitHub repository 相關設定。由於我的 repository 是掛在一個 organization 底下，會直接繼承（受限於）organization 的權限設定，故實際要調整的是 GitHub repo 所屬之 organization 的權限設定。操作步驟如下：
首先，進入 Settings > Actions > General，如下圖：
在 General 設定頁面往下捲到底，修改 Workflow permissions 選項，把預設的唯讀權限改成可讀寫：
補充：GitHub Pages 與 Workflow
- 一個是 Quarto 的 workflow，負責建置網站，並將建置結果推送至 gh-pages 分支。
- 一個是 GitHub Pages 內建的 workflow，負責把 gh-pages 分支的內容發發布至 CDN（content delivery network）。
Quarto 工作流程所產生的檔案（artifacts），可以從「pages build and deployment」點進去的內容頁面找到下載連結。如果 Quarto 工作流程有一併建立 ePub 和 PDF 檔案，也會包含在下載的壓縮檔案中。
延伸閱讀
- Quarto Guide > Publishing > GitHub Pages
- Publishing a Quarto Site to GitHub Pages by Ian Taylor (2022)
沒有留言: