qmd テンプレート集 — 構造化と多形式連携

Quarto qmd ファイルの相互参照・マルチフォーマット・Div/Callouts・文献管理テンプレート集

作者

watanabe3tipapa

公開

2026年5月14日

1 qmd テンプレート集 — 構造化と多形式連携

このページでは、.qmd ファイルを 構造化 し、複数の出力形式に対応 するためのテンプレートを紹介します。

相互参照、Callouts、文献管理、Front Matter 上書きなど、実践的なパターンをまとめています。

1.1 1. 相互参照テンプレート

Quarto では図・表・数式・節に自動でIDを振り、相互参照できます。

1.1.1 テンプレート

---
title: "相互参照デモ"
format: html
number-sections: true
---

# 実験結果

@fig-plot に実験結果を示します。
平均値は @tbl-stats の通りです。

{verbatim}

::: {.cell}
::: {.cell-output-display}
![実験結果の分布](content5_files/figure-html/fig-plot-1.png){#fig-plot width=672}
:::
:::


| 統計量 | 値 |
|--------|-----|
| 平均   | -0.1047564 |
| 標準偏差 | 1.0394798 |

: 基本統計量 {#tbl-stats}

詳細は @sec-analysis で解説します。

## 分析 {#sec-analysis}

ここに分析内容を記述します。

### 実行結果

`@fig-hist` にデータの分布を示します。


::: {.cell}
::: {.cell-output-display}
![正規乱数の分布](content5_files/figure-html/fig-hist-1.png){#fig-hist width=672}
:::
:::


`@tbl-summary` から基本統計量を確認できます。

| 統計量 | 値 |
|--------|-----|
| 標本サイズ | 100 |
| 平均 | 0.083 |
| 標準偏差 | 1.03 |
| 中央値 | 0.071 |

: 基本統計量一覧 {#tbl-summary}

### 参照構文一覧

| 対象 | ラベル | 参照構文 | 表示例 |
|------|--------|----------|--------|
| 図 | `#| label: fig-xxx` | `@fig-xxx` | 図 1 |
| 表 | `{#tbl-xxx}` | `@tbl-xxx` | 表 1 |
| 節 | `{#sec-xxx}` | `@sec-xxx` | 節 2.1 |
| 数式 | `{#eq-xxx}` | `@eq-xxx` | 式 1 |
| ラインブロック | `{#lst-xxx}` | `@lst-xxx` | リスト 1 |

---

## 2. マルチフォーマット出力

1つの `.qmd` ファイルから **HTML / PDF / DOCX** を同時に出力するテンプレートです。

### テンプレート

```qmd
---
title: "マルチフォーマットレポート"
format:
  html:
    toc: true
    code-fold: true
    theme: cosmo
  pdf:
    documentclass: article
    geometry: margin=1in
    number-sections: true
  docx:
    toc: true
    highlight-style: github
execute:
  echo: true
  warning: false
---

# レポートタイトル

このファイルは HTML・PDF・DOCX の3形式で出力されます。

{verbatim}

::: {.cell}
::: {.cell-output-display}
![散布図](content5_files/figure-html/unnamed-chunk-1-1.png){width=672}
:::
:::

1.1.2 形式ごとの条件分岐

Quarto では format: キーの中で、出力先ごとにオプションを個別設定できます。

---
format:
  html:
    # HTML でのみ折りたたみ表示
    code-fold: true
  pdf:
    # PDF でのみフォント設定
    mainfont: "Noto Serif CJK JP"
---

1.2 3. Div / Callouts / Layout

Quarto 独自のブロック要素を使って、リッチなレイアウトを実現します。

1.2.1 Callouts

::: {.callout-note}
## メモ
これはノートです。
:::

::: {.callout-warning}
## 注意
これは警告です。
:::

::: {.callout-important}
## 重要
重要な内容です。
:::

::: {.callout-tip}
## ヒント
役立つ情報です。
:::

::: {.callout-caution}
## 注意喚起
注意が必要です。
:::

1.2.2 実行結果

ノートメモ

Callout は ::: で囲み、{.callout-種類} で種類を指定します。タイトルは ## タイトル で追加できます。

警告注意

コードブロック内で {verbatim} を使うと、Quarto の構文をそのまま表示できます。

重要重要

Callout は入れ子にできません。また、PDF 出力でもそのまま反映されます。

ヒントヒント

appearance: simple や collapse: true などの追加オプションも指定可能です。

1.2.3 Layout パネル

:::: {.grid}
::: {.g-col-6}
左カラムの内容
:::
::: {.g-col-6}
右カラムの内容
:::
::::

1.2.4 タブセット

::: {.panel-tabset}
## R
R のコード例

## Python
Python のコード例
:::

1.2.5 タブセット実行結果

コード 
hist(rnorm(100), col = "steelblue", main = "R: ヒストグラム")

コード 
plot(mtcars$wt, mtcars$mpg, col = "tomato", pch = 19,
     xlab = "Weight", ylab = "MPG", main = "R: 散布図")

1.3 4. 文献管理 + 引用

Quarto は BibTeX / CSL-JSON 形式の文献ファイルをサポートし、@citekey で本文中に引用を挿入できます。

1.3.1 テンプレート

---
title: "文献管理デモ"
bibliography: references.bib
citation: true
link-citations: true
format: html
---

## 導入

Quarto は @quarto2024 で紹介されているように、
再現可能なドキュメント生成が可能です。

また @wickham2019 の設計思想に基づいた
ワークフローが推奨されています。

## 参考文献

1.3.2 文献ファイルの例（references.bib）

@book{wickham2019,
  title = {R Packages},
  author = {Hadley Wickham},
  year = {2019},
  publisher = {O'Reilly Media}
}

@online{quarto2024,
  title = {Quarto Documentation},
  author = {Posit Software},
  year = {2024},
  url = {https://quarto.org/docs/}
}

1.3.3 このプロジェクトでの設定

現在の _quarto.yml には bibliography の設定はありません。必要に応じて追記します：

# _quarto.yml に追加
bibliography: references.bib
link-citations: true

1.4 5. Front Matter 上書き

.qmd ファイル単位で _quarto.yml の設定をオーバーライドするパターン集です。

1.4.1 基本ルール

ファイルの YAML front matter に記述した値は、_quarto.yml の該当値を上書きします。

1.4.2 上書きパターン一覧

目的 _quarto.yml .qmd Front Matter
テーマ変更 theme: spacelab theme: darkly
目次制御 toc: true toc: false
コード表示 code-fold: true code-fold: show（初期表示）
実行制御 echo: true echo: false / eval: false
個別CSS （なし） css: custom-styles.css
言語切替 lang: ja lang: en
PDF専用設定 documentclass: article documentclass: report

1.4.3 実例：テーマ上書き

このページ（content5）では custom-styles.css を適用しています。_quarto.yml で styles.css がデフォルト指定されていますが、front matter で上書きしています。

---
# content5.qmd の front matter
format:
  html:
    css: custom-styles.css   # styles.css を上書き
  pdf:
    documentclass: article
    papersize: a4
---

1.4.4 実例：コード実行の抑制

---
# このファイルではコードを表示するが実行しない
execute:
  echo: true
  eval: false
---

1.5 参考

  • Content3 — _quarto.yml テンプレート集
  • Content4 — コード実行・動的コンテンツのテンプレート集