v2.6: Cover Story 📔

Release Notes

This update adds new cover customization options, along with other improvements and fixes.

Markdown to EPUB Converter

New Features

• Use the new --base-cover-image option with swift-book-epub to request that a specific cover template image be used, instead of deriving one from the version string and the bundled assets.
• Use the new --cover-banner-text and --cover-banner-color options with swift-book-epub to add a custom banner to the inner cover. By default, the Beta banner will apply for versions containing "beta" in their version names.
• Use the new --publication-identifier-seed option with swift-book-epub to override the default pre-hash seed used when deriving the EPUB publication identifier.

Updates & Improvements

• The generated EPUB inner cover uses SVG-based layout and typography, improving cover composition, and accessibility text.
• The inner cover will show the optional footer line if one is provided for the outer cover.
• Aside and grammar block spacing now uses relative em-based sizing for more consistent scaling across reading environments.

Resolved Issues

• Fixed: Some inline code spans that resemble Markdown link syntax may be display incorrectly.
• Fixed: Section title pages may not be vertically centered within the page.

Related PRs

• fix(epub): preserve inline code spans that look like markdown links by @ekassos in #119
• feat(epub): add --base-cover-image support by @ekassos in #120
• feat:(epub): add cover banner, other style improvements by @ekassos in #121
• fix(epub): mark cover document as svg in OPF manifest by @ekassos in #122
• feat(epub): custom publication identifier by @ekassos in #124
• fix(epub): center title pages by @ekassos in #125
• change(epub): normalize aside and grammar spacing by @ekassos in #126
• release: v2.6.0 by @ekassos in #127

Full Changelog: v2.5.2...v2.6.0

v2.5.2

Release Notes

Markdown to EPUB Conversion

Resolved Issues

• Fixed: Double hyphens in generated EPUB prose may not be converted to en dashes.

Security

Updates & Improvements

• Update pillow (12.1.1 to 12.2.0) to resolve FITS GZIP decompression bomb in Pillow.
• Update pytest (9.0.2 to 9.0.3) to resolve pytest has vulnerable tmpdir handling.

Related PRs

• fix(epub): convert double hyphens to en dashes by @ekassos in #113
• chore(deps): bump pillow from 12.1.1 to 12.2.0 in the uv group across 1 directory by @dependabot[bot] in #114
• chore(deps-dev): bump pytest from 9.0.2 to 9.0.3 in the uv group across 1 directory by @dependabot[bot] in #115
• release: v2.5.2 by @ekassos in #116

Full Changelog: v2.5.1...v2.5.2

v2.5.1

Release Notes

Markdown to LaTeX Converter

Resolved Issues

• Fixed: PDF editions may be missing the bundled Swift logo assets used in headers and footnotes.

LaTeX Template

Resolved Issues

• Fixed: The Apache License text in the generated Acknowledgments chapter may be rendered with the wrong text color in dark mode.
• Fixed: Asterisks in the Apache License text may be incorrectly rendered in math mode in the generated Acknowledgments chapter.

Related PRs

• fix: missing swift logo assets by @ekassos in #109
• fix: color text for apache license by @ekassos in #110
• fix: asterisk in math mode in notices by @ekassos in #111
• release: v2.5.1 by @ekassos in #112

Full Changelog: v2.5.0...v2.5.1

v2.5: Version Control

Release Notes

This update provides important bug fixes and improvements.

CLI

New Features

• Use the --override-version <version> option when using swift-book-pdf to override the corresponding Swift version for the book. Include the word beta for beta versions. If not provided, the version will be determined by parsing the table of contents.

Updates & Improvements

• Both swift-book-pdf and swift-book-epub require the Swift version to be resolvable by parsing the table of contents or from an explicit override.

Markdown to LaTeX Converter

Resolved Issues

• Fixed: The generated Summary of the Grammar output may be missing explicit line breaks between grammar rules.
• Fixed: Percent signs may be escaped incorrectly in code blocks.

LaTeX Template

Resolved Issues

• Fixed: The generated Acknowledgments chapter may be missing the swift-docc-render copyright notice.
• Fixed: The Apache License text in the generated Acknowledgments chapter may be rendered with the wrong text color in dark mode.

Internal

Updates & Improvements

• Add .git-blame-ignore-revs file to suppress the repository-wide Ruff linting commit from git blame.

Related PRs

• feat: override version in pdf by @ekassos in #102
• fix: missing swift-docc-render copyright by @ekassos in #104
• fix: color text for apache license by @ekassos in #103
• fix: module escape in code blocks by @ekassos in #105
• chore: git-blame-ignore-revs by @ekassos in #106
• fix: grammar table new lines by @ekassos in #107
• release: v2.5.0 by @ekassos in #108

Full Changelog: v2.4.1...v2.5.0

v2.4.1

Release Notes

LaTeX Template

Resolved Issues

• Fixed: The Acknowledgments chapter is missing the swift-docc-render NOTICE content.

Related PRs

• fix: include swift-docc-render NOTICE by @ekassos in #100
• release: v2.4.1 by @ekassos in #101

Full Changelog: v2.4.0...v2.4.1

v2.4: Fine Print

Release Notes

This update provides important bug fixes and improvements.

Markdown to LaTeX Conversion

New Features

• Add auto-generated Acknowledgments chapter to PDF typesets.

Updates & Improvements

• The chapter icon in table of contents scales with the configured font size.
• Line wrapping in code blocks has been improved by adding more break opportunities.
• The continuation marker indentation for line wraps in code blocks scales with the configured code font size.

Resolved Issues

• Fixed: _?_ in grammar notes may be rendered incorrectly in generated PDF output.

CLI

New Features

• Add --dangerously-skip-legal-notices flag to skip the generating the legal notices chapter in PDF or EPUB editions. Omitting these notices may result in missing attribution, licensing, trademark, and non-affiliation disclosures that could be required for lawful redistribution. Do not distribute or publish this output unless you have independently verified that all applicable legal obligations remain satisfied.

Internal

Updates & Improvements

• Reorganize the Acknowledgments section in README and expand its attribution details.
• Move the package source tree into src/swift_book_pdf and adopt the src layout.

Related PRs

• feat: add Acknowledgments in PDF edition by @ekassos in #93
• feat: --dangerously-skip-legal-notices flag by @ekassos in #94
• feat: scalable icons with font size by @ekassos in #95
• feat: better code wrapping styling by @ekassos in #96
• fix: correct ? rendering in grammar notes by @ekassos in #97
• chore: reorganize package source tree and README by @ekassos in #98
• release: v2.4 by @ekassos in #99

Full Changelog: v2.3.1...v2.4.0

v2.3.1

Release Notes

Markdown to LaTeX Conversion & Markdown to EPUB Conversion

Resolved Issues

• Fixed: The Summary of the Grammar chapter, which is generated at runtime for recent versions of the swift-book repository, can fall out of sync in newer upstream revisions after the grammar generation pipeline moved from bin/publish-book to bin/generate-grammar.

Related PRs

• fix: support new upstream grammar generation scripts by @ekassos in #91
• release: v2.3.1 by @ekassos in #92

Full Changelog: v2.3.0...v2.3.1

v2.3: By the Books

Release Notes

This update provides important bug fixes and improvements.

Markdown to EPUB Conversion

New Features

• Use the new --ibooks-version option for swift-book-epub to write Apple Books version metadata as <meta property="ibooks:version">…</meta> in the generated OPF package document. See the Apple Books Asset Guide for more details.

Updates & Improvements

• This update includes the following improvements to the Acknowledgment section of the generated EPUB file:
  • Clarify derivative-work attribution for editions produced with swift-book-pdf, including original-work credit to Apple Inc. and the Swift project authors.
  • For original-work credit to Apple Inc. and the Swift project authors, swift-book-pdf will scan all files in the swift-book repository for copyright notices to construct the appropriate copyright year range. When available, the constructed copyright year range is included in the copyright notice.
  • Add a non-affiliation disclaimer stating that the edition is not published by, endorsed by, or affiliated with Apple Inc. or the Swift.org open source project.
  • Add the full text of the Apache License, Version 2.0 (with Runtime Library Exception).

Resolved Issues

• Fixed: Line numbers in code blocks may not scale properly at larger font sizes in the generated EPUB file.

Related PRs

• feat(epub): apple books version number by @ekassos in #86
• feat(epub): add Apache License and copyright attribution in notices page by @ekassos in #87
• fix(epub): scale code block layout with font size by @ekassos in #88
• release: v2.3.0 by @ekassos in #89
• release: v2.3.0 by @ekassos in #90

Full Changelog: v2.2.0...v2.3.0

v2.2: Hello, EPUB

Release Notes

This update adds support for generating EPUB editions of The Swift Programming Language book, along with other features and improvements.

Markdown to EPUB Conversion

New Features

• Use swift-book-epub to convert the DocC source for The Swift Programming Language book into an EPUB file. The generated EPUB file follows the familiar rendering style used by previous TSPL publications up to Swift 5.7 published in Apple Books and retains all internal references and external links.
• Customize your EPUB edition with the following options available only for swift-book-epub:
  • Use the --export-cover-image / -e flag to save the generated cover image as a separate PNG file in the output directory.
  • Use the --cover-footer-line <footer text> option to include a custom line of text in the cover image footer.
  • Use the --override-version <version> option to override the corresponding Swift version for the book. Include the word beta for beta versions, which display an alternative cover. If not provided, the version will be determined by parsing the table of contents.
  • Use the --publisher <publisher name> option to include publisher metadata in the generated EPUB file.
  • Use the --contributor <contributor name> option to include contributor metadata in the generated EPUB file.

CLI

New Features

• Use the --source-ref and --source-sha options to build from a specific swift-book tag, branch, ref, or commit without manually preparing a local checkout. --source-ref and --source-sha are supported by both swift-book-pdf and swift-book-epub.
• Installing swift-book-pdf provides both swift-book-pdf and swift-book-epub commands.

Updates & Improvements

• Updated ordering of CLI options in swift-book-pdf --help message for better discoverability.

Internal

New Features

• Add pillow dependency for image processing during EPUB generation.
• Add pytest development dependency.
• Add tests for CLI commands and options.
• Add testing step in python.yml to run the CLI tests when opening a pull request or merging to main.

Updates & Improvements

• Update pygments (2.19.2 -> 2.20.0) to resolve Pygments has Regular Expression Denial of Service (ReDoS) due to Inefficient Regex for GUID Matching.
• Update uv (0.10.12 -> 0.11.2).

Related PRs

• feat: option to create an EPUB e-book by @ekassos in #73
• feat(epub): save cover as separate file by @ekassos in #74
• feat(epub): option for custom footer text in cover by @ekassos in #75
• change: reorganize CLI options by @ekassos in #76
• feat(epub): allow for version override by @ekassos in #77
• feat(epub): add publisher option by @ekassos in #78
• feat(epub): add contributor option by @ekassos in #79
• chore: clarify epub constants by @ekassos in #80
• feat: check out upstream ref or sha by @ekassos in #81
• feat: separate CLIs, add swift-book-epub entry point by @ekassos in #82
• chore(deps): bump pygments >=2.20.0,<3.0.0 by @ekassos in #83
• chore(deps): bump uv 0.10.12 -> 0.11.2 by @ekassos in #84
• release: v2.2.0 by @ekassos in #85

Full Changelog: v2.1.0...v2.2.0

v2.1: pt. taken

Release Notes

This update adds support for customizable font sizes, along with other bug fixes and improvements.

CLI

New Features

• Use the --font-size option to provide a pt value for the base paragraph font size. Other font sizes in the typeset document are scaled proportionally. The default base paragraph font size is 9pt.
• You can now use either swift-book-pdf or swift_book_pdf to run the tool.

LaTeX Typesetting

New Features

• swift-book-pdf will detect missing LaTeX packages before typesetting and surface clearer package-specific errors during PDF generation.
• Added latexminted version check to ensure compatibility with minted.sty versions older than 3.8.0.

Markdown to LaTeX Conversion

New Features

• swift-book-pdf will generate SummaryOfTheGrammar.md during PDF assembly since the upstream swift-book repo no longer ships the chapter as a committed Markdown file. Generation uses the upstream's bin/publish-book metadata and bin/extract_grammar.awk with a built-in fallback.

Updates & Improvements

• Code and note boxes are breakable to support larger font sizes. Custom placement code maintains the current behavior for shorter boxes by moving them to the next page when possible and only splitting boxes that are longer than a page.

Resolved Issues

• Fixed: A chapter may appear multiple times in the generated PDF when the Markdown file for the subsequent chapter is missing.
• Fixed: Generated LaTeX may incorrectly enter math mode and fail on currency amounts like $1.23 because of improper literal dollar sign escaping in paragraph text.
• Fixed: The Summary of the Grammar chapter may be missing from the generated PDF because the upstream repository generates it only during publication.

Internal

Updates & Improvements

• Switch to uv for dependency management.
• Update dependencies:
  • Update pygments (2.9.0 -> 2.19.2)
  • Update tqdm (4.67.1 -> 4.67.3)
  • Update pydantic (2.10.6 -> 2.12.5)
  • Update click (8.1.8 -> 8.3.1)
  • Update latexminted (0.5.0 -> 0.6.0 for Python < 3.14, 0.7.1 for Python >= 3.14)
  • Update filelock (3.20.1 -> 3.25.2)
  • Update pre-commit (4.1.0 -> 4.5.1)
• Add additional ruff linting rules in pre-commit configuration.

Related PRs

• workflows: retire main_branch_check.yml by @ekassos in #54
• deps: switch to uv, update dependencies by @ekassos in #56
• feat: add alias for swift-book-pdf entry point by @ekassos in #57
• feat: add latexminted/minted.sty compatibility checks by @ekassos in #58
• chore: add more ruff linting rules by @ekassos in #59
• fix: escape $ in paragraph text by @ekassos in #61
• Ekassos/feat/detect missing by @ekassos in #62
• feat: font scaling options by @ekassos in #66
• fix: initialize file_path variable in process_files_in_order method by @ekassos in #69
• feat: new grammar generation pipeline by @ekassos in #70
• release: v2.1 by @ekassos in #71

Full Changelog: v2.0.1...v2.1.0