2. 文書の構成

2.1 front matter

文書の metadata は、Markdown ファイルの先頭に YAML front matter として書きます。複数ファイルでは、キーごとに最初に書かれた値が優先されます。

---
title: 四半期報告書
author: 山田 太郎
series: 技術報告シリーズ
template: pfn
toc: true
cover: true
logo: assets/logo.svg
date: 2026-08-01
page_size: A4
confidential: false
lang: ja
dir: ltr
---

文書 metadata として使える key は次の 9 つです。さらに文書設定の toc / cover / logo と、第 3 章で説明する build input の bibliography も使用できます。それ以外の未知の key は、既定では stderr に警告を出して無視します。重複する key、不正な YAML、既知 key の型違い・不正値は引き続きエラーです。

たとえば他ツール用の tags や status を残したまま PDF 化できます。page_szie のような誤記も警告されるため、意図した設定が反映されたか確認してください。未知 key を従来どおりエラーにする場合は、CLI の --strict-front-matter を指定します。

npx @pfnet-research/pfpdf@latest --input docs --output docs.pdf --strict-front-matter

この検証方針は --print-effective-config --input docs と --doctor --input docs にも適用されます。--strict-front-matter は実行設定のため front matter では指定できません。

key	型	既定値	説明
`title`	string	H1、なければ入力名から補完	文書タイトル。明示値では `<br>` で改行できます
`author`	string	なし	著者名
`series`	string	なし	全 bundled template の主要ラベル位置に表示するシリーズ名
`template`	bundled template 名	`default`	文書に使用する bundled template
`toc`	boolean	`true`	目次を生成するかどうか
`cover`	boolean	`true`	表紙または先頭の文書 header を表示するかどうか
`logo`	path string / `false`	template 既定値	表紙ロゴ。`false` ならロゴを表示しません
`date`	string	実行日	表紙に表示する日付
`page_size`	keyword / 寸法	`A4`	ページサイズ
`confidential`	boolean	`false`	`true` のとき全 page に Confidential 表示を出します
`lang`	BCP 47 string	本文から `ja` / `en` を推定	文書の言語。HTML の `lang`、組版、フォント選択に使います
`dir`	`ltr` / `rtl` / `auto`	`auto`	文書の文字方向。HTML root の `dir` に使います

タイトルの優先順位は --title → 入力順で最初の front matter title → 入力順で最初の空でないトップレベル H1 → 入力名です。H1 は # 見出し と Setext 形式を対象とし、引用・list・code・raw HTML block・脚注定義の内側は使いません。本文の見出しは残ります
H1 の装飾は外し、link の文字列、code / 数式の source、画像の alt を使って 1 行にします。H1 がなければ、単一 file は .md を除いた file 名、directory は directory 名を使います。空白・改行を畳んでも空の入力名は document になります。補完値の   や文字参照を再解釈することはありません
明示した空の title、不正な型、許可されない HTML は従来どおり入力エラー(終了 code 2)です。補完や CLI 上書きで隠すことはできません
front matter の template には academic / book / compact / default / notebook / pfn / technical のいずれかを指定します。CLI の --template / --template-preset は front matter を上書きします
logo の相対 path は front matter を書いた Markdown の親 directory 基準です。front matter では local file だけを指定でき、Git repository source は --logo で指定します
series を省略するとシリーズ表示領域自体が削除されます。bundled template は固定の出版名、文書種別、ブランド名、定型ラベルを補いません
表紙のタイトルを改行したいときは title: "長いタイトル サブタイトル" のように   を使います。使える tag は   /   だけです
front matter は YAML mapping として読みます。pfpdf が利用するのは上表と第 3 章で説明する bibliography だけで、metadata key は表に記載した型である必要があります。複雑な YAML 値を書けても metadata としては利用されません
source file の最初の行が --- なら front matter delimiter とみなされ、同じ file 内に閉じる --- または ... が必要です。各 file の front matter は本文から除去されます。各 file の先頭で水平線を出したい場合は *** を使ってください
page_size の keyword は A3 / A4 / A5、JIS-B4 / JIS-B5、ISO-B4 / ISO-B5、Letter / Legal です。規格が曖昧な B4 / B5 は使えません。210mm 297mm のように幅と高さを指定することもできます
lang: en / lang: ja-JP のような明示した BCP 47 language tag が最優先です。省略時は全入力 file の本文から日英を推定し、host locale は使いません。かな・漢字・英字を数え、ひらがなが 2 字以上かつ対象文字の 1% 以上、かなを含み日本語文字数が英字数以上、または漢字数が英字数を超える場合は ja、それ以外は en です。code・数式・raw HTML block・URL は除外し、判定対象文字がなければ title を使います。短文や多言語文書では lang を明示してください
右から左へ書く文書は dir: rtl、左から右なら dir: ltr を指定できます。auto は文書内容から browser が判定し、lang や host locale だけから方向を推測しません
lang の primary language が ja なら自動日付は 2026 年 8 月 3 日、それ以外では 2026-08-03 の固定表記になります。front matter に書いた date の文字列自体は書き換えられません

2.2 複数ファイルの結合

ディレクトリを入力にすると、直下の *.md がファイル名順に結合されます。

各ファイルに front matter を書けます。文書全体の metadata・設定は並び順でキーごとに最初の値を採用し、後続ファイルは未設定のキーを補います。先頭ファイルに front matter がなくても、後続ファイルで title を指定できます。既存の値を一時的に置き換えたい場合は、対応する CLI option を使って上書きします
全ファイルに明示 title がないときだけ H1 を探します。後続ファイルの明示 title は、先行ファイルの H1 より優先します。H1 もなければ先頭ファイル名ではなく入力 directory 名を使います
false も指定済みの値として扱います。bibliography のリストは一つの値として選び、後続ファイルのリストを連結しません
不正 YAML、既知 key の型・値の誤り、未知 key の warning / --strict-front-matter は採否にかかわらず全ファイルで検査します。選ばれない logo / bibliography は参照先の存在確認や読込をしません。選択された相対 path は、そのキーを最初に指定したファイルの親 directory 基準です
拡張子は小文字の .md だけが対象です
ファイルは UTF-8 で保存してください(先頭の BOM と CRLF 改行は受け付けます)
各ファイルは独立した Markdown として解釈されます。code fence、list、raw HTML block、reference link definition を次のファイルへ続けることはできません。章をまたぐ構文は 1 ファイル内で閉じてください

2.3 ファイル間のリンク

同じ文書に結合される Markdown ファイルへの相対リンクは、Markdown 記法でも raw HTML の <a href> でも、生成される PDF 内の対象ファイル先頭へのリンクに書き換えられます。存在しないファイルを指すリンクは入力エラーになります。

詳細は [03 章](03_gfm.md) を参照してください。

別ファイル内の見出しへ直接移動するには fragment を付けます。同じ見出しが複数ある場合、2 個目以降の anchor には -2、-3 が付くため、表示された実際の ID を指定します。

[表の節](03_gfm.md#34-表)を参照してください。

見出しへの文書内リンクも使えます。

[front matter の節](#21-front-matter) を参照してください。

PDF と一緒に配布する spreadsheet など、.md 以外の相対 local file への link は、変換後に配信 server が終了すると壊れるため受け付けません。portable な link には HTTP(S) URL を使ってください。特定 machine の file を開く意図がある場合だけ absolute file: URL を明示できます。

2.4 目次と改ページ

目次は既定で生成されます。通常は front matter の toc: false で無効化し、一時的な上書きには --toc / --no-toc を使います
PDF の栞は、目次と同じ見出しの階層で生成されます。toc: false で目次を省いても、栞は残ります
改ページしたい位置には、単独の行に ___(underscore 3 個以上の連続)を書きます

ここで章が終わります。

___

ここから新しいページが始まります。

___ は pfpdf の拡張です。水平線(thematic break)を出したいときは --- または *** を使ってください。

改ページは次の block を新しい page から始めます。文書先頭 / 末尾や連続した ___ は空白 page を作らず、1 回の改ページへまとめられます。

2.5 画像などの相対パス

file input では Markdown ファイルの親ディレクトリ、directory input では入力ディレクトリが相対パスの基準です。directory input の Markdown はすべて直下にあるため、同じ基準になります。

![構成図](assets/diagram.png)

一方、CLI 引数(--input、--output、--logo など)の相対パスは、pfpdf を実行したカレントディレクトリが基準です。

Markdown、raw HTML、CSS に静的に書いた local URL は resource graph を通じて解決されます。script が実行時に文字列から作る local path は自動公開されないため、resource は静的な src / href / CSS url() として宣言するか、HTTP(S) URL を使ってください。

文書内の URL separator は OS にかかわらず / です。Windows の absolute path は file:///C:/docs/image.png、UNC path は妥当な file://server/share/... URL で書きます。CLI 引数の path だけは実行 OS の通常の path 表記を使えます。