在技術寫作的世界裡，我們一直在尋找更好的方式來呈現程式碼與分析結果。從早期的 Sweave 到 R Markdown，再到 2022 年 Posit 公司推出的 Quarto，這個領域不斷進化。Quarto 可以說是 R Markdown 的下一代進化版，但它不再侷限於 R 語言，而是以「適用於所有人」為目標，支援 Python、Julia、Observable JS 等多種程式語言。
.qmd 是 Quarto 的原始檔案格式。你可以把它想像成一個「可執行的 Markdown」：在普通的文字與標記之外，你還可以嵌入程式碼，並在輸出文件（HTML、PDF、Word 等）中直接呈現程式碼、執行結果、圖表，甚至是互動式元件。它支援 Python、R、Julia、Observable JS 等多種語言，讓跨語言的分析工作變得前所未有的流暢。那麼，為什麼要從 .Rmd 轉向 .qmd？Quarto 最大的優勢在於它將過去需要透過許多套件才能實現的功能（如寫書、做簡報、建網站）整合為單一、一致的系統。它採用更清晰的語法，並提供超過 40 種輸出格式，讓技術文件創作變得更直覺、更強大。
而今天，我們就要聚焦在 .qmd 格式中最核心的功能——程式碼區塊選項，這些選項讓你精準控制程式碼與結果的呈現方式。
程式碼區塊的基本結構
在 .qmd 中，一個程式碼區塊以三個反引號加上語言標籤（如 python）開始，並以三個反引號結束。但真正讓它強大的，是區塊標頭中的選項。
以下是一個基礎的程式碼區塊結構：
```{python}
# 這裡放你的程式碼
print("Hello, Quarto!")
```
如果要加入選項，則使用 #| 開頭的註解語法，每個選項獨立成行：
```{python}
#| echo: true
#| include: true
#| eval: true
print("Hello, Quarto!")
```
這種設計比 R Markdown 將所有選項擠在一行內更清晰易讀，尤其在選項較多時特別實用。現在，我們就來逐一解析這些關鍵選項。
1. echo：控制程式碼是否顯示
echo 選項決定「程式碼本身」是否出現在最終輸出文件中。
- echo: true（預設）：顯示程式碼區塊的原始程式碼。
- echo: false：隱藏程式碼，只顯示執行結果。
應用場景： 當你希望呈現最終結果給非技術讀者，或報告中不想讓程式碼干擾閱讀流暢度時，可以將 echo 設為 false。
```{python}
#| echo: false
print("這段程式碼會被執行，但不會顯示程式碼本身")
```
2. include：完全隱藏程式碼與結果
如果 echo 是「是否顯示程式碼」，include 就是「是否在文件中包含這個區塊的任何東西」。
- include: true（預設）：正常顯示（依據
echo等設定）。 - include: false：程式碼既不顯示，也不執行（或執行但不顯示任何輸出）。
應用場景： 當你需要執行某些設定、載入套件或資料前處理，但不想讓讀者看到這些步驟時，include: false 非常實用。
```{python}
#| include: false
import pandas as pd
import numpy as np
# 這段設定程式碼完全不會出現在文件中
```
3. eval：控制是否執行程式碼
eval 決定程式碼是否被執行。
- eval: true（預設）：執行程式碼，並顯示結果。
- eval: false：不執行程式碼。如果
echo: true，仍會顯示程式碼本身。
應用場景： 當你想展示程式碼的「想法」或「結構」，但由於缺乏環境、資料，或為了節省編譯時間而不實際執行時，可以設定 eval: false。
```{python}
#| eval: false
#| echo: true
print("這段程式碼只會顯示，不會被執行")
```
4. message 與 warning：控制提示與警告訊息
在執行程式碼時，經常會產生套件載入訊息、狀態更新（message）或潛在問題提示（warning）。
- message: false：隱藏所有標準的訊息輸出（如套件載入訊息）。
- warning: false：隱藏所有的警告訊息。
應用場景： 讓最終文件保持乾淨，避免過多雜訊干擾主要內容。
```{python}
#| message: false
#| warning: false
import pandas as pd
# 載入套件時不會顯示任何提示訊息
```
5. output：控制輸出格式
output 選項決定程式碼的輸出如何被渲染。
- output: asis：將輸出視為 Markdown 語法直接渲染。這在動態產生表格或文字段落時非常強大。
- output: text：將輸出以純文字形式呈現。
6. putpaged-print：輸出PDF時自動分頁
- paged-print: true（預設）：當輸出內容較長時，在列印/匯出為 PDF 時自動分頁顯示
- paged-print: false：停用分頁輸出，所有內容連續顯示在同一頁
7. 圖形相關設定
當你的程式碼產生圖形時，可以透過以下選項控制圖片的呈現：
- fig-width 與 fig-height：設定圖形尺寸（單位：英吋）
- fig-cap：設定圖片標題
- fig-align：設定圖片對齊方式（left、center、right）
```{python}
#| fig-width: 6
#| fig-height: 4
#| fig-cap: "這是一張簡單的折線圖"
#| fig-align: center
import matplotlib.pyplot as plt
plt.plot([1, 2, 3, 4], [1, 4, 9, 16])
plt.show()
```
8. cache：啟用快取
當程式碼執行時間較長時，可以啟用快取功能。只要程式碼內容沒有變動，再次編譯時就會跳過執行，直接使用之前儲存的結果，大幅節省編譯時間。
```{python}
#| cache: true
# 這段耗時的計算只會在程式碼有變動時才重新執行
result = slow_computation()
```
9. label：為程式碼區塊命名
為區塊加上名稱，不僅方便在文中引用，也有助於除錯和組織文件。
```{python}
#| label: data-loading
#| echo: false
data = pd.read_csv("data.csv")
```
綜合應用
以下是一個結合多種選項的完整範例，展示如何在教學文章中同時呈現程式碼、隱藏載入訊息、控制圖形尺寸，並將部分設定區塊完全隱藏。
```{python}
#| label: setup
#| include: false
# 這個區塊用來載入套件，完全隱藏在最終文件中
import pandas as pd
import matplotlib.pyplot as plt
```
```{python}
#| label: data-summary
#| echo: true
#| message: false
#| fig-width: 8
#| fig-height: 5
#| fig-cap: "銷售趨勢圖"
# 讀取資料
df = pd.DataFrame({
'月份': ['1月', '2月', '3月', '4月'],
'銷售額': [120, 135, 148, 162]
})
# 繪製圖表
plt.plot(df['月份'], df['銷售額'], marker='o')
plt.title('2024年第一季銷售趨勢')
plt.ylabel('銷售額（萬元）')
plt.show()
```
結語
.qmd 格式的程式碼區塊選項，就像一個精巧的控制面板，讓你精準拿捏「什麼該呈現、什麼該隱藏、如何呈現」。透過 echo、include、eval、message、warning 以及圖形與快取等進階設定，你可以創作出既乾淨專業，又富有互動性與可重現性的技術文件。
無論你是資料科學家、技術作家，或是希望將分析流程記錄下來的專業人士，掌握這些選項都能讓你的 .qmd 作品從「可讀」進化為「優雅」。現在，就打開你的 Quarto 專案，試試看這些設定，打造屬於你的高品質技術內容吧！
