3. Writing GFM

pfpdf uses GitHub Flavored Markdown (GFM). Standard GFM syntax works as written, and every construct in this chapter is rendered directly in this PDF.

3.1 Headings and paragraphs

Markdown headings from # to ###### are supported. Each heading gets an anchor that is unique in source order, and all six levels appear in the table of contents. Headings with the same text get -2, -3 suffixes. h1 through h6 elements written directly in raw HTML are not included in the automatic table of contents; give them an explicit id if you want to use them as link targets.

For Japanese document language (lang: ja, or Japanese inferred when omitted), source wrapping between Han/kana/Japanese punctuation does not add a visible space inside a paragraph, including across emphasis and links. Blank-line paragraph boundaries, English word boundaries, explicit spaces, and Markdown hard breaks are preserved. Code, math and their boundaries, and paragraphs containing raw HTML are unchanged.

3.2 Emphasis

Emphasis, strong emphasis, strikethrough, and valid nesting (strong + emphasis) are all supported.

Japanese emphasis

You can use ** directly in Japanese prose. It converts correctly even when adjacent to full-width punctuation or brackets.

• これは重要です。
• これは**「強調表示」**の例です。
• これは**重要な点。**続きのテキストも書けます。
• ここは**（重要事項）**です。

You rarely need to write <strong> tags; use ** whenever GFM can express the emphasis you need.

Japanese/Latin spacing

Japanese documents automatically add visual CSS spacing between Japanese text and Latin letters/digits. Authored spaces and punctuation are preserved; code and math are excluded. No whitespace is inserted into URLs or copied DOM text. PDF text extractors may reconstruct visual gaps as whitespace. This default does not apply to non-Japanese languages such as lang: en. Override it with text-autospace: no-autospace in custom CSS; unsupported browsers display the text without added spacing.

3.3 Lists

Nested lists, numbered lists, and task lists are all supported.

• Fruits

  • Apples
  • Mandarins
    1. Satsuma mandarin
    2. Ponkan

• Vegetables

• A completed task

• An incomplete task

3.4 Tables

For tables, prefer GFM table syntax over raw HTML. Column alignment can also be specified.

3.5 Links and images

• Inline links: Vivliostyle
• Autolinks: a bare URL such as https://commonmark.org/ becomes a link
• Images: use a relative path, as in ![Alt text](assets/example.svg)

Long URLs and identifiers

pfpdf automatically adds display-only line-break opportunities to URLs, email addresses, paths, and snake_case, kebab-case, or camelCase identifiers that contain at least 16 graphemes. It prefers breaks at / and ? in URLs, . in hostnames, and separators in identifiers. It does not add whitespace or zero-width characters to link targets or copied text.

https://example.invalid/reports/2026/very-long-document-name?format=print&language=en

Inline code, code blocks, math, and the contents of kbd and samp are excluded, since exact preservation takes priority there. Long lines of code are displayed using the template’s existing wrapping rules.

3.6 Quotes and code

This is a blockquote. It can span multiple lines.

Wrap inline code in `backticks`. See Chapter 05 for code blocks.

3.7 Horizontal rules

--- or *** produces a horizontal rule (thematic break).

An unindented, standalone line of three or more consecutive underscores (___, ____, etc.) is reserved for page breaks in pfpdf (see Chapter 02), so it cannot be used as a horizontal rule. It is not treated as page-break syntax when it appears inside a blockquote or list, when it has surrounding or intervening whitespace.

3.8 GitHub features not part of GFM

Some features rendered by GitHub.com belong to the GitHub service rather than the GFM specification. pfpdf does not convert the following:

• @user mentions and #123 issue / pull request references
• emoji shortcodes such as :smile:
• alerts such as > [!NOTE]

Mermaid is supported as a dedicated pfpdf extension; see the mermaid fenced code block in Chapter 05. For anything else, express it with raw HTML (Chapter 04) or images.

3.9 BibTeX bibliographies

Specify .bib files with bibliography in Markdown front matter. Relative paths are resolved against the parent directory of the Markdown file that first supplies that key. Multiple .bib files can be given as a list, and that whole list is selected as one value.

---
title: Survey Report
bibliography:
  - bibliography/references.bib
---

In the body, cite BibTeX keys with the same \cite command as in TeX. Separate multiple keys with commas.

See the prior work\cite{smith2024} and the comparative studies\cite{smith2024,tanaka2025}.

Citations appear as numbers such as [1] and link to the corresponding bibliography entries in the PDF. To choose where the bibliography appears, place \printbibliography on a top-level line by itself. Add an ordinary Markdown heading immediately before it to include the bibliography in the table of contents.

# References

\printbibliography

If \printbibliography is omitted, the list is appended at the end of the document. A \cite inside inline code, code blocks, raw HTML, or math is not interpreted as a citation, so literal usage examples can be written in inline code like `\cite{key}`. To escape a \cite with a backslash instead, write \\cite{key}.

The initial version supports BibTeX / BibLaTeX .bib files with a numeric style. Nonexistent keys, duplicate keys, invalid BibTeX, and unreadable files cause a failure with exit code 2, without generating a partial PDF. TeX’s \ref is not a bibliography citation; it is reserved for future figure / table / equation / section references.

3.10 Footnotes

Write each reference and its definition in the same source file.

Body text[^memo]. The same note can be referenced again[^memo].

[^memo]: Additional information.

Each note appears at the bottom of its first-reference page. No additional configuration is required.

Page footnotes are numbered in first-reference order across the document. The same definition identifier may be reused in another file, where it denotes a separate note. Repeating a reference on a later page links to the note’s first appearance without printing another copy. Long footnotes continue onto following pages; multiple paragraphs, code, and links are supported. Japanese documents also receive Japanese accessible reference and back-link labels.