Customization Options: PDF

All available customization options for swift-book-pdf, the PDF renderer for The Swift Programming Language.

Tip

Starting with version 2.1, you can use either swift-book-pdf or swift_book_pdf. This page uses swift-book-pdf in examples.

Quick reference

Goal	Option	Usage / values
Input and output
Save the PDF somewhere else	OUTPUT_PATH	swift-book-pdf /path/to/output.pdf
Use a local swift-book checkout	-i, --input-path	-i /path/to/swift-book/
Build from a specific upstream branch or tag	--source-ref	--source-ref swift-6.2-fcs
Build from a specific upstream commit	--source-sha	--source-sha abc1234
Layout and appearance
Switch between screen and print output	--mode	digital, print
Change paper size	--paper	letter, legal, a4
Render in dark mode	--dark	swift-book-pdf --dark
Enable or disable the book gutter	--gutter, --no-gutter
Typography and fonts
Scale the typography	--font-size	--font-size 10.5
Use custom fonts	--main, --mono, --unicode, --emoji, --header-footer	--main "Minion Pro"
Versioning and content
Override the detected Swift version	--override-version	--override-version "6.2 beta 3"
Omit the generated legal notices chapter	--dangerously-skip-legal-notices
Advanced rendering
Increase the number of LaTeX passes	--typesets	--typesets 5
Print debug logs while building	--verbose

Input and output

Output path  

By default, swift-book-pdf saves the resulting PDF as swift_book.pdf in the current directory.

You can pass an output directory as the positional argument:

swift-book-pdf /path/to/output-directory/

In that case, the generated file is saved as swift_book.pdf inside that directory.

You can also pass a full .pdf path to choose the file name explicitly:

swift-book-pdf /path/to/output.pdf

Note

If you pass a file path, it must end in .pdf. Missing output directories are created automatically when possible.

Input path  

Use --input-path or -i to point swift-book-pdf to the root of a local copy of the swift-book repository. The path should contain the TSPL.docc directory. If you do not provide it, the repository is cloned from GitHub for the build.

swift-book-pdf -i /path/to/swift-book/

Build from a specific upstream revision  

If you want to build from a particular upstream revision without preparing a separate local checkout first, use one of these options:

• --source-ref for a tag, branch, or other Git ref
• --source-sha for a specific commit SHA

swift-book-pdf --source-ref swift-6.2-fcs

swift-book-pdf --source-sha abc1234

Note

--source-ref and --source-sha cannot be used together with --input-path.

If you pass both --source-ref and --source-sha, swift-book-pdf checks out the SHA and ignores the ref after printing a warning.

Layout and appearance

Rendering modes  

swift-book-pdf supports two rendering modes:

1. digital (default): best for browsing the book as a PDF. Internal references and external links are rendered as blue hyperlinks.
2. print: best for printed copies. Internal references include page numbers, and external links are added as footnotes with full URLs.

Use --mode to switch between them:

swift-book-pdf --mode print

Appearance  

swift-book-pdf renders the book in light mode by default. Use --dark to render it in dark mode.

swift-book-pdf --dark

Paper sizes  

swift-book-pdf supports three paper sizes:

1. letter (default)
2. legal
3. a4

Use --paper to choose one:

swift-book-pdf --paper legal

Book gutter  

By default, swift-book-pdf renders the book with a gutter for duplex or bound reading. The gutter setting also controls whether odd and even pages use different header and footer layouts.

Use --no-gutter to disable it:

swift-book-pdf --no-gutter

Use --gutter to enable it explicitly in scripts or repeated commands:

swift-book-pdf --gutter

Typography and fonts

Custom fonts  

swift-book-pdf requires a set of fonts to typeset The Swift Programming Language. You can use one of the available default options or provide your own fonts with these options:

• --main
• --unicode
• --mono
• --emoji
• --header-footer

swift-book-pdf verifies that your custom fonts are available to LuaTeX before typesetting. Learn how to make your fonts available to the typesetter.

Multiple custom Unicode fonts  

You can pass --unicode multiple times to cover all glyphs required for typesetting.

Note

If you do not have access to Arial Unicode MS, you can download and specify the following Noto Sans font families:

swift-book-pdf --unicode "Noto Sans" --unicode "Noto Sans SC" --unicode "Noto Sans KR" --unicode "Noto Sans Thai"

Font size  

Use --font-size to set the base paragraph font size in points. All other font sizes scale proportionally from that value. The default is 9. You can pass either an integer or a decimal value.

swift-book-pdf --font-size 10.5

Note

--font-size must be a positive number. Larger font sizes can increase the final page count.

Versioning and content

Override version detection  

By default, swift-book-pdf reads the Swift version from the upstream table of contents. Use --override-version when that parsing fails or when you need to force a specific version string.

swift-book-pdf --override-version "6.2 beta 3"

This is mainly a fallback for unusual upstream title formats. If the version cannot be determined from the source and you do not provide --override-version, the build fails.

Legal notices chapter  

By default, swift-book-pdf includes a generated legal notices chapter in the PDF.

Use --dangerously-skip-legal-notices to omit it:

swift-book-pdf --dangerously-skip-legal-notices

Caution

Omitting the generated legal notices chapter may remove attribution, licensing, trademark, and non-affiliation disclosures that can be required for redistribution.

Do not distribute or publish output generated with this flag unless you have independently verified that all applicable legal obligations remain satisfied.

Advanced rendering

Number of typesetting passes  

swift-book-pdf uses LaTeX to typeset the TSPL book. LaTeX arranges page elements dynamically, so references added in later passes may shift content and change the placement of headers and footers. To ensure everything is rendered correctly, swift-book-pdf typesets the document four times by default.

If needed, you can increase the number of typesets:

swift-book-pdf --typesets 5

Caution

Only increase the number of typesets if the document has missing references or misaligned headers or footers.

Do not decrease the number of typesets. Given the document's complexity, the extra passes help ensure stable references, headers, and footers.

Always run at least two typesets. Skipping this may break internal references to other sections.

Verbose logging

Use --verbose to enable debug logging during the build.

swift-book-pdf --verbose

This is useful when you are troubleshooting source checkout, font discovery, LuaTeX setup, or output path issues.