Tool:Tool:AI工具

VS Code × Quarto 環境建置與使用教學

一、安裝清單

下列項目為使用 VS Code 撰寫、編譯與預覽 Quarto 專案（SIGGRAPH Asia 論文、課程講義、研究報告）所需的全部環境。

類別	名稱	功能說明	安裝方式
Quarto 主程式	Quarto CLI	Markdown → PDF / HTML / LaTeX 論文轉換核心	下載後安裝，終端機輸入 quarto check 測試
TeX 系統	macOS：MacTeX Windows：MikTeX Linux：TeX Live Full	用於輸出 PDF（含 ACM acmart 模板）	安裝後輸入 kpsewhich acmart.cls 檢查
Graphviz	Graphviz	繪製 DOT 流程圖與研究架構圖	安裝後輸入 dot -V 測試
VS Code 編輯器	Visual Studio Code	撰寫與預覽 Quarto 檔案	下載後安裝即可

二、VS Code 必裝擴充套件

於 VS Code 左側 Extensions 搜尋並安裝以下外掛：

套件名稱	功能說明
Quarto	官方外掛，提供編譯、Render、Preview 與語法高亮（必裝）
Markdown All in One	改善 Markdown 編輯體驗，自動標題、快速格式化、目錄生成功能
LaTeX Workshop	LaTeX 文件輔助、PDF 即時預覽與錯誤提示
Graphviz Preview（可選）	於 VS Code 內直接預覽 .dot 或 Quarto Graphviz 圖
Better BibTeX for Zotero（Zotero 外掛）	自動產生引用鍵與 BibTeX 檔，供 Quarto 文獻引用

三、環境測試

開啟終端機輸入：

quarto check

若顯示以下內容，代表環境安裝成功：

✓ Checking versions...
✓ Pandoc found
✓ TeX found
✓ Graphviz found

四、專案結構

建立或開啟範例專案，結構建議如下：

siggraph_quarto_template/
├─ _quarto.yml
├─ siggraph.qmd
├─ siggraph_bilingual.qmd
├─ references.bib
├─ figures/
│   └─ dot-graphs/
└─ README.md

五、基本使用步驟

1. 開啟檔案

開啟 siggraph.qmd 或 siggraph_bilingual.qmd。

2. 編輯 Markdown 內容

# Introduction
This paper explores...

## Related Work
Haraway argues that... [@Haraway2016]

3. 插入 DOT 流程圖

```{dot}
digraph Example {
  rankdir=LR;
  A[label="Concept"];
  B[label="Artifact"];
  A -> B;
}

六、在 VS Code 中編譯與預覽

• 點擊右上角「Render」按鈕（藍色 Quarto 圖示）
• 或使用快捷鍵：Ctrl + Shift + K (Windows) / Cmd + Shift + K (Mac)
• 輸出：
  • siggraph.pdf → ACM SIGGRAPH 樣式論文
  • 若設定 format: [pdf, html] → 可同時產生 HTML 預覽

七、引用與文獻管理

1. 在 Zotero 中安裝「Better BibTeX」。
2. 匯出 BibTeX 檔至專案根目錄（命名為 references.bib）。
3. 在文章中插入引用，例如：[@AuthorYear]。
4. Render 後 Quarto 會自動生成 ACM 樣式參考文獻。

八、常見問題

問題	可能原因與解決方式
產生 PDF 失敗	檢查 TeX 是否安裝完整，或查看 Log 中的 LaTeX 錯誤訊息。
中文亂碼	檢查字型設定（Font Family）是否包含支援中文的字體（如 Noto Sans TC）。
DOT 圖未顯示	確保 Graphviz 已安裝且已加入系統路徑（Path）。
引用不顯示	檢查 .bib 檔案路徑是否於 YAML Header 中正確設定。

九、進階用途

• 使用 siggraph_bilingual.qmd 製作中英雙語版（左英右中）。
• 將多份 .qmd 納入 _quarto.yml 管理，建立 18 週教學講義。
• 使用 {dot}、{python}、{r} 程式區塊自動產生圖表。
• 將計畫書（FITI / NSTC）改寫為 Quarto 專案版本。
• 以 quarto render --to html 生成互動式網站展示作品。

十、建議工作流程

1. 在 Zotero 收集文獻
2. 匯出 references.bib
3. 在 VS Code 撰寫 .qmd 檔
4. 插入 Graphviz 圖表
5. 按「Render」輸出 SIGGRAPH Asia 論文 PDF
6. 最後校對字型與排版

十一、檢查指令速查

功能	指令
測試環境	quarto check
產生 PDF	quarto render doc.qmd --to pdf
產生 HTML	quarto render doc.qmd --to html
預覽檔案	quarto preview doc.qmd

十二、延伸建議

• 以 Git 管理 Quarto 專案版本。
• 在 _quarto.yml 中定義多檔輸出（論文、講義、簡報）。
• 若需要投稿 SIGGRAPH Asia，請移除作者資訊以符合匿名審稿規範。

---

撰寫者：江振維
版本：2025-11
用途：SIGGRAPH Asia、設計研究、教學講義與學術寫作之 Quarto + VS Code 整合指南。