QUARTO

VS Code × Quarto 環境建置與實作指南

🚫 無須範例檔 | 🚀 從零開始 (From Scratch) | 🎓 適用於論文、講義與報告

🛠️ 一、安裝清單 (必備環境)

注意： 請務必依照下列順序安裝，這是運作的基礎。

步驟	軟體名稱	功能說明	安裝與檢查方式
1	Visual Studio Code	編輯器主程式	下載後安裝即可。
2	Quarto CLI	轉換核心 (Markdown → PDF/HTML)	安裝後，開啟終端機輸入 quarto check 測試。
3	TeX 系統	PDF 輸出引擎	macOS: 安裝 MacTeX Windows: 安裝 MiKTeX
4	Graphviz	流程圖繪製工具	安裝後輸入 dot -V 測試。 (Windows 安裝時請勾選 "Add to PATH")

🧩 二、VS Code 擴充套件設定

請開啟 VS Code 左側 Extensions (方塊圖示)，搜尋並安裝以下套件：

套件名稱	重要性	功能
Quarto	★★★	官方外掛，提供語法高亮、預覽與自動補全。
Markdown All in One	★★☆	自動編號、目錄生成、快捷鍵優化。
Graphviz Preview	★★☆	讓你可以直接預覽 .dot 流程圖檔案。
LaTeX Workshop	★☆☆	輔助 PDF 輸出除錯與語法檢查。

📂 三、建立第一個專案 (手把手教學)

因為沒有現成檔案，請依照以下步驟建立你的工作區：

步驟 1：建立資料夾

• 在電腦中建立新資料夾，命名為 My_Quarto_Paper。
• 使用 VS Code 開啟此資料夾。

步驟 2：設定檔 (_quarto.yml)

在 VS Code 建立新檔案 _quarto.yml，並貼上以下內容：

project:
  title: "我的學術研究專案"
  type: website
  output-dir: docs

format:
  html:
    theme: cosmo
    toc: true
  pdf:
    documentclass: scrartcl
    number-sections: true

步驟 3：文獻檔 (references.bib)

建立新檔案 references.bib，貼上測試用文獻：

@article{Example2025,
  title={Designing with AI: A Practical Guide},
  author={Chiang, Chen-Wei and GPT, Chat},
  journal={Journal of Creative Technology},
  year={2025},
  volume={1},
  pages={1--10}
}

步驟 4：主文件 (index.qmd)

建立新檔案 index.qmd，這是撰寫論文的地方。請完整複製貼上：

---
title: "Quarto 論文實作範例"
author: "你的名字"
date: last-modified
bibliography: references.bib
format:
  html: default
  pdf: default
---

# 緒論 (Introduction)
這是使用 VS Code 與 Quarto 撰寫的第一份文件。我們可以輕鬆整合文字、程式碼與圖表。

## 文獻回顧
根據研究指出，AI 協作能提升設計效率 [@Example2025]。

# 研究方法 (Methodology)
本研究採用 DOT 語言繪製研究架構圖，如下所示：

```{dot}
//| label: fig-flowchart
//| fig-cap: "研究流程圖"

digraph G {
  rankdir=LR;
  fontname="Helvetica";
  node [shape=box, style=filled, fillcolor="#E6F3FF"];
  
  Step1 [label="文獻探討"];
  Step2 [label="建立假說"];
  Step3 [label="實驗驗證"];
  
  Step1 -> Step2 -> Step3;
}
結論 (Conclusion)
Quarto 能夠將上述內容自動排版為高品質的 PDF 與 HTML。 

▶️ 四、編譯與預覽 (Render)

💡 操作技巧： 請確保目前編輯視窗停留在 index.qmd 檔案上。

1. 點擊 VS Code 右上角的 「Preview」按鈕 (放大鏡與文件圖示)。
2. 或使用快捷鍵：
   • Windows: Ctrl + Shift + K
   • macOS: Cmd + Shift + K
3. 檢查結果：
   • 右側出現 HTML 互動預覽。
   • 資料夾內產生 index.pdf 文件。

📄 五、進階：使用 ACM SIGGRAPH 模板

若需投稿學術研討會，請使用官方模板：

開啟 VS Code 終端機 (Ctrl + ~)。 輸入指令：quarto add quarto-journals/acm (詢問時按 Y)。 修改 index.qmd 標頭如下：

title: "My SIGGRAPH Paper" format: acm-pdf: default <-- 修改這裡 acm-html: default bibliography: references.bib

❓ 六、常見問題排除 (Troubleshooting)

問題現象	解決方法
PDF 無法產生	檢查 TeX 系統是否安裝完整。 查看 Log，若 Quarto 詢問是否安裝缺少的套件，請選 Yes。
中文顯示亂碼	在 PDF 設定加入字型參數： mainfont: "Microsoft JhengHei" (或 Noto Sans TC)
DOT 圖表未顯示	確認已安裝 Graphviz。 Windows 用戶需確認安裝時勾選 "Add to PATH"。