Create Quarto Report

---
name: create-quarto-report
locale: wenyan-lite
source_locale: en
source_commit: 82c77053
fence_basis_commit: 82c77053
translator: "Julius Brussee homage — caveman"
translation_date: "2026-04-19"
description: >
  Create a Quarto document for reproducible reports, presentations, or
  websites. Covers YAML configuration, code chunk options, output
  formats, cross-references, and rendering. Use when creating a
  reproducible analysis report, building a presentation with embedded
  code, generating HTML, PDF, or Word documents from code, or migrating
  an existing R Markdown document to Quarto.
license: MIT
allowed-tools: Read Write Edit Bash Grep Glob
metadata:
  author: Philipp Thoss
  version: "1.0"
  domain: reporting
  complexity: basic
  language: R
  tags: quarto, report, reproducible, rmarkdown, publishing
---

# 造 Quarto 報告

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

## 適用時機

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

## 輸入

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

## 步驟

### 步驟一：造 Quarto 文件

造 `report.qmd`：

```yaml
---
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`）。

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

````markdown
## 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-`）。

### 步驟三：配塊選項

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

```text
#| 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}` 語法。驗標籤名僅含字母數字與連字符。

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

```markdown
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 頭已設。

### 步驟五：渲染文件

```bash
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 套件誤：確保所有套件已裝

### 步驟六：多格式輸出

```yaml
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 小品