Quarto 筆記 (3) - 從 Hugo 到 Quarto 的轉換心得

這是我從 Hugo 遷移至 Quarto 的心得。

我先前曾製作過一個《Google 技術寫作課程中文版》網站，當時是以 Hugo 搭配 Docsy 建立。最近我嘗試將該文件改用 Quarto 語法重寫並生成網站，前後花了兩個晚上的時間，過程相當順利。這也再次凸顯了以 Markdown 為基礎撰寫文件的好處：靈活，並能有效避免 vendor lock-in 的問題（轉換成本還是有，但不至於高到令人卻步）。

👉 成果：用 Quarto 生成的《Google 技術寫作課程中文版》網站

截圖：

Hugo vs. Quarto

遷移過程中，我隨手記下了剛學到的 Quarto 排版語法和技巧，也根據我對 Hugo 和 Quarto 目前所知的部分整理了這兩個工具的功能差異。版本是：

• Hugo 0.126.0 + Docsy 0.12.0 （以及 HugoMods 的部分擴充元件）
• Quarto v.18.25

這裡的比較只涵蓋「生成靜態網站」的相關功能，並不包括其他功能（如 PDF 生成、可執行程式碼等等）。內容純粹依據我自身的使用經驗撰寫，沒有透過 AI 生成或增補，因此難免有所不足。

Hugo vs. Quarto

功能	Hugo	Quarto
圖片: lightbox 效果	無內建	內建，可用屬性控制。文件
表格: 控制欄寬	無，可用 <div> 解決。	內建。文件
表格: 標題	無	🏆 有，而且可以放在表格上方或下方。
網站導覽: navbar	有	有
網站導覽: sidebar	在個別文件的 front matter 中指定 weight 來控制先後順序。	🏆 勝! 可以在個別文件的 front matter 區塊中透過 order 屬性來控制，也可以在專案組態檔 _quarto.yml 中手動編排或自動剖析指定的資料夾底下的檔案。
頁面 layout 樣板系統	🏆 勝！強大且靈活的設計。See: Templates	比較簡單，主要是靠屬性設定和自訂 CSS。See: Page Layout
自動產生子頁面連結清單	有：內建簡易條列式清單。	🏆 有：內建三種樣式的連結清單，可透過屬性來控制排序和呈現方式。
交叉連結	一般	🏆 勝! 無論是 section titles 還是圖片、表格、程式碼等等，都可以設定成錨點，供其他文件加入連結。
站外連結開新分頁	自動	🏆 自動，亦可個別指定，而且能加上箭頭 icon。See: External Links
確保站內連結正確	內建 shortcode 支援。	有（註：不確定是否完整）。
Callout	🏆 勝！多達十幾種樣式，如 Tip、Question、Success 等等。	內建 5 種：note、warning、important、tip、caution。文件
Shortcode 擴充語法	有	有，而且跟 Hugo 的標記符號一樣使用 {{\< \>}}。
Themes	🏆 勝！非常多選擇。	數量較少。
搜尋	有，local search。	有，local search。
文件最近修改時間	🏆 有，而且支援 git commit 時間。	不完整，無法符合需求。（稍後說明）
Code block	一般該有的都有。	🏆 勝！除了一般功能，還有更豐富的註解標示法。
Tabs	有	有（語法更直觀）。See: Tabsets
可收合區塊	有	有
HTML	可使用基本的標籤，如 <br>、<div>。	大致相同。

底下是兩個工具的 GitHub 星星數成長趨勢圖（透過 star-history.com 生成）。從圖中可見，Quarto 是在 2020 年才開始發展，比 2013 年就問世的 Hugo 晚了大約 7 年。

Hugo 和 Quarto 怎麼選？

目前我是這麼覺得：

• 如果只需要生成靜態網站，而且想要靈活、可高度自訂的頁面樣板系統，選 Hugo，再搭配一個現成的 theme （例如 Docsy）。
• 如果需要一條龍的數位出版流程：筆記 → 生成網站 → 輸出 ePub 和 PDF 格式的電子書，選 Quarto。 

哪一個方案的學習成本比較高？這不好評斷。

印象中，我花了不少時間在摸索和熟悉 Hugo 的樣板系統。當我逐漸理解它的樣板系統是如何運作的，便開始喜歡它的設計，也能自行依各種排版需要來調整 layout。我覺得這些投資還是很值得的。另一方面，Quarto 有豐富的選項（在 _quarto.yml 中設定）和增強 Markdown 的排版語法。選擇 Quarto 意味著要學習更多擴充的 Markdown 標記和 Quarto 專屬的標記語法（Hugo 那邊則無可避免地要使用一堆 shortcodes），而在處理 PDF 的部分則還得了解 LaTeX 語法。這些學習成本，我認為也值得投資。

順便一提，Visual Studio Code 安裝了 Quarto extension 之後，編輯文件時出現的 intellisense 提示非常方便，能大幅提升寫作效率。我在編寫 Hugo 語法的 markdown 文件時，並沒有發現這麼好用的 VS Code extension。

排版功能補充

本節整理幾個「陽春」markdown 語法不支援，而我在寫作時會用到的 Quarto 排版功能。

註：陽春 markdown，或者原始 markdown，指的是沒有許多擴充語法的 vanilla markdown。

水平置中

令文字水平置中的一種方法是利用 CSS 的 text-align 屬性。

範例：

::: {style="text-align: center;"}
這會生成一段水平置中的文字
:::

如果要讓圖片水平置中，可以對個別圖片加上 fig-align  屬性：

![](images/figure-1.png){width=70% fig-align="center"}

如果要全域套用圖片水平置中，可在自訂的 CSS 檔案中加入：

/* 圖片水平置中 */
img[src$=".png"], img[src$=".jpg"] {
  display: block;
  margin: 0 auto;
  max-width: 95%;
}

See also: Other blocks、Figure Alignment

圖片使用 lightbox 效果

See: Lightbox Figures

Section 標題不要出現在 TOC

使用 .unnumbered 和 .unlisted 屬性來可以讓小節標題不加入 table of contents：

### More Options {.unnumbered .unlisted}

See: Table of Contents

表格欄寬

在 markdown 表格下方增加一個空白列，然後加入以下標記，即可控制各欄的顯示寬度比例：

: {tbl-colwidths="[20,40,40]"}

此範例表示要讓表格的三個欄位寬度分別是 20%、40%、40%。

See: Tables

每頁顯示最後更新日期

寫作當下，Quarto 還沒有完整的解方——它無法自動為每一頁顯示其最後更新日期。

詳見 GitHub issue: last-modified is not working as expected when rendering on github actions…

手動方式：在 .qmd 檔案的 metadata 區塊中指定 date-modified 屬性，例如：

date-modified: 2025-10-01

進階議題

查看 Quarto 生成 PDF 過程中產生的 LaTeX 檔案

啟用 keep-tex 屬性：

format:
  pdf:
    documentclass: report
    keep-tex: true

參見：LaTeX Output

然後，在專案目錄下執行：

quarto render --to pdf

這樣會在相同目錄下生成一個 mydoc.tex。打開這個 .tex 檔案，就能看到 Quarto（其實是 Pandoc）產生的 LaTeX 檔案內容。

當你始終無法成功改變 PDF 檔案中的某個樣式，便可以利用此方法來觀察中間過程產生的 LaTeX 是使用了哪個 environment。

以下是利用此方法所觀察到的程式碼區塊所生成的 .tex 內容：

\begin{Shaded}
\begin{Highlighting}[numbers=left,,]
\DataTypeTok{string}\NormalTok{ name }\OperatorTok{=} \StringTok{"mike"}\OperatorTok{;}
\DataTypeTok{int}\NormalTok{ age }\OperatorTok{=} \DecValTok{20}\OperatorTok{;}
\DataTypeTok{var}\NormalTok{ tuple }\OperatorTok{=} \OperatorTok{(}\NormalTok{name}\OperatorTok{,}\NormalTok{ age}\OperatorTok{);} \CommentTok{// 自動推導元素名稱}
\NormalTok{Console}\OperatorTok{.}\FunctionTok{WriteLine}\OperatorTok{(}\NormalTok{$}\StringTok{"\{tuple.name\} \{tuple.age\}"}\OperatorTok{);}
\end{Highlighting}
\end{Shaded}

可以看到這裡使用的環境是 {Shaded}。因此，如果要讓 PDF 中的程式碼區塊跟上方和下方段落文字離得稍遠一點，便可以在餵給 Quarto 的 custom.tex 檔案中加入以下標記：

\usepackage{etoolbox}
\BeforeBeginEnvironment{Shaded}{\vspace{1em}}
\AfterEndEnvironment{Shaded}{\vspace{0.4em}}

順便一提，項目符號清單是使用 {itemize} 環境：

\begin{itemize}
\tightlist
\item
  有沒有行號？
\item
  程式碼區塊的中文字能否正確顯示？
\item
  程式碼區塊的字體大小是否比正文的字體稍微小一點？
\item
  有沒有語法高量？
\end{itemize}

有哪些語法高亮樣式

有這些：arrow (預設), pygments, tango, espresso, zenburn, kate, monochrome, breezedark, haddock, atom-one, ayu, breeze, dracula, github, gruvbox, monokai, nord, oblivion, printing, radical, solarized, vim。

See: Syntax Highlighting

常用參考

• Quarto 用戶指南
• Quarto 參考手冊
• Quarto 網站原始碼（主要是看它的 _quarto.yml 如何配置，以及一些排版效果如何達成）