Frontmatter とは何か: Markdown のメタデータ記法

Frontmatter とは

Definition 1 Frontmatter

Frontmatter とは，Markdown ファイルの先頭に置かれるメタデータブロックのこと．
本文として描画されることを意図しないが，ページ生成時にツール側 (静的サイトジェネレータ，ブログエンジン，ドキュメントビルダー等) から参照される情報を宣言的に記述するために使われる．

代表的な用途は次のとおり:

何をキーに置くかはツール側のスキーマで決まるため，「自由に追加できる」と言ってもパーサが解釈できないキーは単に無視される点に注意．

RULE

---
title: "Frontmatter section"
---

# Markdown section

二つ目の --- 以降が通常の Markdown 本文として処理される．

Warning

ブロック内は YAML として parse される．したがってインデントは半角スペース固定でタブを混ぜない．
多くのパーサは Frontmatter ブロックがファイルの 1 行目から始まることを要求する．
- BOM や先頭の空行があると Frontmatter として認識されず，本文に --- がそのまま出力される
: を含む文字列 (例: title: foo: bar) はクォートしないと YAML 構文エラーになる．

スカラー値

---
title: 'The document title'
---

ブロックスタイルの配列

---
tags:
  - JavaScript
  - Markdown
---

フロースタイル (ブラケット記法) の配列

---
tags: ["JavaScript", "Markdown"]
---

ブロック形式とフロー形式は等価で，tags[0] == "JavaScript" となる．要素数が少なくインラインで読みやすい場合はフロー記法，要素が多い・コメントを挟みたい場合はブロック記法が向く．

オブジェクトの配列はハイフン (-) で要素を区切り，各要素配下のキーをそろえてインデントする．

---
tech:
  - role: frontend
    stack: Remix
  - role: backend
    stack: Go
---

Warning

元記事のように - frontend と書いてその下に stack: Remix を続けると YAML としては不正となる (配列要素が文字列 "frontend" で確定してしまうため，後続の stack: を子キーとして解釈できない)．
ネストしたオブジェクトを表現したいときは，ハイフンの直後に最初のキーを書く (- role: frontend) のが一般的．

YAML には複数行文字列のためのブロックスカラー記法が 2 種類ある．Frontmatter では特に description のような長文フィールドで頻出する．

Folded 記法 >: 改行をスペースに畳み込む

---
description: >
    this is a
    multiline
    string
---

このとき description の値は次の 1 行になる:

this is a multiline string

段落として 1 行に整形したい (= ソース上では折り返したいが出力では 1 行) ケースで使う．

Literal 記法 |: 改行を保持する

---
description: |
    this is a
    multiline
    string
---

このとき値は改行込みで保持される:

this is a
multiline
string

整形済みテキスト (詩，コードスニペット，事前に改行位置が決まっている文章) を埋め込みたい場合に使う．

Warning

> も | も末尾の改行の扱いがオプションで変わる: > / | (デフォルト・clip) は末尾改行を 1 つだけ残し，>- / |- (strip) は末尾改行を削除，>+ / |+ (keep) は末尾の空行を全部残す．
インデントは「ブロック開始行より深い」位置でそろえる．インデント幅を混在させると YAML パーサが文字列の途中で打ち切る．