我的 Quarto 初體驗心得。
前言
我原本在網路上查找 Sphinx（讀音近似「斯芬克斯」）的相關文件，比較跟我自己用過的一些文件編輯與出版工具比較，像是 MkDocs、Hugo。找來找去，無意間看到了 Quarto（讀音似「誇頭」），發現它似乎更符合我的需求。
從私人筆記到出版
我經常想，無論是私人筆記、部落格文章、還是寫一本書，最好能夠用同一套工具或平台，一條龍通吃。這也是為什麼以前剛開始接觸 Obsidian 時覺得很棒，但後來還是回到以 Visual Studio Code 來寫作的方式。目前的做法是，私人筆記以及要公開發布至部落格的文章，都是在 VS Code 中編寫 Markdown 文件，並利用 Hugo 搭配 Docsy 主題套件來生成靜態網站。但這樣還是缺了一塊：轉換成電子書。
Hugo 和 Docsy 有一些擴充標記語法，已經大致能滿足各種文件排版樣式的需要，語法用熟了也還挺習慣。總的來說，Hugo 和 Docsy 很好，我沒有什麼想要挑剔的。唯一的問題是，當我想要把過往這些 Markdown 文件整理成一本電子書，此時就會碰到格式轉換的問題，因為我慣用的書籍出版平台是 Leanpub，而 Leanpub 又有自己的一套 Markdown 方言。每當想到這個轉換程序就覺得累，缺乏效率。
看到 Quarto，我覺得或許找到了解決方案。
Quarto 初體驗
Quarto 跟上述工具一樣採用 Docs-as-Code 作為文件編寫與出版流程，一樣是 Markdown 標記語言（基於 R Markdown），再加上更豐富強大的擴充語法、可製作動態內容（使用 Python、R、Julia、Observable），也支援多種出版形式，包括：網站、線上書籍、PDF、ePub，甚至 MS Word 和投影片等等。它具備的功能已經超出我需要的。
接著想的是：功能這麼多，排版樣式這麼豐富，會不會很難上手、或者實際寫作時碰到一堆限制或 bugs 呢？
終歸還是得自己動手試試看才能確定。
於是，我做了第一個練習：在 GitHub 上面建立一個 repository，然後在這個 repo 中以 Quarto 的文件框架和語法來寫一本幾乎沒有內容的電子書，主要是為了測試以下需求：
- ✅ 能輸出 HTML + EPUB + PDF 三種格式。
- ✅ 生成之 PDF 可以正常顯示中文字，而不會是豆腐方塊。
- ✅ 於本機生成書檔。
- ✅ 透過 GitHub workflow 生成書檔。詳見 Quarto 筆記(2) - 自動發布至 GitHub Pages。
底下是 Quarto 生成的線上電子書網站的截圖：
生成的 PDF 檔案的截圖：
- _quarto.yml - 控制了整本書的排版相關參數，包括語系、各章的文檔名稱和順序、輸出資料夾、輸出哪些格式等等。
- index.qmd - 作為首頁的內容。注意此檔案必須存在，因為 Quarto 生成的書籍也包含 HTML 格式。See also: Quarto 文件 > Book Structure
- 01-intro.qmd - 第一章。
- 02-workflow.qmd - 第二章。
- references.qmd - 用來放參考文獻。
於本機建置
- Visual Studio Code
- Visual Studio Code extension for Quarto
- Quarto CLI
- Noto Serif 繁體中文字型
- 安裝完成 Quarto CLI 之後，須重新啟動 Visual Studio Code。
- 若沒有安裝 Noto Serif 繁體中文字型，未來生成的 PDF 檔案裡面的中文會是亂碼或豆腐（方塊字／口口口）。這個字型是在 _quarto.qmd 檔案中指定的。
Quarto vs. Settlr vs. Notion
不過，如果最重要的目標是「讓公司裡所有人，不管有沒有 IT 背景，都能立刻上手，隨手把筆記和文件丟進知識庫」，那選 Notion 這種主打 WYSIWYG 的工具就很合理了。
快速結論
- Quarto：偏向 Docs-as-Code 的專業文件/技術寫作流程，最適合用 Git + PR 做 review、差異比對與合併；團隊需要有 Git 技能。
- Zettlr： 主打桌面應用程式、偏個人/離線的寫作工具，沒有內建多人即時協作或細緻的合併機制；若要多人協作要靠外部同步或把檔案放在 Git/雲端，合併多半是「檔案層級」的流程。
- Notion： 以即時共同編輯與留言討論為強項（WYSIWYG），review 可以用「評論 / @ 指派 / 歷史版本還原」，但內建的版本差異（redline / 差異視覺化）較弱，對程式碼或純 Markdown 的精細差異比對、合併不友善。
比較表
| 比較項目 | Quarto | Zettlr | Notion |
|---|---|---|---|
| 文件類型 / 格式 | Markdown / Quarto（支援程式碼、R/Python、學術輸出）— 與 Git 相容，適合自動化 build | 本機 Markdown/文本為主（桌面 app，離線為優先） | WYSIWYG/富文本（支援 Markdown 粘貼），頁面與資料庫為核心 |
| 審查（review comments） | 靠 GitHub/GitLab PR comments、issue 討論 | 無內建多人即時評論；可借助外部工具或雲端 | 內建評論、提及、@指派、Thread，適合跨部門快速回饋 |
| 版本差異比對（diff） | 借助 Git，可逐行比對 Markdown 變更 | 無內建 diff；需搭配 Git 或外部 diff 工具 | 有版本歷史，可回溯頁面，但無逐行 redline |
| 合併（merge） | 透過 Git 分支與 PR 合併，支援衝突解決與審核流程 | 多為檔案層級；若無 Git，容易出現覆蓋衝突 | 即時編輯避免衝突，但無 Git-style 合併工具 |
| 即時協作 | 非即時（Git 為主，可搭配雲端 IDE 改善體驗） | 不支援即時，多為桌面離線 | 支援多人即時共同編輯（強項） |
| 適合團隊情境 | 技術文件、教學手冊、需 CI/CD、版本化發佈的團隊 | 個人寫作、研究筆記、注重隱私或離線的小組 | 產品/PM/設計/商務團隊，需要快速共同編輯與任務追蹤 |
沒有留言: