「Tool:Tool:QUARTO」：修訂間差異

於 2026年2月1日 (日) 13:39 的最新修訂

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 檔案上。

點擊 VS Code 右上角的 「Preview」按鈕 (放大鏡與文件圖示)。
或使用快捷鍵：
- Windows: Ctrl + Shift + K
- macOS: Cmd + Shift + K
檢查結果：
- 右側出現 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"。

@@ 第1行： / 第1行： @@
-= VS Code × Quarto 環境建置與使用教學 =
+<div style="background-color: #2c3e50; color: white; padding: 20px; border-radius: 8px; margin-bottom: 20px; box-shadow: 0 4px 6px rgba(0,0,0,0.1);">
+<div style="font-size: 2em; font-weight: bold; border-bottom: 2px solid #ecf0f1; padding-bottom: 10px; margin-bottom: 10px;">VS Code × Quarto 環境建置與實作指南</div>
+<div style="font-size: 1.1em; opacity: 0.9;">
+🚫 <b>無須範例檔</b> | 🚀 <b>從零開始 (From Scratch)</b> | 🎓 <b>適用於論文、講義與報告</b>
+</div>
+</div>
-== 一、安裝清單 ==
+== 🛠️ 一、安裝清單 (必備環境) ==
-下列項目為使用 VS Code 撰寫、編譯與預覽 Quarto 專案（SIGGRAPH Asia 論文、課程講義、研究報告）所需的全部環境。
+<div style="background-color: #fff3cd; border-left: 6px solid #ffc107; padding: 10px; margin: 15px 0;">
+'''注意：''' 請務必依照下列順序安裝，這是運作的基礎。
+</div>
-{| class="wikitable" style="width:100%;"
+{| class="wikitable" style="width:100%; border-collapse: collapse;"
-! 類別 !! 名稱 !! 功能說明 !! 安裝方式
+|- style="background-color: #f8f9fa; text-align: left;"
+! style="padding: 10px;" | 步驟
+! style="padding: 10px;" | 軟體名稱
+! style="padding: 10px;" | 功能說明
+! style="padding: 10px;" | 安裝與檢查方式
 |-
-| Quarto 主程式 || [https://quarto.org/download Quarto CLI] || Markdown → PDF / HTML / LaTeX 論文轉換核心 || 下載後安裝，終端機輸入 <code>quarto check</code> 測試
+| align="center" | 1
+| '''[https://code.visualstudio.com/ Visual Studio Code]'''
+| 編輯器主程式
+| 下載後安裝即可。
 |-
-| TeX 系統 || macOS：MacTeX<br>Windows：MikTeX<br>Linux：TeX Live Full || 用於輸出 PDF（含 ACM acmart 模板） || 安裝後輸入 <code>kpsewhich acmart.cls</code> 檢查
+| align="center" | 2
+| '''[https://quarto.org/download Quarto CLI]'''
+| 轉換核心 (Markdown → PDF/HTML)
+| 安裝後，開啟終端機輸入 <code>quarto check</code> 測試。
 |-
-| Graphviz || [https://graphviz.org/download Graphviz] || 繪製 DOT 流程圖與研究架構圖 || 安裝後輸入 <code>dot -V</code> 測試
+| align="center" | 3
+| '''TeX 系統'''
+| PDF 輸出引擎
+|
+* '''macOS:''' 安裝 [https://www.tug.org/mactex/ MacTeX]
+* '''Windows:''' 安裝 [https://miktex.org/download MiKTeX]
 |-
-| VS Code 編輯器 || [https://code.visualstudio.com/ Visual Studio Code] || 撰寫與預覽 Quarto 檔案 || 下載後安裝即可
+| align="center" | 4
+| '''[https://graphviz.org/download Graphviz]'''
+| 流程圖繪製工具
+| 安裝後輸入 <code>dot -V</code> 測試。<br>''(Windows 安裝時請勾選 "Add to PATH")''
 |}
----
+== 🧩 二、VS Code 擴充套件設定 ==
+請開啟 VS Code 左側 '''Extensions''' (方塊圖示)，搜尋並安裝以下套件：
-== 二、VS Code 必裝擴充套件 ==
-於 VS Code 左側 Extensions 搜尋並安裝以下外掛：
 {| class="wikitable" style="width:100%;"
-! 套件名稱 !! 功能說明
+! 套件名稱 !! 重要性 !! 功能
 |-
-| '''Quarto''' || 官方外掛，提供編譯、Render、Preview 與語法高亮（必裝）
+| '''Quarto''' || style="color:red; font-weight:bold;" | ★★★ || 官方外掛，提供語法高亮、預覽與自動補全。
 |-
-| '''Markdown All in One''' || 改善 Markdown 編輯體驗，自動標題、快速格式化、目錄生成功能
+| '''Markdown All in One''' || ★★☆ || 自動編號、目錄生成、快捷鍵優化。
 |-
-| '''LaTeX Workshop''' || LaTeX 文件輔助、PDF 即時預覽與錯誤提示
+| '''Graphviz Preview''' || ★★☆ || 讓你可以直接預覽 <code>.dot</code> 流程圖檔案。
 |-
-| '''Graphviz Preview'''（可選） || 於 VS Code 內直接預覽 .dot 或 Quarto Graphviz 圖
+| '''LaTeX Workshop''' || ★☆☆ || 輔助 PDF 輸出除錯與語法檢查。
-|-
-| '''Better BibTeX for Zotero'''（Zotero 外掛） || 自動產生引用鍵與 BibTeX 檔，供 Quarto 文獻引用
 |}
----
+== 📂 三、建立第一個專案 (手把手教學) ==
+因為沒有現成檔案，請依照以下步驟建立你的工作區：
+=== 步驟 1：建立資料夾 ===
+* 在電腦中建立新資料夾，命名為 <code>My_Quarto_Paper</code>。
+* 使用 VS Code 開啟此資料夾。
+=== 步驟 2：設定檔 (_quarto.yml) ===
+在 VS Code 建立新檔案 <code>_quarto.yml</code>，並貼上以下內容：
+<pre style="background-color: #282c34; color: #abb2bf; padding: 15px; border-radius: 5px; border: 1px solid #ddd; overflow-x: auto;">
+project:
+  title: "我的學術研究專案"
+  type: website
+  output-dir: docs
-== 三、環境測試 ==
+format:
-開啟終端機輸入：
+  html:
-<pre>
+    theme: cosmo
-quarto check
+    toc: true
-</pre>
+  pdf:
-若顯示：
+    documentclass: scrartcl
-<pre>
+    number-sections: true
-✓ Checking versions...
-✓ Pandoc found
-✓ TeX found
-✓ Graphviz found
 </pre>
-代表環境安裝成功。
----
+=== 步驟 3：文獻檔 (references.bib) ===
+建立新檔案 <code>references.bib</code>，貼上測試用文獻：
-== 四、專案結構 ==
+<pre style="background-color: #282c34; color: #abb2bf; padding: 15px; border-radius: 5px; border: 1px solid #ddd; overflow-x: auto;">
-建立或開啟範例專案：
+@article{Example2025,
-<pre>
+  title={Designing with AI: A Practical Guide},
-siggraph_quarto_template/
+  author={Chiang, Chen-Wei and GPT, Chat},
-├─ _quarto.yml
+  journal={Journal of Creative Technology},
-├─ siggraph.qmd
+  year={2025},
-├─ siggraph_bilingual.qmd
+  volume={1},
-├─ references.bib
+  pages={1--10}
-├─ figures/
+}
-│   └─ dot-graphs/
-└─ README.md
 </pre>
+=== 步驟 4：主文件 (index.qmd) ===
+建立新檔案 <code>index.qmd</code>，這是撰寫論文的地方。請完整複製貼上：
+<pre style="background-color: #282c34; color: #abb2bf; padding: 15px; border-radius: 5px; border: 1px solid #ddd; overflow-x: auto;">
+---
+title: "Quarto 論文實作範例"
+author: "你的名字"
+date: last-modified
+bibliography: references.bib
+format:
+  html: default
+  pdf: default
 ---
-== 五、基本使用步驟 ==
+# 緒論 (Introduction)
+這是使用 VS Code 與 Quarto 撰寫的第一份文件。我們可以輕鬆整合文字、程式碼與圖表。
-=== 1. 開啟檔案 ===
+## 文獻回顧
-開啟 <code>siggraph.qmd</code> 或 <code>siggraph_bilingual.qmd</code>。
+根據研究指出，AI 協作能提升設計效率 [@Example2025]。
-=== 2. 編輯 Markdown 內容 ===
+# 研究方法 (Methodology)
-<pre>
+本研究採用 DOT 語言繪製研究架構圖，如下所示：
-# Introduction
-This paper explores...
-## Related Work
+```{dot}
-Haraway argues that... [@Haraway2016]
+//| label: fig-flowchart
-</pre>
+//| fig-cap: "研究流程圖"
-=== 3. 插入 DOT 流程圖 ===
+digraph G {
-<pre>
-```{dot}
-digraph Example {
    rankdir=LR;
-   A[label="Concept"];
+   fontname="Helvetica";
-   B[label="Artifact"];
+  node [shape=box, style=filled, fillcolor="#E6F3FF"];
-   A -> B;
+  Step1 [label="文獻探討"];
+   Step2 [label="建立假說"];
+   Step3 [label="實驗驗證"];
+  Step1 -> Step2 -> Step3;
 }
+結論 (Conclusion)
+Quarto 能夠將上述內容自動排版為高品質的 PDF 與 HTML。 </pre>
+== ▶️ 四、編譯與預覽 (Render) ==
+<div style="background-color: #e7f3fe; border-left: 6px solid #2196F3; padding: 10px; margin: 10px 0;">
+💡 <b>操作技巧：</b> 請確保目前編輯視窗停留在 <code>index.qmd</code> 檔案上。
+</div>
+# 點擊 VS Code 右上角的 '''「Preview」按鈕''' (放大鏡與文件圖示)。
+# 或使用快捷鍵：
+#* Windows: <code>Ctrl</code> + <code>Shift</code> + <code>K</code>
+#* macOS: <code>Cmd</code> + <code>Shift</code> + <code>K</code>
+# '''檢查結果：'''
+#* 右側出現 HTML 互動預覽。
+#* 資料夾內產生 <code>index.pdf</code> 文件。
+== 📄 五、進階：使用 ACM SIGGRAPH 模板 ==
+若需投稿學術研討會，請使用官方模板：
+開啟 VS Code 終端機 (<code>Ctrl</code> + <code>~</code>)。
+輸入指令：<code>quarto add quarto-journals/acm</code> (詢問時按 Y)。
+修改 <code>index.qmd</code> 標頭如下：
+<pre style="background-color: #f4f4f4; border: 1px solid #ccc; padding: 10px;">
+title: "My SIGGRAPH Paper" format: acm-pdf: default <-- 修改這裡 acm-html: default bibliography: references.bib
+</pre>
+== ❓ 六、常見問題排除 (Troubleshooting) ==
+{| class="wikitable" style="width:100%;"
+! width="20%" | 問題現象 !! 解決方法
+|-
+| '''PDF 無法產生'''
+|
+* 檢查 TeX 系統是否安裝完整。
+* 查看 Log，若 Quarto 詢問是否安裝缺少的套件，請選 '''Yes'''。
+|-
+| '''中文顯示亂碼'''
+|
+* 在 PDF 設定加入字型參數：<br><code>mainfont: "Microsoft JhengHei"</code> (或 Noto Sans TC)
+|-
+| '''DOT 圖表未顯示'''
+|
+* 確認已安裝 Graphviz。
+* Windows 用戶需確認安裝時勾選 '''"Add to PATH"'''。
+|}