2. Document Structure

2.1 Front matter

Write document metadata as YAML front matter at the top of a Markdown file. With multiple files, the first supplied value for each key takes precedence.

---
title: Quarterly Report
author: Taro Yamada
series: Technical Report Series
template: pfn
toc: true
cover: true
logo: assets/logo.svg
date: 2026-08-01
page_size: A4
confidential: false
lang: en
dir: ltr
---

The following nine keys are available as document metadata. The toc / cover / logo document settings and the bibliography build-input key described in Chapter 03 are also accepted. Other unknown keys produce warnings on stderr and are ignored by default. Duplicate keys, invalid YAML, and invalid types or values of known keys remain errors.

For example, you can keep tags or status intended for other tools when building a PDF. Typos such as page_szie also produce warnings, so check that the intended settings took effect. To make unknown keys errors as before, pass the CLI flag --strict-front-matter.

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

This validation policy also applies to --print-effective-config --input docs and --doctor --input docs. Since --strict-front-matter is a runtime setting, it cannot be set in front matter.

• Title precedence is --title → first front matter title in input order → first non-empty top-level H1 in input order → input name. Both # Heading and Setext H1s qualify; headings inside quotes, lists, code, raw HTML blocks, or footnote definitions do not. The body heading is retained
• Flatten H1 formatting into one line, using link text, code / math source, and image alt text. Without an H1, use the filename without .md for a single file or the directory name for directory input. If collapsing whitespace and line breaks leaves an empty input name, use document. Do not reinterpret <br> or character references in inferred values
• An explicitly empty title, invalid type, or disallowed HTML remains an input error (exit code 2). Inference and CLI overrides never hide these errors
• Front matter template must be one of academic / book / compact / default / notebook / pfn / technical. The CLI’s --template / --template-preset override front matter
• Relative logo paths are resolved from the directory containing the front matter Markdown. Front matter accepts only local files; use --logo for a Git repository source
• If series is omitted, the series display area is removed entirely. The bundled templates never fill it with a fixed publication name, document type, brand name, or boilerplate label
• To break the title across lines on the cover, use <br>, as in title: "Long Title<br>Subtitle". The only tags allowed are <br> / <br/>
• The front matter is parsed as a YAML mapping. pfpdf uses only the keys in the table above and the bibliography key described in Chapter 03; each metadata key must have the type listed in the table. You can write complex YAML values, but they are not used as metadata
• If the first line of a source file is ---, pfpdf treats it as a front matter delimiter and requires a closing --- or ... in that file. Front matter is removed from the body of every file. To place a horizontal rule at the top of a file, use ***
• The page_size keywords are A3 / A4 / A5, JIS-B4 / JIS-B5, ISO-B4 / ISO-B5, and Letter / Legal. The ambiguous B4 / B5 are not allowed. You can also specify an explicit width and height, such as 210mm 297mm
• An explicit BCP 47 language tag such as lang: en / lang: ja-JP always wins. When omitted, Japanese or English is inferred from prose across all input files without using the host locale. Count kana, Han, and Latin characters: select ja if at least two hiragana make up at least 1% of those characters, if kana is present and Japanese characters are at least as numerous as Latin characters, or if Han characters outnumber Latin characters; otherwise select en. Code, math, raw HTML blocks, and URLs are excluded; use the title if no counted prose characters remain. Specify lang for short or multilingual documents
• For right-to-left documents you can specify dir: rtl, and for left-to-right documents, dir: ltr. With auto, the browser determines the direction from the document content; it does not guess the direction from lang or the host locale alone
• If the primary language of lang is ja, the automatically generated date is rendered in Japanese style, as in 2026 年 8 月 3 日; otherwise it uses the fixed 2026-08-03 format. A date string written in the front matter is never rewritten

2.2 Combining multiple files

When the input is a directory, pfpdf combines the *.md files directly inside it in filename order.

• Every file may have front matter. Document-wide metadata and settings retain the first supplied value for each key in sort order; later files fill unset keys. A later file can supply title even if the first file has no front matter. To replace an existing value for one invocation, use its corresponding CLI option
• Search for an H1 only if no file supplies an explicit title. A later file’s explicit title overrides an earlier file’s H1. Without an H1 either, use the input directory name rather than the first filename
• false also counts as a supplied value. A bibliography list is selected as one value and is never concatenated with later files’ lists
• Invalid YAML, invalid types or values of known keys, and unknown-key warnings / --strict-front-matter apply to all files regardless of selection. Unselected logo / bibliography targets are neither checked for existence nor opened. A selected relative path is based on the parent directory of the file that first supplies that key
• Only the lowercase .md extension is accepted
• Save files as UTF-8 (a leading BOM and CRLF line endings are accepted)
• Each file is parsed as independent Markdown. Code fences, lists, raw HTML blocks, and reference link definitions cannot continue into the next file. Close any syntax that would otherwise span chapters within a single file

2.3 Links between files

Relative links to Markdown files in the same document—whether written in Markdown syntax or as raw HTML <a href> elements—become internal links to the beginning of the target file in the generated PDF. A link to a nonexistent file is an input error.

See [Chapter 03](03_gfm.md) for details.

To jump directly to a heading in another file, add a fragment. When the same heading text appears more than once, the second and later anchors get -2, -3, and so on, so specify the ID that is actually rendered.

See [the tables section](03_gfm.md#34-tables).

Links to headings within the same document also work.

See [the front matter section](#21-front-matter).

Relative links to local files other than .md, such as a spreadsheet distributed with the PDF, are rejected because they stop working when the conversion server shuts down. Use HTTP(S) URLs for portable links. Use an explicit, absolute file: URL only when the link is intentionally specific to one machine.

2.4 Table of contents and page breaks

• A table of contents is generated by default. Normally disable it with toc: false in front matter; use --toc / --no-toc for temporary overrides
• PDF bookmarks follow the same heading hierarchy as the table of contents. They remain even when toc: false omits the table of contents
• To force a page break, write ___ (three or more consecutive underscores) on a line by itself

The chapter ends here.

___

A new page starts here.

___ is a pfpdf extension. To produce a horizontal rule (thematic break), use --- or ***.

A page break starts the next block on a new page. Page breaks at the very beginning or end of the document, and consecutive ___ lines, do not create blank pages; they are merged into a single page break.

2.5 Relative paths for images and other assets

With file input, relative paths are resolved against the Markdown file’s parent directory; with directory input, against the input directory. Since all Markdown files in directory input sit directly under it, the base is the same either way.

![Architecture diagram](assets/diagram.png)

By contrast, relative paths in CLI arguments such as --input, --output, and --logo are resolved from the directory in which you run pfpdf.

Local URLs written statically in Markdown, raw HTML, and CSS are resolved through the resource graph. Local paths that a script builds from strings at runtime are not automatically exposed, so declare resources with static src / href / CSS url(), or use HTTP(S) URLs.

The URL separator inside documents is / regardless of OS. A Windows absolute path is written as file:///C:/docs/image.png, and a UNC path as a valid file://server/share/... URL. Only paths in CLI arguments may use the native path notation of the OS you are running on.