Appendix A — Quarto (応用編)

A.1 スライド

Quartoでスライドを作る場合, PowerPoint, Beamer, Reveal.js などの形式を選ぶことができます. Quartoを使う人は Reveal.js 形式を選ぶことが多いですが, HTMLベースであるため扱いに癖があります. ここでは, Typst 形式でスライドを作る方法を紹介します. その他の方法はQuartoのドキュメントを参照してください. 基本的に文法は変わらず, YAMLフロントマターの format で revealjs などを選ぶことでスライド形式で出力されるようになります.

quarto-clean-typst

quarto-clean-typst は, 私 (柳本和春) が作ったQuartoでTypst形式のスライドを作るためのテンプレートです. ここでは最小限の機能を紹介しますが, 詳細は Zennの記事 を参照してください.

インストールはプロジェクトを開いた状態で, ターミナルから

quarto install extension kazuyanagimoto/quarto-clean-typst

として Y を入力するだけです. プロジェクトディレクトリに _extensions/kazuyanagimoto/clean/ というディレクトリができていれば成功です.

スライドの作成

YAMLフロントマターに format: clean-typst と書くと, Typst形式のスライドが出力されるようになります. そのほかは通常のQuartoと同じような内容を設定できます.

基本的には, Quartoのスライド記法 (特にReveal.jsの) を使います. h2レベルのヘッダーがスライドの区切りかつスライドタイトルであり, h1がセクションタイトル, h3がスライドのサブタイトルとなります.

slides.qmd
# Section Slide as Header Level 1

## Slide Title as Header Level 2

### Subtitle as Header Level 3

You can put any content here, including text, images, tables, code blocks, etc.

- first unorder list item
    - A sub item

1. first ordered list item
    1. A sub item

Next, we'll brief review some theme-specific components.

- Note that _all_ of the standard Quarto + Typst
[features](https://quarto.org/docs/output-formats/typst.html) 
can be used with this theme
- Also, all the [Touying](https://touying-typ.github.io) features can be used by **Typst native code**.

局所的なカスタマイズ

スライドを作成する際, 一部のスライドだけスタイルを変更したり, 行間を調整したいことがよくあります. QuartoのTypst CSSを用いたり, 独自機能の {{< v 1em >}} を使うことで局所的なカスタマイズが可能です.

slides.qmd
## Ad-hoc Styling

### Typst CSS

- Quarto supports [Typst CSS](https://quarto.org/docs/advanced/typst/typst-css.html) for simple styling
- You can change [colors]{style="color: #009F8C"}, [backgrounds]{style="background-color: #F0F0F0"}, and [opacity]{style="opacity: 0.5"} for `span` elements

::: {style="font-size: 30pt; font-family: 'Times New Roman'"}

You can also change the font size and family for `div` elements.

:::

{{< v 1em >}}

### Vertical Spacing

- A helper shortcode `{{< v DIST >}}` is provided to add vertical spacing
- This is converted to a Typst code `#v(DIST)` internally.

{{< v 2em >}}

This is a `2em` vertical spaced from above.

演習

Tip演習: Quartoでスライドを作る
  1. 適当な場所に演習用のフォルダを作ってください (例: 11-exercise).
  2. 11-1-exercise.qmd をダウンロードして, そのフォルダに入れてください.
  3. Quartoのextension quarto install extension kazuyanagimoto/quarto-clean-typst によって quarto-clean-typst をインストールしてください.
  4. 11-1-exercise.qmd をコンパイルしてみてください. うまくいけば, 11-1-exercise.pdf というファイルが生成されるはずです.
  5. 11-1-exercise.qmd を開いて, 中に書かれている指示に従ってスライドを作成してください.

A.2 相互参照

相互参照 (cross-reference) は, 図・表・節などに自動で番号を振り, 本文から「@fig-... を参照」のように引用する仕組みです. 番号は出現順に自動で振られ, 並び替えても自動で更新されるため, 手で「図1」「図2」と書く必要がありません.

Quartoでは, 要素に ラベル を付け, 本文から @ラベル名 で参照します. ラベルの 接頭辞 が要素の種類を決め, 番号の付け方 (「図」か「表」か) もこれで決まります.

  • fig-: 図 (figure)
  • tbl-: 表 (table)
  • ほかに sec- (節, この節も {#sec-crossref} で参照可能), eq- (数式) など

画像ファイルの相互参照

Markdownの画像記法で, [] の中にキャプションを書き, 末尾に {#fig-ラベル} を付けます.

![スライドの例](/static/img/11-quarto/slides_example.png){#fig-slides-img}
Figure A.1: スライドの例

本文で @fig-slides-img と書くと, Figure A.1 のように「図 番号」へ展開されます.

Markdown テーブルの相互参照

テーブルの直後に空行を挟んで, : キャプション {#tbl-ラベル} を書きます.

| 種類   | 主な生息地             |
|--------|------------------------|
| Adelie | 南極半島周辺           |
| Gentoo | フォークランド諸島など |

: ペンギンの種類 {#tbl-penguins-md}
Table A.1: ペンギンの種類
種類 主な生息地
Adelie 南極半島周辺
Gentoo フォークランド諸島など

本文で @tbl-penguins-md と書くと Table A.1 のように展開されます.

ggplot2 による図の相互参照

コードで生成する図には, チャンクオプションの #| label: を fig- で始め, #| fig-cap: でキャプションを付けます. 図そのものに {#...} を付ける必要はありません.

```{r}
#| label: fig-penguins-plot
#| fig-cap: "くちばしの長さとひれの長さの関係"
penguins |>
  ggplot(aes(x = flipper_len, y = bill_len, color = species)) +
  geom_point() +
  labs(
    x = "Flipper length (mm)",
    y = "Bill length (mm)",
    color = "Species"
  )
```
Figure A.2: くちばしの長さとひれの長さの関係

本文で @fig-penguins-plot と書くと Figure A.2 のように参照できます.

tinytable による表の相互参照

表も同様に, チャンクラベルを tbl- で始め, #| tbl-cap: でキャプションを付けます. tinytable では tt(caption = ...) よりも, このチャンクオプションを使う方が相互参照が確実に効きます.

```{r}
#| label: tbl-penguins-tt
#| tbl-cap: "ペンギンの種類ごとの平均値"
penguins |>
  summarize(
    bill_len = mean(bill_len, na.rm = TRUE),
    flipper_len = mean(flipper_len, na.rm = TRUE),
    .by = species
  ) |>
  tt()
```
Table A.2: ペンギンの種類ごとの平均値
species bill_len flipper_len
Adelie 38.79139 189.9536
Gentoo 47.50488 217.1870
Chinstrap 48.83382 195.8235

本文で @tbl-penguins-tt と書くと Table A.2 のように参照できます.

ラベルのカスタマイズ

デフォルトでは, キャプションも本文中の参照も英語の “Figure” / “Table” になります. これを「図」「表」に変えるには, YAMLフロントマター (または _quarto.yml) の crossref で設定します.

  • fig-title / tbl-title: キャプション側 の接頭辞. 「Figure 1: …」の “Figure” の部分.
  • fig-prefix / tbl-prefix: 本文の参照側 の接頭辞. @fig-... が展開されたときの “Figure 1” の “Figure” の部分.
  • title-delim: 接頭辞・番号とキャプション本文の間の区切り文字 (デフォルトは :).
_quarto.yml
crossref:
  fig-title: 図
  tbl-title: 表
  fig-prefix: 図
  tbl-prefix: 表
  title-delim: "　"

こう設定すると, キャプションは「図 1　…」, 本文の参照は「図 1」のように表示されます.

なお, ドキュメント全体を日本語にする場合は, lang: ja を指定するだけでこれらの既定値がまとめて日本語になるため, 個別の指定は不要なことが多いです.

_quarto.yml
lang: ja