YAMLヘッダー

1 よく使うYAML設定

　YAMLヘッダーでは文書のタイトル、作成者、作成日のようなメタ情報に加え、出力フォーマット（HTML、PDF、Microsoft Word）、出力タイプ（文書、本、ウェブサイト、ダッシュボードなど）、チャンクオプションの指定ができる。YAMLヘッダーはYAML（YAML Ain’t Markup Language）という言語の表記法に則って書く必要がある。

　YAMLヘッダーは.qmd文書最上段の---と---間の領域内に指定するが1、順番は関係ない。 しかし、多くの場合、メタ情報、フォーマット、タイプ2、チャンクオプションの順になることが多い。ここではよく使う機能を中心にYAMLヘッダーの書き方を紹介する。

1.1 メタ情報

　まずはメタ情報について解説する。最低限のものとしてはタイトル（title）、作成者（author）、作成日（date）があるが3、なるべく多くの内容を解説したいので、適当なQuarto文書を作成し、YAMLヘッダーを以下の内容に置き換え、renderしてみよう4。

メタ情報指定の例
---
title: なぜ私がヘルムシュテット大学に...?
subtitle: 2083年では数学落ちこぼれだった私が1777年に転生して数学天才と称えられた件について
author: 
  - name: カール・フリードリヒ・ガウス
    affiliation: ヘルムシュテット大学
    email: gauss@herumushutetto-u.ac.jp
    url: https://www.gauss.com/
    attributes:
      corresponding: true
  - name: ベルンハルト・リーマン
    affiliation: ゲッティンゲン大学
    email: reimann@gettingen-u.ac.jp
    url: https://wwww.riemann.shock/
date: 1855/2/23
date-modified: today
lang: ja
abstract: |
   算数すらまともにできなかった私が1777年のドイツに生まれ変わり、
   適当なこと喋ったら、なぜかみんな私のことを天才と称え始めた。
   マジで訳わからんわ。なんか、私の名前をちなんだソフトもあるらしいね。
format: html
---

　まず、タイトルはtitle、サブタイトルはsubtitleで指定する。:の後ろには必ず半角スペースを入れること。タイトルは文字列なので"（または、'）で囲んでも良いが、YAML文法の場合、囲まなくても良い。

　作成者名は作成者が一人、かつ氏名のみ出力するだけならauthor: 作成者名だけでよい。しかし、作成者が二人以上の場合、以下のように書く必要がある（author以外の箇所は全て省略）5。

author:
  - name: 作成者1
  - name: 作成者2

　以上のようにauthor:後に改行し、2文字以上半角スペースで字下げを入れた上で、- name: 作成者名と書く。-の後ろにも半角スペースを忘れないこと。Markdownにおける箇条書き（順序なし）と同じだと考えても良いだろう。また、authorには作成者に関する様々な情報を与えることができる。たとえば、作成者の所属機関、ホームページアドレス、メールアドレス、責任著者の有無などがある。最初に見せた例は二人の所属機関（affiliation）、メールアドレス（email）、ホームページ（url）を追加し、更にガウスには責任著者（attributes > corresponding）という情報を追加した（全員の貢献度が同じである場合、attributes内にequal-contributorも指定できる。）。

　dateは文書の作成日であり、date-modifiedは文書の修正（更新）日である。"2024/06/04"のような表記法で良い。もし、render日を自動的に入れたい場合はtodayにすれば良い。これはdate-modifiedと相性が良い。

　langは文書の言語である。これによって文書が大きく変わることは内が、自動生成される内容、なとえば「References」が自動的に「参考文献」に変わったりする。デフォルトは英語（lang: en）であるが、日本語にしたい場合はlang: jaに変更しよう。

　最後にabstractは文書の概要である。ここで注目したいのはabstract:の後に内容が来るのではなく、|が入り、内容は次の行になっている点だ。YAMLの場合、値が長くなりそうだと、|の次の行に書くことが多い。この中では普通のMarkdown文法が使用可能である。たとえば、**を使った強調はむろん、二行改行を入れることで概要内の改行もできる。|でなく、>を使うケースもあるが、この場合は概要内において改行が適用されない。

1.2 フォーマット

　先ほどの「メタ情報指定の例」の最後を見るとformat: htmlと書かれた行がある。ここが出力フォーマットを指定する箇所であり、よく使われるフォーマットはHTML（format: html）とPDF（format: pdf）、そしてreveal.jsのスライド（format: revealjs）などがある。他にもあまり推奨はしないが、Microsoft Word（format: docx）もある。

　RStudioから.qmd文書を作成すると、既定値はformat: htmlになっているが、ここを適当にpdfやdocxに変えると別フォーマットとして出力されるため、非常に便利だ。もし、一つの.qmdファイルをHTMLとPDF版、両方用意する場合、その都度format:をいじるのは面倒だろう。実はこのformat:は複数のフォーマットを指定することもできる。たとえば、HTMLとPDFなら以下のように指定する。

format: 
  html: default
  pdf: default

　この状態でrenderを行うとHTML版で出力されるが、出力フォーマットを変更したい場合は、renderボタンの右にある小さい三角（▼）をクリックし、「Render PDF」を選択しよう。これ以降、ショートカットキーやrenderボタンを押すとPDFが出力される。HTMLに戻したい場合は、renderボタンの右にある小さい三角（▼）をもう一度選択してみよう。

　それでは細かい設定について紹介する。量が膨大になるため、HTMLに限定し、以下では宋がよくいじる箇所のみ紹介する。詳細はQuartoの公式ホームページを参照されたい。

フォーマット指定の例
format: 
  html:
    grid: 
      body-width: 1024px
    theme: lumen
    highlight-style: a11y
    toc: true
    toc-location: right
    toc-depth: 3
    number-sections: true
    embed-resources: false
    code-fold: false

　gridではサイドバー（sidebar-width）、本文（body-width）、右側の余白（margin-width）の幅が指定できる。それぞれ既定値は250、800、250であるが（単位はピクセル）、本文の幅が800だとやや窮屈に感じるので、1024くらいが良いかも知れない。また、サイドバーと本文、右側の余白の間の空間はガター（gutter）と呼ばれ、gutter-widthで指定できる。既定値はデフォルトのフォントサイズの1.5倍（1.5em）となっている。

　つづくthemeとhighlight-styleは文書の見た目と関係する。themeは文書全体、highlight-styleはコードのハイライトに関わる。Quartoは10種類以上のテーマとコードハイライトを提供するので、色々試しながら好みのテーマを見つけてみよう。

　つづいて、文書内目次に関連するtoc、toc-location、toc-depthについてた。tocは文書内目次の有無、toc-locationは目次の位置（既定値は右側）、toc-depthは目次の深度（既定値は3）だ。既定値のままが最もスタンダードがフォーマットとなるので、そもそもこちらは省略するケースも多い。

　他にもよく使うものとしてはnumber-sectionsがある。これは章・節の見出し（##や###など）の前に番号を付けるかを指定するものであり、既定値はfalseになっている。embed-resourcesは図、JavaScriptライブラリー、CSSなどHTMLファイル外のファイルを結果物のHTMLファイル内にすべて埋め込むものである。既定値はfalseだが、他人にHTMLファイルを共有するためにはtrueにしておくことを推奨する。しかし、様々なファイルがHTML内に埋め込まれるのでファイルのサイズが劇的に大きくなる。図表多めのHTMLファイルなら数十MBも普通にあるくらいだ。ただ、embed-resources: trueでも埋め込まれないJavaScriptライブラリーがある。数式のレンダリングを担当するMathJaxなどのライブラリーは非常に重いので、これをHTML内に埋め込みたい場合はself-contained-math: trueを別途指定する必要がある。最後にcode-foldはコードが多めであるものの、「コードよりも文章と結果がメインとなる文書、しかしコードを無くしたくはない」場合に有用なオプションだ。以下の例を見れば違いが分かるだろう。

Input：

`code-fold: false`の場合

```{r}
1 + 1
```

`code-fold: true`の場合

```{r}
#| code-fold: true
1 + 1
```

Output：

code-fold: falseの場合

1 + 1
[1] 2

code-fold: trueの場合

コード 
1 + 1
[1] 2

　YAMLヘッダー内にcode-fold: tureを指定すると、全チャンクにcode-fold: trueが適用されることになる。

1.3 チャンクオプション

　前章で説明した通り、チャンク内には#| オプション名: 値でオプションの指定ができる。もし、全て（ほとんど）のチャンクに共通するオプションがあれば、個別のチャンクに指定することは非効率的だろう。全てのチャンクに適用されるオプションknitr: > opts_chunk:で指定できる。ここではチャンクオプションであれば何でも使えると思っても良い。たとえば以下の例を見てみよう。

チャンクオプション指定の例
knitr: 
  opts_chunk: 
    dev: ragg_png
    fig-align: center
    dpi: 144
    message: false

　以上の例だと、図の文字化けを未然に防ぐために図のエンジンは{ragg}のPNG（dev: "ragg_png"）、図は中央揃え（fig-align: center）、図の解像度は144DPI（dpi: 144）、コード実行から表示されるメッセージの非表示（message: false）を指定している。他にも様々なオプションが指定できる。たとえば、エラーが生じても強制的にレンダリングを続行させるためにerror: trueを指定することもできる。

2 YAML文法

　以上の内容だけでも大体のことはできるだろう。しかし、YAMLヘッダーで指定可能な内容はこれまで紹介してきた内容の数十倍だ（もしかしたら数百倍かも知れない）。詳細はQuarto公式ホームページのReferenceを参照されたい。ただし、公式ホームページには指定可能なオプションと取りうる値、その役割について記載されているだけである。これで足りるかも知れないが、YAMLの文法が分からない人はこの場合、戸惑うかも知れないので、これから紹介するYAMLの書き方を知っておくと良い。

　YAMLの基本的な書き方はキー: 値だ。format: htmlの場合、キー（key）がformat、値（value）がhtml（または"html"）となる。YAMLの場合、値が文字列でも"が強制されない。また、階層構造を示すためには字下げを使うことも覚えておこう。決まった基準はないが、半角スペース2〜3個が無難だろう。

　一つのキーに対し、値が2つ以上の場合、[]で囲み、,で区切る。たとえば、authorの値が"Jaehyun"と"Poyon"ならauthor: ["Jaehyun", "Poyon"]となる。リストのもう一つの書き方は-である。author:の後に改行し、2〜3文字字下げをした上で各要素の前に-を付ける。つまり、以下のYAMLはauthor: ["Jaehyun", "Poyon"]と同じ内容だ。

author:
  - "Jaehyun"
  - "Poyon"

　YAMLの場合、値としてキー: 値を、つまり「キーと値のセット」を値として使うこともできる。つまり、authorの値としてname: "Jaehyun"を与えることもできる。しかしauthor: name: "Jaehyun"の書き方は通常ない。値の中にキーがあるということは、キーが複数ある時が一般的だろう。つまり、authorの値としてname: "Jaehyun"とaffiliation: "Kansai University"両方を与えることが多いだろう。このように2つ以上のプロパティ: 値をブロックとしてまとめる場合は以下のように{}を使用する。

author: {name: "Jaeyun", affiliation: "Kansai University"}

　もし、著者が二人以上であれば、これらを更に[]でまとめれば良い。

author: [{name: "Jaeyun", affiliation: "Kansai University"}, {name: "Poyon", affiliation: "Seoul National University"}]

　しかし、一行が非常に長くなるので、-で改行しても良いだろう。

author: 
  - {name: "Jaeyun", affiliation: "Kansai University"}
  - {name: "Poyon", affiliation: "Seoul National University"}

　また、{}内の要素も改行することができる。複数のキー: 値ペアをブロックとして扱う場合は、同じ階層で字下げをすれば良い。

author: 
  - name: "Jaeyun"
    affiliation: "Kansai University"
  - name: "Poyon"
    affiliation: "Seoul National University"

　この[]と{}、改行と字下げを組み合わせることで構造化されたメタ情報を記述できる。

　以上の内容だけでも、YAMLヘッダーは書けるが、いくつか便利な機能も紹介しよう。まず、値が長い時には|か>を使用する。この2つは似たような役割を果たすが、微妙に異なる。

key1: >
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Quisque dictum lorem a tempor feugiat. Cras sit amet semper mi.

    Phasellus dignissim lobortis nisl, id varius metus.
key2: |
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Quisque dictum lorem a tempor feugiat. Cras sit amet semper mi.

    Phasellus dignissim lobortis nisl, id varius metus.

　key1には>が、key2には|が使われているが、>を使用する場合、全ての改行が無視され、一行扱いとなる。一方、|を使用する場合、改行も全て認識される。

　また、YAMLの場合、#を用いたコメント機能が付いている。メタ情報記述のためにも幅広く使われてきたJSON形式の致命的なデメリットがコメント機能の不在だったが、YAMLには以下のように#で説明を付けたり、コメントアウトができる。

author: 
  # 第一著者が夜逃げしたので、著者から消す
  #- name: "Jaeyun"
  #  affiliation: "Kansai University"
  - name: "Poyon"
    affiliation: "Seoul National University" # a.k.a SNU

3 YAMLヘッダーの再利用

　Quarto文書、スライド等のメタ情報や見た目には雛形がある。たとえば、宋の場合、画像の文字化け対策として作図エンジンはAGGを使用し、画像の解像度は300DPI、位置は常に中央に揃えている。また、スライドの縦横比は4:3を使い、横1200px、縦900pxを使う。Quartoの見た目に最も大きな影響を与える要素はCSSやSCSSであるが、少なくともこれらはYAMLヘッダー内で指定するものである。

　以下は授業用スライドのソースコードの例である。

slide02.qmd
---
title: "政治学入門"
subtitle: "第2回 政治とは何か"
author: "宋財泫（関西大学）"
date: "2026/02/20"
lang: ja
format: 
  revealjs:
    footer: "政治とは何か"
    width: 1200
    height: 900
    slide-number: "c/t"
    auto-stretch: false
knitr: 
  opts_chunk: 
    dev: ragg_png
    dpi: 300
    fig.align: "center"
    echo: false
    message: false
    warning: false
    error: true
---

# 政治とは何か

## David Eastonの政治

社会に対する価値の権威的配分（Easton 1953）

> the authoritative allocation of values for the society

　大学の講義は通常、15回構成となっているため、このようなスライドを15枚作成する必要がある。たとえば、「第3回 国家とは何か」のスライドを作成するとしよう。上のスライドからsubtitle、date、foramt > recvealjs > footer、この3つだけ修正すれば良いだろう。むろん、これらのYAMLヘッダーをそのまますべてコピペして使っても良いだろう。しかし、大学の機材変更により、スライドの縦横比を4:3から16:9へ変更したい場合、15の.qmdファイルをすべて開き、widthとheightを修正する必要がある。これは面倒だし、ミスも生じやすい。subtitle、date、foramt > recvealjs > footer以外の要素をすべて別途のファイルとして格納し、そのファイルを参照すれば、ファイル一つを修正するだけで、すべてのスライドのメタ情報が修正できる。

　以下は共通のメタ情報のみを記録したslide.ymlのコードである。通常のYAMLヘッダーと同じだが、前後に---は不要だ（入れたらエラーが出る）。

slide.yml
title: "政治学入門"
author: "宋財泫（関西大学）"
lang: ja
knitr: 
  opts_chunk: 
    dev: ragg_png
    dpi: 300
    fig.align: "center"
    echo: false
    message: false
    warning: false
    error: true
format:
  revealjs:
    theme: ["default", "style/slide.scss"]
    width: 1200
    height: 900
    slide-number: "c/t"
    auto-stretch: false

　このslide.ymlをslide02.qmdで参照するためにはYAMLヘッダー内にmetadata-filesを追加し、slide.ymlファイルのパスを指定すれば良い。ここではstyleフォルダー内にslide.ymlファイルがあると仮定し、"style/slide.yml"と書いた。metadata-filesの値は必ず長さ1以上の配列である必要がある。配列は[]で表記するため、metadata-files: ["style/slide.yml"]と書く必要がある6。metadata-files: "style/slide.yml"はエラーが出るから注意だ。

slide02.qmd
---
subtitle: "第2回 政治とは何か"
date: "2026/02/20"
format: 
  revealjs:
    footer: "政治とは何か"
metadata-files: ["style/slide.yml"]
---

# 政治とは何か

## David Eastonの政治

社会に対する価値の権威的配分（Easton 1953）

> the authoritative allocation of values for the society

脚注

  1. .qmdファイルの最上段でなく、別途のファイル（たとえば、_quarto.yml）で指定する場合もある。YAMLヘッダーの内容が長かったり、複数の.qmdファイルが同じYAMLヘッダーを共有したりする場合に使う。↩︎

  2. 書籍やウェブサイトなどの特殊なタイプでないのであれば、ここは省略されるケースが多い。↩︎

  3. 実はこれらすらなくても良い。↩︎

  4. こんな感じの本を書きたいとしよう（Gemini画伯の作品）。
    ↩︎

  5. author: ["作成者1", "作成者2"]でも同じだが、作成者の氏名だけでなく連絡先や所属機関も入れたい場合は、改行して書く必要がある。↩︎

  6. 改行して- "style/slide.yml"と書いても良い。↩︎