Customization Options: EPUB

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

Quick reference

Goal	Option	Usage / values
Input and output
Save the EPUB somewhere else	OUTPUT_PATH	swift-book-epub /path/to/output.epub
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
Cover generation
Also save the generated cover art as PNG	-e, --export-cover-image
Add a custom footer line to the cover	--cover-footer-line	--cover-footer-line "Beta"
Metadata
Override the detected Swift version	--override-version	--override-version "6.2 beta 3"
Set Apple Books version metadata	--ibooks-version	--ibooks-version 1.1
Set publisher metadata	--publisher	--publisher "Publisher"
Set contributor metadata	--contributor	--contributor "Contributor"
Content and diagnostics
Omit the generated legal notices page	--dangerously-skip-legal-notices
Print debug logs while building	--verbose

Input and output

Output path  

By default, swift-book-epub saves the resulting EPUB as swift_book.epub in the current directory.

You can pass an output directory as the positional argument:

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

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

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

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

Note

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

Input path  

Use --input-path or -i to point swift-book-epub 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-epub -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-epub --source-ref swift-6.2-fcs

swift-book-epub --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-epub checks out the SHA and ignores the ref after printing a warning.

Cover generation

Export the generated cover image  

Use --export-cover-image or -e to save the generated cover as a separate PNG file next to the EPUB output.

swift-book-epub --export-cover-image

If the EPUB file is saved as swift_book.epub, the exported cover image is saved as swift_book_cover.png. If you choose a custom EPUB file name such as tspl.epub, the exported image becomes tspl_cover.png.

Cover footer line  

Use --cover-footer-line to add a custom line of text to the footer of the generated cover image.

swift-book-epub --cover-footer-line "Beta"

This affects both the embedded EPUB cover image and any separately exported cover image created with --export-cover-image.

Metadata

Override version detection  

By default, swift-book-epub 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-epub --override-version "6.2 beta 3"

For EPUB builds, the resolved version affects the generated book title and cover treatment. If the version string contains beta, swift-book-epub uses the beta cover template.

If the version cannot be determined from the source and you do not provide --override-version, the build fails.

Apple Books version metadata  

Use --ibooks-version to write Apple Books version metadata into the generated EPUB package:

swift-book-epub --ibooks-version 1.1

This adds an OPF metadata entry in the form:

<meta property="ibooks:version">1.1</meta>

Publisher metadata  

Use --publisher to add a dc:publisher field to the EPUB metadata.

swift-book-epub --publisher "Publisher Name"

Contributor metadata  

Use --contributor to add a dc:contributor field to the EPUB metadata.

swift-book-epub --contributor "Contributor Name"

Note

swift-book-epub always includes baseline metadata for language (en), title, creator (The Swift project authors), and a generated publication identifier. --publisher, --contributor, and --ibooks-version add extra metadata on top of that default set.

Content and diagnostics

Legal notices page  

By default, swift-book-epub includes a generated legal notices page in the EPUB package and navigation files.

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

swift-book-epub --dangerously-skip-legal-notices

Caution

Omitting the generated legal notices page 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.

Verbose logging

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

swift-book-epub --verbose

This is useful when you are troubleshooting source checkout, cover generation, metadata, or output path issues.