v2.0.0 Alpha 2

We received great feedback on the first alpha for Asciidoctor PDF 2, and immediately got to work fixing bugs and wrapping up issues that didn't make it into the first alpha. This release very nearly represents what we want Asciidoctor PDF 2 to be.

There are several notable enhancements in this release worth drawing attention to. First, you can now add the notitle option to the title of any section so it only appears in the TOC, not the document. This can be useful for creating entries in the TOC that are not sections, as the entry will effectively link to the first child element. Speaking of sections, you now add the breakable option to a section to keep the title with the first block of content, just like you can do for tables. It doesn't change where the section breaks, but it does provide a hint to the converter to do extra work to keep the section title from being orphaned. On the table front, you can now style the ends and sides of the frame and the rows and cols of the grid independently. To help improve the terminology in the theme, we have separated the align and text-align keys so the meaning of these keys doesn't get entangled. You can also now set a background color on any caption and define image-based admonition icons in the theme. If you are writing an extended converter, note that all methods with the prefix layout_ have been renamed to have the prefix inscribe_. However, if a converter uses the old method names, it will still work. Finally, this release includes numerous bug fixes and a few improvements to the log messages. As usual, consult the CHANGELOG for a more detailed view of what changed.

During this development cycle, the new docs for Asciidoctor PDF continued to be improved and reorganized thanks to the work by Sarah. The new docs will go live on https://docs.asciidoctor.org at the same time Asciidoctor PDF 2.0.0 is released.

To reiterate, we don't anticipate having many alpha releases or a long prerelease cycle. We're going to give users a chance to try this release so we can uncover any unexpected regressions, errors, or problem areas. If they come up, we will try to address them quickly so that we can turn around a final release very soon.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Enhancements

• separate align and text-align keys in theme schema; remap old keys for backwards compatibility (#2095)
• allow theme to control the border on all sides of tables independently (#902)
• keep section title with first block of content is breakable option is set on section (#2075, #38)
• pass part, chapterlike, and hidden options to arrange_section method
• add support for background-color property on caption (#1995)
• add support for image-based icons, resolved from iconsdir and having the icontype file extension (#1770)
• add asciidoctor/pdf/nogmagick script to prevent Gmagick from handling PNG images (#1687)
• change name of untitled option on special section to notitle
• allow the title of any section to be hidden using the notitle option
• allow imported PDF page to be referenced in TOC by enclosing in parent section with notitle option (#1213)
• allow entry for preface to be added to TOC without adding title to body using the notitle option on the preface section (#1786)
• automatically promote the notitle option from the first block in the premable to preface section; restore lead role on opening paragraph (#1786)

Improvements

• change "icon" to "icon image" in warning about missing admonition icon image
• report admonition type in warning about missing implicit admonition icon image

Bug Fixes

• set the base font of the front cover image is a PDF and the title page is not active (#2092)
• pass through warnings in background SVG to logger (#1940)
• keep closing quote with trailing ellipsis in text enclosed in typographic quotes (#321)
• collapse space in front of hidden index term (#2061)
• delete dests on page before deleting it (keeps generated PDF clean of obsolete destinations)
• don't call arrange_section if section title is hidden
• remove theme_font enclosure around call to start_new_chapter and start_new_part
• change layout_ method prefix to inscribe_ in converter (#2099)

Release meta

Released on: 2022-04-28
Released by: @mojavelinux
Release beer: Hop Zombie Red IPA by Lone Tree Brewing

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v2.0.0 Alpha 1

I'm not even sure where to begin with summarizing this release, which has been in the works for well over two years. While still based on the same technology (Prawn), this release is a drastic improvement over the previous release line (thanks to some clever ingenuity and pure grit). I suppose I should start with the fact that the number of tests increased by almost 1,000 (from 1,032 to 1,890), which now cover 99.5% of the code. You can imagine those increases teased out a lot of bugs, which is reflected in the lengthy CHANGELOG and the 150 resolved issues.

Apart from a plethora of bug fixes, the flagship enhancements this release brings are that blocks are breakable by default, all blocks are arranged using the same logic, extra margin is not added below the last block of a parent, and the theming system is much more comprehensive.

IMPORTANT: You no longer need to declare a dependency on the upstream of the prawn-table gem in your Gemfile. The patch for prawn-table has been moved into Asciidoctor PDF, so you can use the version of prawn-table that is pulled in as a transitive dependency.

Reworking how blocks are arranged was the primary issue that was holding up this release. Previously, when the converter needed to know the boundaries of a block, it would render the block in a scratch document and return its height. This approach had several key flaws. First, the height in the scratch documented didn't always line up with the height of the block when rendered in the primary document, so the border and background would be off. The process also required that blocks be unbreakable by default in order to work reliably. And it didn't account for orphaned block titles. The logic has been completely rewritten to compute the extent of the block (start and end cursor) with intelligent positioning using multiple passes in order to get an accurate measure of the where the block begins and ends. As part of that change, blocks no longer need to be unbreakable, and thus have been changed to be breakable by default. The new logic also ensures that if no content is written on the first page, or only the block title fits, the block will automatically be advanced to the next page (regardless of whether the block is breakable). You can read more about the requirements and design behind this change in #2003 and #2004 (and the batch of related issues resolved by those issues).

As part of the new arrange block logic, the open block now serves as a generic container for keeping chunks of content together that don't themselves support the unbreakable option. And while tables now support the unbreakable option, this is the mechanism used behind the scenes to achieve that behavior.

Another big enhancement that was holding up the release was an overhaul of margin handling. In previous releases, the converter would add a bottom margin to the last block inside of another block or list. There were some hacks in place to minimize this quirk, but many edge cases still slipped through. The margin handling has been rewritten so that the bottom margin is only added to a block if it is followed by another block within the same enclosure (such as inside a sidebar). Top margins have been dropped and all margins are defined from the bottom edge of the block. With this new logic in place, you should no longer expect to see gaps at the bottom of content, and it drastically simplifies both the theme and the converter code.

For those who've been waiting for it, you can now apply a role defined in a theme to a paragraph. The role can be used to control the font properties, text alignment, and text transform. Speaking of the theme, there are many new categories and keys, and several have been renamed for consistency. There are also several new built-in themes for producing print-optimized PDFs and for replacing the bundle serif font (Noto Serif) with the equivalent sans font. Consult the theming guide for details.

On the compliance front, Asciidoctor PDF 2 will require Ruby 2.7 and JRuby 9.2 at a minimum.

Last but not least, during this development cycle, the docs for Asciidoctor moved to https://docs.asciidoctor.org. Thanks to the work by Sarah, the docs for Asciidoctor PDF are being migrated to join the family.

We do not anticipate having many alpha releases or a long prerelease cycle. We're going to give users a chance to try this release so we can uncover any unexpected regressions, errors, or problem areas. If they come up, we will try to address them quickly so that we can turn around a final release in a few weeks.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Enhancements

• make delimited blocks breakable by default; require the unbreakable option on the block to retain the previous "keep together" behavior (#2004, #578, #509, #240)
• add support for the %unbreakable option on a table to prevent it from being split across pages (#2022, #871, #819, #331)
• add support for the %breakable option on a table (special case) to keep the caption and ID with the start of the table (#2022, #993)
• implement smart bottom margins on blocks to prevent extra space below blocks, particularly nested blocks (#1515, #1513, #1845)
• drop support for top-margin key on block and prose categories in theme; space between delimited blocks and lists now controlled using bottom margins only (#1515)
• allow location of anchor for block to be positioned relative to content using block-anchor-top key in theme (#2013)
• allow page numbering and running content to start after first page of a document without a title page by assigning an integer to the respective start_at theme key (#1644)
• allow page numbering and running content to start after toc (wherever it's placed) by assigning the keyword after-toc to the respective start_at theme key (#1763)
• allow theme to configure page numbering to start at cover (#1727)
• allow the front and back cover images to be defined in the theme (#1584)
• allow the front and back cover images to be specified as a data URI (#1584)
• allow theme to control margin and content margin of running content per periphery (header or footer) and per side (recto or verso) (#994)
• allow theme to control border style of delimited blocks (example, sidebar, code, admonition, verse, quote) (#1586)
• allow theme to control font color of first line of abstract using abstract-first-line-font-color key
• allow theme to control background color and border offset (only for background) of links (#1705)
• support custom role on paragraph to allow theme to control font properties (#483)
• change lead category in theme to built-in role named lead (#2031)
• allow theme to control line height of blocks using line-height property where font properties are accepted (#2032)
• don't render index section if index is empty (i.e., there are no index entries)
• allow title of special section to be hidden by setting untitled option on section
• stabilize font paths in built-in themes by prefixing paths with GEM_FONTS_DIR (#1568)
• assign page-layout attribute in running content so it can be used to select a background per layout (#1570)
• reset numbering of footnotes in each chapter (#1639)
• add chapter xreftext to label of footnote reference that refers to previous chapter (#1639)
• add support for assigning the same font file to all font variants (i.e., styles) using the wildcard key (*) (#1588)
• bundle Noto Sans in addition to Noto Serif and add built-in theme sans-with-fallback-font (#2010)
• allow caption max-width to be set to percentage of content by passing argument to fit-content function (#1494)
• allow theme to control text alignment of caption independent of box alignment (#1493)
• set chapter-numeral attribute in running content on pages in chapter if sectnums attribute is set (#1373)
• set part-numeral attribute in running content on pages in part if partnums attribute is set (#1373)
• add support for normal_italic font style (to reset font style to normal, then apply italic) (#1603)
• honor text alignment roles (e.g., text-left) or list-text-align theme key on callout lists
• honor text alignment roles (e.g., text-center) on block image (#1609)
• honor role and inherited role on inline image (#1939, #1376)
• disable running header and/or footer on toc pages if noheader and/or nofooter option is set on toc macro (#1378)
• add support for preamble toc placement
• only insert macro toc at location of first toc macro
• ignore requested pages not found in imported PDF (#1616)
• disable document outline if outline document attribute is unset (#1619)
• keep temporary artifacts (for debugging) if KEEP_ARTIFACTS env var is set
• define a dest name "toc" at the top of the default toc location
• normalize space characters in authors content and drop lines with unresolved attribute references (#1642)
• skip image block with missing image if computed alt text resolves to empty string (#1645)
• custom theme does not inherit from base theme by default; must be specified explicitly using extends: base (#1640)
• allow theme to configure number of index columns using index_columns key (#1663)
• configure AsciiDoc table cell to inherit font properties from table and scale font size of nested blocks (#926)
• scale font size of literal table cell (#1696)
• add support for id attribute on link macro
• add support for link attribute on icon macro (#1915)
• allow theme to configure width of block border on ends separate from sides (#1693)
• add additional glyphs to built-in fonts (heavy checkmark to fallback font; both checkmarks to monospaced font; numero sign to prose and fallback fonts) (#1625)
• allow theme to specify text decoration style, color, and width for captions (globally)
• allow admonition icon image to be remote (if allow-uri-read is set) or data URI (#1...

v1.6.2

Summary

This is a patch release for the v1.6.x line to fix a regression introduced by upgrading Prawn and to backport the feature to control when the link URI is shown using the show-link-uri attribute.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Enhancements

• show URL of link for any media type when show-link-uri is set (#951)
• do not show URL of link when media type is screen or prepress when show-link-uri is unset (#951)

Bug Fixes

• update patches for PDF::Core.real and PDF::Core.real_params to prevent scientific notation ending up in PDF (#1983) (@rillbert)

Release meta

Released on: 2021-12-31
Released by: @mojavelinux
Release beer: Hop Excavator by Our Mutual Friend

Logs: full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v1.6.1

Summary

This is a bug fix release for the v1.6.x line to fix a regression introduced into Prawn by a change in Ruby 3. It also includes a backport of the footnotes alignment from the v2.0.x line.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Enhancements

• align footnotes block to the bottom of the page it is placed on (#1833)

Bug Fixes

• don't strip leading null character from fragment text when arranging lines when running on Ruby 3 (#1963)

Release meta

Released on: 2021-05-10
Released by: @mojavelinux
Release beer: Dragon's Milk Reserve by New Holland Brewing

Logs: full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v1.6.0

Summary

This is special major release of Asciidoctor PDF before transitioning to semantic versioning. The purpose of this release is to make Asciidoctor PDF compatible with Ruby 3 (in advance of the Asciidoctor PDF 2.0.0 release). As part of that upgrade, this release drops support for Ruby < 2.5 (which also means JRuby < 9.2). It also drops support for Asciidoctor < 2. In order to get the full CI matrix running, support for controlling the location of the gs command using the GS environment variable was backported to this release. As part of removing patches to support Ruby < 2.5, the fix to not hyphenate a hyphen was also backported.

The Asciidoctor PDF 1.5.x release line does not work on Ruby 3 because the version of Prawn it depends on cannot be installed on Ruby 3. And it's not possible to upgrade Prawn in that release line since newer versions of Prawn dropped support for Ruby < 2.5. Since that upgrade constitutes a major breaking change, we've decided to create a 1.6.x release line. Since Asciidoctor PDF isn't yet using semantic versioning, this is considered a major release.

As part of upgrading Prawn, this release also upgrades prawn-svg, prawn-icon, and ttfunk. Those upgrades bring in additional enhancements. For example, the ttfunk upgrade adds partial support for OTF fonts. The prawn-svg upgrade adds support for loading embedded images from a data URI. And the prawn-icon upgrade brings in a newer version of Font Awesome (5.15.1).

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Enhancements

• allow path of ghostscript command to be controlled using GS env var (#1791)

Bug Fixes

• do not hyphenate a hyphen when hyphenation is enabled (#1562)

Compliance

• add support for Ruby 3 and drop support for Ruby < 2.5 and JRuby < 9.2 (#1681)
• upgrade to Prawn 2.4.0 (adds support for Ruby 3)
• upgrade to prawn-svg 0.32 (adds support for Ruby 3 without a patch and for loading embedded images from a data URI)
• upgrade to prawn-icon 3.0.x
• release lock on ttfunk version (1.6 produces slightly different output from 1.5 for certain missing glyphs)
• drop support for Asciidoctor < 2 (#1552)

Build / Infrastructure

• run tests against pygments.rb 2.x in addition to pygments.rb 1.2.0

Release meta

Released on: 2021-05-10
Released by: @mojavelinux
Release beer: Sun Reaper by Toppling Goliath

Logs: full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v1.5.4

Summary

Thanks to community feedback and testing, we bring you yet another bug fix release. The most significant fix in this release is to restore compatibility with the latest Asciidoctor 2.0 release when using Pygments. A regression was fixed to keep the caption with the block image when the image is scaled down to fit on the page. Images in the theme are now resolved correctly when theme is loaded from classloader when using JRuby. And it's now possible to control the font family used for conums inside a verbatim block. This release also brings a minor release upgrade for prawn-svg. There are additional fixes you can find listed in the CHANGELOG.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Bug Fixes

• restore compatiblity with Asciidoctor 2.0.12 when using Pygments (#1846)
• fix numeric assertions in test suite (#1542)
• keep caption with image when image is scaled down to fit page (#1803)
• prevent inline image from rendering multiple times if fallback font is used for alt text (#1858)
• disable cache tests if open-uri-cache gem is not available
• disable hyphen tests if text-hyphen gem is not available
• compensate for change in how character_spacing is applied in FontMetricCache#width_of after Prawn 2.2.2
• allow inline image to be enclosed in link macro (alt text was breaking parsing)
• use oembed API over HTTPS to get thumbnail for Vimeo video
• use conum font family defined in theme for conum in verbatim block (#1611)
• patch float precision constant so prawn-table does not fail to arrange cells that span columns (#1835)
• resolve images in theme correctly when theme is loaded from classloader (JRuby only) (#1829)

Compliance

• upgrade to prawn-svg 0.31 (adds support for loading embedded images from a data URI) (#1810)

Build / Infrastructure

• migrate Linux CI jobs to GitHub Actions

Release meta

Released on: 2021-01-09
Released by: @mojavelinux
Release beer: D.O.R.I.S. the Detroyer by Hoppin' Frog

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v1.5.3

Summary

Thanks to community feedback and testing, we bring you yet another bug fix release. First, it fixes a crash when the text transform is applied to the heading cell in the table body. It also removes the extra hyphen when hyphenation is enabled and a hyphen appears at the end of the line. And finally, it looks in the correct font, honoring the font style, when trying to find which font provides the glyph. Finally, if the format of an image is unsupported, and prawn-gmagick has already been loaded, the log message will not suggest installing it. And that's it!

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Bug Fixes

• do not hyphen a hyphen when hyphenation is enabled (#1562)
• fix crash when applying text transform to heading cell in table body (#1575)
• honor font style when looking for glyph in font
• only suggest installing prawn-gmagick gem if not loaded (#1578)

Release meta

Released on: 2020-02-28
Released by: @mojavelinux
Release beer: Orange Tango Jam by Alternation Brewing

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v1.5.2

Summary

This release fixes just two bugs. First, it ensures that all images are properly closed after reading and that temporary image files are always cleaned up (which fixes several warnings on Windows). Second, it fixes the crash when the btn or kbd macros are used in a section title. And that's it!

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Bug Fixes

• fix crash if btn or kbd macro is used in section title (#1563)
• ensure background and admonition icon image files are closed after being read (#1566)
• ensure temporary images generated by running content are cleaned up (#1566)

Release meta

Released on: 2019-02-21
Released by: @mojavelinux
Release beer: Monkey's Wedding by Resolute Brewing

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v1.5.1

Summary

Work has started on Asciidoctor PDF 2. While that happens, we'll roll bugs fixes and minor enhancements into the 1.5.x line. This release is the first in that series. It fixes the line spacing between the first and second lines of an indented paragraph as well as the abstract. In order to test it properly, we needed to add support for changing the font color of the first line of the abstract. The first-line category for the abstract is now documented in the theming guide. One lingering reference to the Pdf module was renamed to PDF. And that's it!

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Enhancements

• allow theme to control font color of first line of abstract

Fixes

• fix spacing after first line of indented paragraph (#1557)

Release meta

Released on: 2019-02-16
Released by: @mojavelinux
Release beer: Monkey's Wedding by Resolute Brewing

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v1.5.0

Summary

This is it! You can finally install the Asciidoctor PDF gem without the --pre flag. What made us decide it's ready? Perhaps it's the 1,000 tests in the test suite. Perhaps it's the 900 resolved issues. Perhaps because it's the 30th release in the project history. Or perhaps, it was just time ;)

This release brings with it several notable improvements and bug fixes since the last candidate release. Feature-wise, there's now broader support for using a data URI target as the image target (i.e., background image and running content image), the page mode can be fully configured using the pdf-page-mode attribute or page_mode theme key, the front and back cover can be set to a blank page, a pass block will render as a literal block, and if a table has multiple header rows (which must be configured using an extension), those rows will act like header rows (i.e., styled appropriately and repeated on subsequent pages). In the bug fix category, the processor won't crash if the document has a PDF cover page and SVG page background, the background and border will be drawn around the entire block in an AsciiDoc table cell, the character spacing in an inline SVG won't be altered by the image placeholder, and the processor will only warn once per missing character per font.

Consult the CHANGELOG for this release, as well as previous releases, for a full picture of what has changed recently.

Next steps

Following this release, Asciidoctor PDF will adhere to semantic versioning and only support versions of Ruby that themselves are in an active cycle. The Asciidoctor PDF 2.0.0 release will mostly be the same as this one, though will swap a few default settings that could affect compatibility.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

• support table with multiple head rows & decorate accordingly (#1539)
• draw background and border around entire delimited block with wrapped text that appears inside an AsciiDoc table cell (#820)
• fix crash when document has PDF cover page and SVG page background (#1546)
• allow page mode to be fully configured using pdf-page-mode attribute or page_mode theme key (#840)
• allow background image to be specified using a data URI
• allow running content image to be specified using a data URI
• support creating empty front or back cover by assigning empty value to front-cover-image or back-cover-image attribute
• only warn once per missing character (#1545)
• render pass block as listing block, using raw source as contents
• prevent image placeholder from altering character spacing in inline SVG (#1550)

Release meta

Released on: 2019-02-11
Released by: @mojavelinux
Release beer: Black IPA by Bent Barley

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.