Option 1: The Docker Hub image

A prebuilt image is published at book4matter/book4matter. This is the fastest way to start: there is nothing to compile and no repository to clone — the tool and its templates are baked into the image, and only your book’s files are read from disk.

Pull it once:

docker pull book4matter/book4matter

Then run the tool with docker directly. Mount the directory that holds your book at /work; the image does the rest:

docker run --rm -v "$PWD":/work book4matter/book4matter print my-book/

The image’s entry point is bf, so everything after the image name is an ordinary bf command. The other forms work the same way:

docker run --rm -v "$PWD":/work book4matter/book4matter pdf  my-book/
docker run --rm -v "$PWD":/work book4matter/book4matter epub my-book/
docker run --rm -v "$PWD":/work book4matter/book4matter html my-book/
docker run --rm -v "$PWD":/work book4matter/book4matter all  my-book/

Output lands in my-book/out/. If typing the full line each time gets tedious, wrap it in a shell alias or a short script of your own.

Option 2: Install directly, without Docker

If you would rather not run Docker at all, install the tools on your machine. Book4matter needs:

• Pandoc 3.9 — the document converter.
• Typst 0.14 — the PDF typesetter. It bundles the Libertinus Serif body font, so there is nothing extra to install for that.
• Python 3 with PyYAML — the bf command.
• The Liberation fonts — Liberation Sans is used for headings.

Two more are optional: a Java runtime and EPUBCheck if you want the EPUB validated (otherwise build EPUBs with --no-check), and Python’s pypdf if you want the impose command.

Pandoc and Typst both ship self-contained binaries on their release pages, so the surest way to get the tested versions — on any operating system, without a package manager — is to download them directly:

• Pandoc 3.9: https://github.com/jgm/pandoc/releases
• Typst 0.14: https://github.com/typst/typst/releases

PyYAML comes from pip (pip install pyyaml), and the Liberation fonts from your operating system’s font package or the project page.

Then clone this repository — it holds the bf command and the templates — point bf at the templates, and run it as a Python module from the repository root:

export BF_TEMPLATES="$PWD/templates"
python3 -m bf print my-book/

Newer versions of Pandoc and Typst usually work, but 3.9 and 0.14 are the versions the project builds and tests against. The project’s own GitHub Actions workflow, .github/workflows/deploy-web.yml, downloads exactly these binaries and builds every sample book on each commit, so it is a working, always-current reference for this option.

Option 3: Build the image yourself

You can also build the Docker image from the Dockerfile in this repository rather than pulling the prebuilt one from Docker Hub. It is more work, but the image is assembled entirely from sources you can read — worth doing if you would rather not run a prebuilt binary you didn’t build.

Clone the repository. The bundled run.sh builds the image the first time you use it, then runs the tool with your current directory mounted inside the container:

# Builds the image once, then builds the example book.
./run.sh print example/

That first run takes a little longer, while the image is assembled.

The templates and the bf command itself are baked into the image. After you change a template or update the tool, force a rebuild so the change takes effect:

./run.sh --rebuild print example/

To rebuild the image without building a book:

docker build -t book4matter .

Your book’s own files — the Markdown, the YAML, the images — are not baked in; they are read fresh from disk on every build, so editing a chapter never needs an image rebuild.

run.sh only ever shells into the container. It mounts the current directory at /work, and — when you pass a file that lives elsewhere, such as a .docx in ~/Documents — it mounts that file’s folder read-only so the container can read it. Everything else on your machine is left alone.

Chapter order

By default every chapters/*.md file is included, sorted by filename in natural order, so 2.md comes before 10.md. Numeric prefixes such as 010, 020, 030 make the order explicit and leave gaps to slot a new file between two existing ones without renumbering. If you would rather order the files by hand, list them under a chapters: key in book_metadata.yaml; then only those files, in that order, are built.

If you don’t need chapter titles, you can just put one chapter per file, and Book4matter will assume each file is a chapter and number them. You can still put titles on some chapters, like “# Introduction”, “# Afterword”.

The Novels and Flat Books chapter covers that low-structure path.

Plain .txt files are treated as pure text: Markdown commands such as #, *emphasis*, and links appear literally. Leave a blank line between paragraphs and put each chapter in its own file. Use .md for titles and other formatting.

Building each format

# For printing or KDP upload.
./run.sh print my-book/
# For sending someone a PDF.
./run.sh pdf my-book/
# For e-readers.
./run.sh epub my-book/
# For the web.
./run.sh html my-book/

Output always lands in the book’s out/ directory, named after the book’s title: print writes <title>-interior.pdf, pdf writes <title>.pdf, epub writes <title>.epub, and html writes <title>.html.

Use print when you are printing a book or uploading an interior to KDP. It omits the cover and removes internal link annotations, because print platforms such as KDP expect the cover as a separate file and may reject hyperlinks inside an interior PDF. Use pdf when you will send someone a PDF. It can include the cover and keeps hyperlinks live for the table of contents, footnotes, and web links.

The bundled examples

The repository ships with several examples.

• example
• novel
• docs

# Writes example/out/the-pocket-pipeline-interior.pdf.
./run.sh print example/

There is no such thing as parts without chapters

A book can have chapters and no parts, but never parts and no chapters. So when a manuscript uses no ## headings anywhere, book4matter reads # as chapter, not part — a plain chaptered book, arabic page numbers from page one, no divider pages. You write # for each chapter title and nothing else. This happens on its own; there is no flag to set.

--no-parts: when you do use ## inside a chapter

Some authors naturally write # for a chapter and ## for a heading within that chapter. Left alone, book4matter would read those as parts and chapters. Pass --no-parts (or set no-parts: true in book_style.yaml) and every heading shifts down one level: # becomes a chapter, ## a section, ### a subsection, and so on. No part dividers are produced.

./run.sh print my-novel/ --no-parts

Files with no heading become numbered chapters

Here is the smallest possible book: a folder of text files with no markup in them at all.

my-novel/
  book_metadata.yaml
  chapters/
    01.txt
    02.txt
    03.txt

Each file with no heading becomes one chapter, numbered in the order the files are read — the first file is Chapter 1, the next Chapter 2, and so on. You never type the numbers; book4matter supplies them, so inserting or reordering a file renumbers the rest. The chapter opens with a centered numeral over a short rule, the classic novel look.

Because nothing in the book carries a title, there is nothing to list, so the Contents page is left out automatically. (Set toc: true in book_style.yaml if you want one anyway; the numbered chapters then appear as “Chapter 1”, “Chapter 2”, and so on.)

Plain text files

Chapters may be .txt as well as .md. A .txt file is pure text: Markdown headings, emphasis, links, and scene-break markers appear literally. Blank lines separate paragraphs. Each file becomes an automatically numbered chapter in PDF/print builds. Use .md when you want Markdown formatting.

A named section among numbered chapters

Most novels want at least a titled page or two — a prologue, an introduction, an afterword. Give that one file a # heading and leave the rest without one:

chapters/
  00-introduction.md      # begins with "# Introduction"
  01.txt                   # no heading
  02.txt                   # no heading
  99-afterword.md         # begins with "# Afterword"

A titled file set among untitled ones is treated as a named section: it shows its title (Introduction, Afterword) and is not given a chapter number, nor does it disturb the count. The untitled files remain Chapter 1, Chapter 2. Because the book now has titles, a Contents page is included, listing the named sections alongside the numbered chapters.

If instead every file has a # title, they are all ordinary titled chapters, numbered straight through — the titled-chapter novel, or any chaptered non-fiction book built with --no-parts.

The bundled novel

The repository ships a second example, novel/, alongside the example/ book. It is a very short fable with no titles, no parts, and no markup — just numbered .txt chapters — so you can see the whole of this chapter at work:

# Writes novel/out/the-smallest-fire-interior.pdf.
./run.sh print novel/

Where images live

Keep images in a media/ folder at the root of your book. Chapter files sit one level down, in chapters/, so they reference an image with a leading ../:

![A frame from the Vienna Ball](../media/vienna.jpg)

That one path works everywhere — print, digital PDF, EPUB, HTML, and your Markdown editor’s preview — because the build compiles from the book root and never rewrites your paths.

Captions and centering

A captioned image becomes a centered figure automatically, in every format:

![The closed hold, seen from above](../media/hold.png)

An image with no caption is treated as inline text and sits flush left. To center a caption-less image on its own line, tag it {.center}:

![](../media/ornament.svg){.center}

Sizing

Set the size with width or height:

![](../media/diagram.svg){width="3in"}

Give one dimension and the other scales to keep the image’s proportions. Setting both width and height to a ratio that does not match the image can crop it, so as a rule size by a single dimension. SVG line art is welcome and scales without loss; for photographs, supply roughly 300 DPI at the printed size, which is what KDP expects for a sharp result.

Wrapping text around an image

To float an image to one side and let the section’s text flow beside it, tag it {.wrap-right} or {.wrap-left}:

![](../media/step.svg){.wrap-right width="2in"}

The text of this section flows up the side of the image and returns to full
width once it clears the bottom edge.

The wrap runs from the image to the end of its section — that is, until the next heading at the same level or shallower. In the PDF outputs this is a true text wrap; in EPUB and HTML it is a CSS float, which modern e-readers honor and older ones quietly ignore (the image just becomes a normal block — fine either way).

Scene breaks

A “scene break” between passages is written as three hyphens alone on their own line. In EPUB and HTML it renders as a centered * * * ornament instead of a hard rule.

Print note. The PDF pipeline does not yet render a bare scene break — the Typst template defines no rule for it — so avoid one in a book you build to print until that support is added.

Tables

Write a normal Markdown pipe table and align a column with colons in the divider row. In the PDF outputs it is set in book (booktabs) style: a rule above, a rule under the header, and a rule below — no vertical lines, no shaded cells — with the header in bold and figures set in tabular (fixed-width) columns so digits line up.

| Step | Count | Beats |
|------|------:|------:|
| Rise |     1 |     1 |
| Turn |     2 |    23 |
| Fall |     3 |   456 |

Block quotes

Mark a quotation with >; never indent by hand. A block quote is set a little smaller and in italic, indented from both margins with air above and below:

Waltzing has undergone so many alterations that the dance of today bears little resemblance to its ancestor — yet the family likeness survives.

Footnotes

Markdown footnotes work as usual. In the two PDF outputs they fall to the foot of the page; in EPUB they collect at the end of the chapter. In the single-page HTML build, superscript markers link to a Footnotes section at the end of the book. The table of contents also links to that section when notes are present. The digital pdf output keeps its footnote markers clickable; the print output does not, because KDP rejects internal hyperlinks in print interiors.

While you can put footnotes anywhere, we recommend putting them in the file where they are referenced. If you put all the footnotes in an otherwise empty file, you may end up with a “Ghost Chapter” in the table of contents, represeting the empty file. This will happen with an empty file, too.

Practice the rise slowly at first.[^rise]

[^rise]: Rising too early is the commonest beginner's mistake.

Links

Links survive to every format, but the target decides whether they are clickable. Use the digital pdf, EPUB, and HTML outputs when links should work on screen; use print when the file is going to a printer or to KDP.

• In digital PDF, EPUB, and HTML links stay live. That includes the table of contents, footnotes, cross-references, and external web links.
• In print there are no clickable annotations, because KDP rejects them, but the links still guide the reader. An internal cross-reference to another part of the book — [Rotation](#rotation) — prints as its text followed by the page it points to, so "Rotation" (page 42); the page number is resolved for you at build time and updates automatically as the book repaginates. (A link whose target is missing simply prints its text.) External web links print the destination after the visible text, so [CLICK HERE](https://www.example.com) becomes CLICK HERE (https://www.example.com). A bare autolink shows its URL once. Email addresses are kept whole and never broken at a hyphen across a line.

Write internal links with Markdown link syntax, [text](#anchor), where the anchor matches a heading. Raw HTML anchors like <a href="#anchor"> do not survive to print — only the Markdown form is turned into a page reference.

Punctuation

Write punctuation the Markdown way and the build sets it properly: -- becomes an en dash, --- an em dash, and straight quotes turn into curly ones. There is no need to paste Unicode dashes or smart quotes by hand.

Math

Unfortunately, we don’t yet have math expressions working fully in HTML and EPUB. They work fine in pdf and print.

Register the kinds you use

First tell the book which kinds of thing you track, in book_metadata.yaml. Each kind gets a label: the word printed before the number and heading its list.

tracked:
  exercise: { label: "Exercise" }
  figure:   { label: "Figure" }
  chart:    { label: "Chart" }
  table:    { label: "Table" }

Registering the kinds up front is what keeps the feature safe: only these words are treated as tracked-item markup, so an ordinary {ratio: 3:2} written in your prose is left completely alone. A kind is lowercase letters, digits, or hyphens.

Define an item where it belongs

Give each item a short id — a name that means something to you, unique within the whole book. Two ways to write a definition:

{exercise:pushups:def}
{exercise:pushups Push-ups to failure}

The first defines an exercise with the id pushups and no title. The second does the same but adds a title: anything after the first space is the title. Both print in place as Exercise 3 (whatever the next number is); the title is not printed here — it is saved for the list at the back. Write any caption text around the token yourself:

{figure:rotary A rotary telephone}. *An early rotary dial, c. 1950.*

For a figure or chart, put the definition in the caption beside the image; for an exercise, at the head of the exercise. Each kind counts on its own, so your first figure is Figure 1 even if three exercises came before it.

Refer to an item by name

Anywhere else — before or after the definition — refer to the item with just its kind and id, no :def:

Warm up before you attempt {exercise:pushups}.

That prints Exercise 3, and the number is always right because the build looks it up. What the reference becomes depends on the output, exactly like any other internal link:

• In digital PDF, EPUB, and HTML it is a live, clickable link to the item.
• In print there are no clickable links (KDP forbids them), so it prints the number followed by the page, as Exercise 3 (page 42) — resolved for you and kept correct as the book repaginates.

Because you never type a number, inserting, removing, or reordering items is free: every number and every page updates on the next build.

List them at the back (or the front)

Drop this on a line of its own wherever you want the list to appear:

{index:exercise}

It prints every exercise in order of appearance, each one a link to the item. In the print and digital PDF outputs each entry carries its page number, like a table of contents for your exercises; in EPUB and HTML, which have no fixed pages, the entry is simply a tappable link. Give it a heading of its own:

# List of Exercises {.section}

{index:exercise}

By book convention a List of Figures or List of Tables sits in the front matter, just after the table of contents, while an alphabetical index of terms goes in the back. Book4matter does not force either: the list appears wherever you place {index:...}, and the page numbers resolve correctly whether the content it points to comes before or after it.

When something is wrong, the build says so

The system fails loudly rather than printing a quietly wrong book:

• A reference to an id that is never defined stops the build and names it — usually a typo in the id, or a definition you forgot to mark with :def.
• Defining the same id twice for one kind stops the build.
• An unregistered kind in an unmistakable token — {exercise:x:def} or {index:exercise} when exercise isn’t in your tracked: map — stops the build. This is what catches the commonest mistake: forgetting the tracked: block altogether, or mistyping a kind ({index:figurse}).

The two unmistakable forms are the :def keyword and {index:...}; they can only be tracked markup, so an unregistered kind there is always an error. The plainer forms overlap with ordinary writing, so {exercise:pushups} or {exercise:pushups A title} with an unregistered kind is left as text and prints verbatim (you will see it and can fix it) rather than being seized from your prose. Either way, tokens inside code spans and fenced code blocks are never touched — which is how this chapter shows them to you.

Numbering is book-wide, so the one output that cannot do it is a single-chapter HTML fragment (html chapter N): with only one chapter in hand there is no way to number across the book or resolve a reference to another chapter, so tracked tokens are left as-is there. Every whole-book output — print, PDF, EPUB, and the whole-book HTML page — handles them fully.

An alphabetical index of terms

Mark a definition by surrounding its words with double brackets:

Let's talk about [[practice hold]] in [[Rotary Waltz]].

The sentence prints as ordinary text, with no brackets, numbering, or special styling. Only marked definitions enter the index; other mentions are not collected automatically. No tracked: registration is needed for terms. The name term is reserved for this built-in index.

Place the index on its own line, under a heading of your choice:

# Index {.section}

{index:term}

Entries sort alphabetically without regard to case. Repeated definitions of the same term share an entry, using the spelling of the first definition. In print and PDF the entry lists its page numbers, with each page listed only once. Digital PDF page numbers link to their definitions; print has no hyperlinks. HTML and EPUB link the term to its first definition, with numbered links to additional definitions. The index may appear before or after the definitions.

Every definition has a separate term-based anchor, such as idx-frame-1 or idx-practice-hold-1. Additional definitions with the same slug increment the suffix. Heading definitions retain their own index anchors on the term itself. The build removes duplicate index IDs from generated navigation, keeping the definition as the unique target and its heading visible when following a link. Ordinary heading links continue to use the heading’s original anchor. In print and PDF, the contents renders the heading text without its index marker. A repeated definition marker stops the build with the term and anchor ID in the error, rather than silently indexing a contents-page copy. Separate intentional definitions of the same term still have distinct IDs and are valid. HTML and EPUB also validate index anchors after navigation cleanup: a duplicate ID or any definition ID left in navigation stops the build, naming the anchor, generated file, and line numbers. EPUB checks across chapter files as well as within each file, even when EPUBCheck is disabled with --no-check.

Markers must contain plain text; place emphasis around the entire marker if needed (*[[practice hold]]*). Markers in code spans and code blocks stay literal. Reference (:ref) syntax is not supported yet. Single-chapter HTML fragments leave markers literal, like other tracked markup.

Indexing text that is already a link

Put the double-bracket definition inside the ordinary Markdown link text:

I started taking classes with Stanford University's [[[Richard Powers]]](https://www.richardpowers.com).

The three opening brackets are intentional: the outer [ starts the link text, and the inner [[ starts the index definition. The closing brackets nest the same way, followed by the link destination in parentheses. No spaces, escapes, or bold markup are needed.

The name remains an ordinary outbound link, with the same styling as other links. The Richard Powers entry in {index:term} links back to the name’s location in the book; clicking the name in the prose follows the external URL. This combines an outbound link and an index definition without creating nested links: the index definition supplies an anchor inside the outbound link.

Using a different name in the index

Separate the visible text from the index entry with |:

I started taking classes with [[Richard Powers|Powers, Richard]].

The prose shows Richard Powers, while the index lists Powers, Richard under P. Both sides are plain text; spaces around the separator are trimmed. The index entry determines grouping, alphabetical sorting, and the anchor name (for example, idx-powers-richard-1). Different visible names with the same index entry are collected together, just like repeated ordinary definitions.

This also works inside an outbound link, without adding bold formatting:

I started taking classes with Stanford University's [[[Richard Powers|Powers, Richard]]](https://www.richardpowers.com).

Clicking the name in the prose opens the external website; clicking Powers, Richard in the index returns to this passage. In print and PDF, the index entry has the definition’s page number as usual. Use exactly one | and provide nonempty text on both sides. Existing [[term]] definitions work unchanged, using the same words in the prose and index.

Grouping terms with subentries

Use > in the index wording to separate a parent entry from a subentry:

[[Practice hold]]
[[polka hold|Practice hold>polka]]

The second marker displays polka hold in the prose. The index groups it under Practice hold, with an indented polka entry:

Practice hold ................ 22
    > polka .................. 23

Use | to separate the visible words from the index wording, as with other aliases. Spaces around > are optional and trimmed. The parent and its subentries sort alphabetically without regard to case; repeated definitions of the same subentry share one entry, with duplicate page numbers removed. Subentries with the same name under different parents remain separate.

If only a subentry is marked, its parent is created automatically. A parent gets its own page numbers or definition links only from explicit parent markers such as [[Practice hold]]; it does not collect its children’s pages. In HTML and EPUB, children link to their own definitions, and an automatically created parent without a definition is plain text.

Subentries also work in headings and outbound links:

## [[Polka practice hold|Practice hold>polka]]

[[[polka hold|Practice hold>polka]]](https://example.com)

The heading keeps its normal appearance and the link still opens the external website. The index links to the marked term in the book. Each definition has its own anchor, such as idx-practice-hold-polka-1, excluded from the contents in every format.

Index rows have dot leaders between the term and its locations, and every subentry has a > marker as well as indentation. In HTML and EPUB, the numbers on the right are linked occurrence numbers (1, 2, and so on), not fixed page numbers. The column is labelled Refs; each number opens an indexed occurrence. The term itself also links to the first definition. Automatically created parents without definitions have no leaders or location numbers.

Print and PDF keep each parent with its first child. If a group spans pages, the parent repeats as Practice hold (continued) above the children on each subsequent page. The continuation heading does not repeat the parent’s page numbers or create a new index definition. Long child rows stay together.

One level of subentries is supported. Both parent and child must be nonempty; [[text|Parent>]], [[text|>child]], and [[text|A>B>C]] stop the build with a markup error. Commas remain ordinary index text, as in Powers, Richard.

Adding “see” aliases

Add alternate lookup names after the main index wording, separated by ;:

[[Tempo|Tempo;BPM]]

The prose displays Tempo. The index contains a normal Tempo entry with its locations, plus BPM. see Tempo under B when BPM has no indexed occurrences of its own. That “see” entry has no page numbers or dot leaders. In digital PDF, HTML, and EPUB, both “see” and “see also” link to the target’s row in the index, where readers can choose among all its locations. A target with subentries links to the specific subentry’s row. Print shows plain text.

You can declare several aliases on one definition:

[[Tempo|Tempo;BPM;Beats per minute]]

The visible wording can differ, and aliases also work in headings and links:

## [[Musical speed|Tempo;BPM]]

[[[Tempo|Tempo;BPM]]](https://example.com)

An alias can point to a subentry:

[[polka hold|Practice hold>polka;Polka grip]]

That adds Polka grip. see Practice hold, polka, linking to the polka hold definition. Alias names themselves are top-level entries, not subentries.

If the alias also has indexed occurrences, the index keeps those locations and adds see also automatically:

[[Tempo|Tempo;BPM]]
[[BPM]]
[[BPM]]

Here BPM lists the locations of both [[BPM]] markers, followed by see also Tempo. Tempo lists the location of the first marker. If BPM has subentries, those are kept too. You can add occurrences anywhere in the book, before or after the alias declaration; no markup changes are needed. Ordinary, unmarked mentions of BPM do not add index locations or change “see” to “see also”.

Spaces around ; are trimmed. Repeating the same alias for the same entry is allowed and produces one cross-reference. An alias cannot be empty, refer to itself, or point to different entries. Names are compared without regard to case. Invalid aliases stop the build with a source diagnostic. In index wording after |, ; is reserved for alias separators; commas remain ordinary text, as in Powers, Richard.

Finding markup errors

Invalid term definitions stop the build with a reason, the original chapter path and line number, and the offending marker. For example:

tracked.lua: term definitions require nonempty display text and index entry
  at /path/to/book/chapters/010-introduction.md:12
  offending markup: [[Richard Powers|]]

Print diagnostics refer to the chapter you edit, rather than a temporary file created during preprocessing. If identical markup occurs in several places, the error lists matching source locations instead of guessing one. For input from standard input or markup transformed by Markdown parsing, a source location may be unavailable; the message still includes the offending marker.

The “Also by” page

Give an also-by: list and book4matter adds an “Also by Author” page in the front matter of the PDF outputs; omit it and there is no such page. Each entry needs a title and may add a cover image, a qr image, and a url. A bare string is treated as a title-only entry.

also-by:
  - title: "How to Teach Ballroom Dancing"
    cover: "media/htbd-cover.jpg"
    qr: "media/htbd-qr.png"
    url: "howtoteachballroomdancing.com"
  # Title only.
  - "An Earlier Work"

Tracked items

tracked: registers the kinds of thing book4matter auto-numbers, cross-references, and can list — exercises, figures, charts, tables, whatever you use. Each kind maps to a label, the word printed before the number (Exercise 3) and heading its list. A bare string is shorthand for the label.

tracked:
  exercise: { label: "Exercise" }
  figure:   { label: "Figure" }
  chart: "Chart"

Omit the key and nothing is tracked. How to write the {...} tokens themselves — defining items, referring to them, and placing a list — is covered in the Auto-Numbering, Cross-References, and Lists chapter.

Listing chapters explicitly

By default every file in chapters/ is built, in natural filename order. To fix the order by hand instead, list the files under chapters:, relative to the book directory; only those files, in that order, are built. A listed file that does not exist stops the build.

chapters:
  - chapters/010-introduction.md
  - chapters/020-first-steps.md

Not a metadata key: --build-id is a command-line flag, not something you put here, because it changes from build to build. See the Command-Line chapter.

print

./run.sh print [bookdir] [--pages N] [--keep] [--no-parts] [--build-id ID]

Builds the print interior PDF to bookdir/out/<title>-interior.pdf. Use this for KDP upload or for a file you intend to print as a book. The print interior does not include the cover, because KDP takes the print cover as a separate upload. It also removes internal hyperlinks from the table of contents, footnotes, and cross-references, because Amazon KDP enforces no hyperlinks in a print interior. External web links are converted to visible text plus their destination, as in CLICK HERE (https://www.example.com).

• --pages N — the estimated final page count. It selects a KDP-appropriate inside gutter (see the margins table in the previous chapter). Omit it and a generous default gutter is used. Any margins in book_style.yaml win regardless.
• --keep — keep the intermediate Typst files (_body.typ, _meta.typ, book.typ, main.typ) in out/ instead of deleting them. Handy when you want to read the generated Typst.
• --no-parts — treat # headings as chapters, not parts, shifting every heading down one level. See the Novels and Flat Books chapter.
• --build-id ID — a printing identifier, printed as “Printing: ID” on the copyright page.

pdf

./run.sh pdf [bookdir] [--pages N] [--keep] [--no-parts] [--build-id ID]

Builds a digital PDF to bookdir/out/<title>.pdf. Use this when you will send someone a PDF directly. It uses the same page layout as print, but keeps hyperlinks live for the table of contents, footnotes, cross-references, and external links. If book_metadata.yaml has a cover: image, the digital PDF includes it as the first page.

• --pages N — the estimated final page count, using the same gutter logic as print.
• --keep — keep the intermediate Typst files in out/.
• --no-parts — treat # headings as chapters, not parts (as for print).
• --build-id ID — a printing identifier, printed as “Printing: ID” on the copyright page.

epub

./run.sh epub [bookdir] [--no-check] [--build-id ID]

Builds an EPUB 3 to bookdir/out/<title>.epub. The result is validated with epubcheck — the same kind of check KDP runs on upload — and validation errors fail the build.

• --no-check — skip the epubcheck step.
• --build-id ID — appended to the rights line in the EPUB metadata.

The EPUB cover, if any, comes from the cover: key in book_metadata.yaml.

html

# Whole book: one standalone page with a clickable table of contents.
./run.sh html [bookdir]
# Just the contents, as a link-free fragment.
./run.sh html toc [bookdir]
# One chapter, as an HTML fragment.
./run.sh html chapter NN [bookdir]

• The whole-book form is a single self-contained page (resources embedded) with a clickable table of contents — the form used for the book4matter website. It links an optional book_style.css after the embedded styles, so dropping a book_style.css next to the page (or copying your project’s CSS into out/ under that name) themes the site; omit it and the embedded styling stands. If book_metadata.yaml has a cover: image, the whole-book page embeds it near the top.
• toc emits a <nav class="book-toc"> of plain, unlinked titles to drop into a web page (the in-book anchors would point nowhere off-site).
• chapter NN picks one chapter: NN matches the leading number in a filename (010-foo.md is 10), or a 1-based position in the chapter list, or a filename/stem.
• --build-id is accepted for parity with the other commands but is not stamped on web output.

impose

./run.sh impose <file.pdf> [--paper P] [--signature N] \
  [--single] [--margin INCHES] [-o NAME]

Rearranges a PDF two-up into printable signatures for home binding. It is separate from the print command: KDP and commercial print shops impose pages for you, but impose is useful when you are printing on a home printer, folding the sheets, and binding the book yourself. A signature is a small stack of sheets folded together down the middle; several signatures are then stacked and sewn or glued into a codex.

impose takes any PDF, not just a book4matter interior. The output is written next to its input, so docs/out/book4matter-interior.pdf produces docs/out/book4matter-signatures.pdf. Print the result double-sided, flipping on the short edge, then fold each signature down the middle. Keep the sheets in their output order, nest each signature’s sheets, and stack the folded signatures in order for binding. Use the printer’s actual-size (100%) setting; the PDF already has two book pages on each landscape sheet, so don’t apply the printer’s booklet or multiple-pages-per-sheet option again.

Pages keep their orientation and are scaled proportionally to fit each half-sheet, with a safe margin around them. A 6×9 or 5×8 source will therefore work, but its printed pages may be smaller than the original trim size. The last signature is padded with blank pages to a multiple of four; it doesn’t have to fill the chosen signature size. There are no fold or trim marks: fold at the centre of the sheet.

For example, this makes four-sheet signatures on A4 paper:

./run.sh impose docs/out/book4matter-interior.pdf --paper a4 --signature 4

Print a signature first to check page order and duplex orientation before printing the whole book.

• --paper letter or --paper a4 — the sheet you print on. The default is letter.
• --signature N — sheets per signature. The default is 4, which makes 16-page signatures because each sheet folds to four pages.
• --single — impose the whole PDF as one folded booklet, useful for thin saddle-stitched work.
• --margin INCHES — safe margin inside each half-page cell. The default is 0.25.
• -o NAME or --output NAME — output filename, still written beside the input.

import

./run.sh import <file.docx> [bookdir] [--no-split] [--force]

Converts a Word manuscript into chapters/*.md plus an extracted media/ folder, splitting the document into one file per Heading 1.

• --no-split — write a single Markdown file instead of splitting on H1.
• --force — overwrite a chapters/ directory that already has files.

The Importing from Word chapter covers this in full.

Stamping builds with –build-id

--build-id is how you make a given printing identifiable. Compute the value once — usually the repository’s short git hash — and pass it to the outputs that stamp it. This manual’s own build.sh does exactly that:

BUILD_ID="$(git rev-parse --short=10 HEAD)"
./run.sh print docs/ --build-id "$BUILD_ID"
./run.sh pdf docs/ --build-id "$BUILD_ID"
./run.sh epub docs/ --build-id "$BUILD_ID"

Body text

The body is set justified and hyphenated, so the right margin stays even, with lining (uniform-height) figures rather than old-style ones. The default face is Libertinus Serif at 11pt: a quiet, readable book face bundled in the image, so the default needs no font setup and nothing is fetched from the network.

Paragraph indents

Paragraphs are set off by a first-line indent rather than by blank space — the book convention. In the PDF outputs, indent: in book_style.yaml chooses among three styles:

• all (the default) — indent every paragraph, including the one that opens a chapter or section. The house style: no flush-left openers.
• standard — leave the opening paragraph after a heading flush and indent the rest. The classic trade-book look, and what EPUB and HTML already do, so standard makes print match them.
• none — no indents at all; paragraphs are told apart by the space between them (block style).

EPUB and HTML always use the standard look — readers expect it on screen and can override it anyway — so indent: is a PDF setting.

Headings

Headings are set in a sans-serif face (Liberation Sans by default), in capitals, ragged-right: they never justify or hyphenate, so a long title wraps whole words instead of stretching or splitting. Each level has its own job — a part is a divider page, a chapter opens a fresh page, and the lower levels are run-in section headings.

Page numbers and running heads

Front matter carries lowercase roman folios (i, ii, iii …); arabic numbering begins at the first part. Display pages — the title, copyright, and “Also by” pages, and every part divider — show no folio, though they still count, so the numbering downstream stays correct. Running heads are off by default; when on, they appear only on ordinary body pages (never where a part or chapter opens), and only in the PDF outputs.

Parts and chapters

A part divider sets its title about a third of the way down the page, rather than dead centre, with room beneath for optional divider text. Chapters open on a fresh page with a centered numeral over a short rule and the title centered beneath (set chapter-style: left for a flush-left “CHAPTER N” opener instead). Both are numbered automatically, and chapter numbers run straight through the whole book instead of resetting inside each part.

Two more book_style.yaml switches, parts-recto and chapters-recto, make parts or chapters begin on a recto (right-hand) page, inserting a blank page when needed — the traditional way to open a chapter in a well-set book. The inserted blank is counted in the page numbering (it may show a folio), and the main matter still starts at page 1.

Figures

A captioned image becomes a centered figure; figures are not auto-numbered (“Figure 1.2”), because trade books usually refer to an image in prose rather than by number. How tables, quotes, footnotes, and links are set is described where you write them, in the Tables, Quotes, Footnotes, and Links chapter.

Links in PDF and print

The pdf command is for screen reading, so hyperlinks stay live there: the table of contents, footnotes, cross-references, and external links are all clickable. The print command is for physical books and KDP interiors, which forbid clickable annotations — so instead of dropping the reader, a print cross-reference to another part of the book prints as its text plus the target page, "Rotation" (page 42), with the page number resolved at build time. External web links print their destination in parentheses after the visible text, and email addresses are kept whole so they never break at a hyphen. EPUB and HTML links stay live and bare.

Two routes from one source

Markdown is the single source. Pandoc parses it, and from there the formats diverge:

• Print and digital PDF take the long way round. Pandoc converts the Markdown into a Typst body fragment, and Typst typesets that into pages.
• EPUB and HTML are written by Pandoc directly.

Why route PDF output through Typst at all? Because Typst alone cannot produce EPUB, and authoring straight in Typst would forfeit the EPUB and HTML outputs. With Pandoc in the middle, all four outputs come from the same Markdown. Typst earns its place on the page-layout side: it is fast, needs no enormous TeX installation, embeds fonts automatically, and ships in the same pandoc/typst image.

What a PDF build generates

Build with --keep and you can read the intermediate Typst the pipeline writes into out/:

• _meta.typ — a Typst dictionary built from your book_metadata.yaml and book_style.yaml: title, authors, trim, margins, fonts, and the rest.
• _body.typ — Pandoc’s Typst rendering of your chapters, with a short prelude of imports prepended.
• book.typ — the template, copied in from the image.
• main.typ — the short entry point that ties them together:

#import "book.typ": book
#import "_meta.typ": meta
#show: book.with(meta)
#include "_body.typ"

Typst compiles main.typ into either the print interior PDF or the digital PDF. Without --keep, these files are removed after the build.

The two commands share this pipeline, then differ in the metadata passed to the template. print removes internal hyperlinks and omits the cover; pdf keeps links live and includes the configured cover image as the first page.

The template

book.typ owns the PDF page geometry — the exact trim, the asymmetric binding gutter used by print books, font embedding, and page numbering — and the styling: the title and copyright pages, the table of contents, and the show rules that turn each heading level into a part, a chapter, or a section. That styling is adapted from the MIT-0-licensed ilm Typst template.

The Pandoc filters

Small Lua filters bridge Markdown and each output so the same source behaves consistently across formats:

• PDF outputs: parts.lua numbers the parts, acts on the {.unnumbered}, {.new-page}, and {.section} classes, switches the front matter over to the main-matter page numbers, and lifts part-divider text onto the divider page; wrap.lua turns a .wrap-left / .wrap-right image into a Typst text wrap and centers a .center image.
• EPUB and HTML: epub-parts.lua injects the “Part N” / “Chapter N” labels, epub-wrap.lua floats wrap images with CSS, and toc-list.lua builds the link-free contents used by html toc.

Fonts

Typst embeds whatever fonts a build uses. The defaults (Libertinus Serif and Liberation Sans) live in the image. For a custom face, Typst also searches a per-book fonts/ folder — the subject of the next chapter — so the fonts travel with the book and nothing is installed or downloaded. The wrap-it package behind text wrapping is vendored into the image as well, so a compile never has to reach the network.

Restyling through book_style.yaml

Trim size, margins, body and heading fonts, type size, the Contents page, running heads, the title rule — all of these are keys in book_style.yaml (see the reference in Part Three). Because appearance lives in that one file, you can copy or symlink a single book_style.yaml across several books to give them a shared house style, and restyle them all by editing it in one place. The manuscript and its metadata never change.

Using a custom font

The default faces are bundled, but you can use any font you have licensed:

1. Make a fonts/ folder at the root of your book.
2. Drop the .ttf or .otf files into it.
3. Name the family in book_style.yaml:

font: "EB Garamond"
heading-font: "Cormorant"

When a fonts/ folder is present, book4matter points Typst at it automatically, so the fonts travel with the book project — no system install, no image rebuild. System and bundled fonts are still searched, so a missing fonts/ folder is fine. The PDF builds embed whatever is used, so the font’s license must permit PDF embedding.

True to this project’s grain, prefer a real, licensed book face that you keep with the project over pulling one from a web font service. It keeps the build self-contained and the typography under your control.

Fonts in EPUB and HTML

EPUB and HTML deliberately do not embed your custom fonts. epub.css names only the generic serif and sans-serif families and lets the reader’s device choose — which is what readers expect, and what lets them override fonts anyway. A custom font: therefore affects the two PDF outputs only.

The files

• templates/book.typ — the PDF page template. It holds the page geometry, the title / copyright / “Also by” / contents pages, and the show rules that style every heading level. Most PDF-appearance changes happen here: heading sizes and spacing, the title-page layout, the running-head format, the table and block-quote styling.
• templates/epub.css — the styling for EPUB and the HTML outputs. Edit this to change how the e-book and the default web page look.
• templates/*.lua — the Pandoc filters from the previous chapter. Edit these only to change structural behavior: how labels are injected, how wraps work, how the contents list is built.

Applying a change

The templates live inside the image, so after editing one, rebuild:

./run.sh --rebuild print mybook/

Until you rebuild, the old templates are what run.

What book.typ expects

book.typ is driven by a meta dictionary that the tool assembles from your YAML (you can read it as _meta.typ in a --keep build). The template consumes a fixed set of keys — the ones documented in Part Three. Changing how an existing value is used is a book.typ edit on its own. Introducing a brand-new setting would also mean teaching the tool to pass it through, which is a code change beyond the scope of styling.

Restyling the website without touching the template

The HTML output embeds epub.css followed by html.css, which adds a reading layout and a sidebar table of contents on wide screens. On smaller screens, the contents appear above the text. You need not edit either file to restyle the site. Every page that bf html generates links an optional book_style.css after the built-in styles, so any rules in that file win on the cascade. The file is optional: drop a book_style.css next to the generated page — or have your build script copy one into out/ — and the site picks it up; leave it out and the page falls back to the built-in styling. The page is plain, semantic HTML — a #TOC nav, one section per part and chapter, .part-label / .chapter-label spans — so a stylesheet has clean hooks to target.

This manual does exactly that: docs/build.sh copies its book4matter-web.css into out/book_style.css, giving the site its own look without disturbing the templates that the PDF, EPUB, and HTML outputs share.

What it does

Pandoc converts the document to Markdown and extracts its images, and book4matter then splits the result into chapter files:

• One file per Heading 1. Each Heading 1 starts a new chapter file. The split is fence-aware, so a # inside a code block is never mistaken for a heading. Anything before the first Heading 1 is written to 000-frontmatter.md for review — usually you trim it, since the template makes its own title page and contents.
• Numbered in steps of ten. Files are named 010-slug.md, 020-slug.md, and so on, leaving gaps so you can slot in a part divider or an appendix later without renumbering the rest.
• Images extracted to media/. Pictures are pulled into a media/ folder and referenced as ../media/..., the same convention a hand-written book uses. An image Word had embedded in a heading is lifted out to a figure just beneath it.
• Punctuation kept verbatim. The author’s real em dashes, curly quotes, and ellipses are preserved rather than rewritten, so the Markdown is clean to edit. Tracked changes are accepted and comments are dropped.

Flags

• --no-split — write the whole document as a single Markdown file instead of splitting on Heading 1.
• --force — overwrite a chapters/ folder that already holds files. By default the importer refuses, so existing work is never clobbered by accident.

After importing

Expect to tidy up by hand. Import carries the words, the structure, and the images across; you then map the headings onto book4matter’s parts and chapters (Word’s single level of “Heading 1” cannot express the part/chapter distinction), check the image sizes against the ~300 DPI print target, and trim the front matter. From there it is an ordinary book4matter project.

Output Formats

Input Formats

While writing in Markdown is much simpler than writing in Word, there are some challenges. If you are using human editors, the editing industry largely runs on “Microsoft Word, with track changes”. This makes it very easy to have an editor make a lot of changes, and you can easily accept them individually or as a whole.

This actually works just fine with Markdown, as you can use version control and merge. The issue is that the number of book editors who are familiar with Git is much smaller than the number who know Word.