造 Quarto 報告

立並寫可重現之 Quarto 文件，以供分析報告、簡報、或網站。

適用時機

• 造可重現之分析報告
• 建含內嵌程式之簡報
• 自程式生 HTML、PDF、Word 文件
• 自 R Markdown 遷至 Quarto

輸入

• 必要：報告主題與目標讀者
• 必要：輸出格式（html、pdf、docx、revealjs）
• 選擇性：資料源與分析程式
• 選擇性：引用書目（.bib 檔）

步驟

步驟一：造 Quarto 文件

造 report.qmd：

---
title: "Analysis Report"
author: "Author Name"
date: today
format:
  html:
    toc: true
    toc-depth: 3
    code-fold: true
    theme: cosmo
    self-contained: true
execute:
  echo: true
  warning: false
  message: false
bibliography: references.bib
---

預期： 檔 report.qmd 存，含有效 YAML frontmatter，含標題、作者、日期、格式配置、執行選項。

失敗時： 驗 YAML 頭：察 --- 分隔符配對與縮排正確。確保 format: 鍵合 Quarto 支援之輸出格式（html、pdf、docx、revealjs）。

步驟二：寫含程式塊之內容

## Introduction

This report analyzes the relationship between variables X and Y.

## Data

```{r}
#| label: load-data
library(dplyr)
library(ggplot2)

data <- read.csv("data.csv")
glimpse(data)
```

## Analysis

```{r}
#| label: fig-scatter
#| fig-cap: "Scatter plot of X vs Y"
#| fig-width: 8
#| fig-height: 6

ggplot(data, aes(x = x_var, y = y_var)) +
  geom_point(alpha = 0.6) +
  geom_smooth(method = "lm") +
  theme_minimal()
```

As shown in @fig-scatter, there is a positive relationship.

## Results

```{r}
#| label: tbl-summary
#| tbl-cap: "Summary statistics"

data |>
  summarise(
    mean_x = mean(x_var),
    sd_x = sd(x_var),
    mean_y = mean(y_var),
    sd_y = sd(y_var)
  ) |>
  knitr::kable(digits = 2)
```

See @tbl-summary for descriptive statistics.

預期： 內容段含格式正確之程式塊，含 {r} 語言標識與 #| 塊選項（標籤、題注、尺寸）。

失敗時： 驗程式塊用 ```{r} 語法（非行內反引號）、#| 選項於塊內（非 YAML 頭內）、標籤前綴合交叉引用型（圖用 fig-、表用 tbl-）。

步驟三：配塊選項

常塊層選項（用 #| 語法）：

#| label: chunk-name        # Required for cross-references
#| echo: false               # Hide code
#| eval: false               # Show but don't run
#| output: false             # Run but hide output
#| fig-width: 8              # Figure dimensions
#| fig-height: 6
#| fig-cap: "Caption text"   # Enable @fig-name references
#| tbl-cap: "Caption text"   # Enable @tbl-name references
#| cache: true               # Cache expensive computations

預期： 塊選項於塊層以 #| 語法施，標籤循交叉引用所需之命名慣例。

失敗時： 確保塊選項用 #| 語法（Quarto 原生），非舊 R Markdown 之 {r, option=value} 語法。驗標籤名僅含字母數字與連字符。

步驟四：加交叉引用與引用

See @fig-scatter for the visualization and @tbl-summary for statistics.

This approach follows @smith2023 methodology.

::: {#fig-combined layout-ncol=2}
![Plot A](plot_a.png){#fig-plotA}
![Plot B](plot_b.png){#fig-plotB}

Combined figure caption
:::

預期： 交叉引用（@fig-name、@tbl-name）解至正確之圖表，引用（@key）合 .bib 檔中之項。

失敗時： 驗程式塊中引用之標籤以正確前綴（fig-、tbl-）存。引用則察 .bib 鍵完全合（區分大小寫），且 bibliography: 於 YAML 頭已設。

步驟五：渲染文件

quarto render report.qmd

# Specific format
quarto render report.qmd --to pdf
quarto render report.qmd --to docx

# Preview with live reload
quarto preview report.qmd

預期： 輸出檔以指定格式生。

失敗時：

• quarto 缺：自 https://quarto.org/docs/get-started/ 裝
• PDF 誤：以 quarto install tinytex 裝 TinyTeX
• R 套件誤：確保所有套件已裝

步驟六：多格式輸出

format:
  html:
    toc: true
    theme: cosmo
  pdf:
    documentclass: article
    geometry: margin=1in
  docx:
    reference-doc: template.docx

渲染所有格式：quarto render report.qmd

預期： 所有指定輸出格式皆成生，各含合目標格式之樣式與佈局。

失敗時： 若一格式敗而他成，察格式專屬需：PDF 需 LaTeX 引擎（以 quarto install tinytex 裝）、DOCX 需有效參考範本（若指定）、格式專屬 YAML 選項須於各格式鍵下正確巢式。

驗證

• 文件渲染無誤
• 所有程式塊執行無誤
• 交叉引用解（圖、表、引用）
• 目錄準確
• 輸出格式合讀者

常見陷阱

• 缺標籤前綴：可交叉引用之圖需標籤含 fig- 前綴，表需 tbl-
• 快取失效：上游資料改時快取之塊不重行。刪 _cache/ 以強之
• 無 LaTeX 之 PDF：裝 TinyTeX，或以 pdf-engine: weasyprint 用 CSS 基礎之 PDF
• Quarto 中之 R Markdown 語法：用 #| 塊選項代 {r, echo=FALSE} 式

相關技能

• format-apa-report - APA 格式學術報告
• build-parameterized-report - 參數化多報告生成
• generate-statistical-tables - 可出版之表
• write-vignette - R 套件中之 Quarto 小品