Summary
After many years, Asciidoctor PDF is finally ready to exit alpha status. The simple reason? Tests. Asciidoctor PDF now has over 300 tests in its arsenal to make it resilient against bugs and regressions as changes are made to the code base. While there's always room for more tests, this suite gives us plenty of confidence to enter beta.
The transition from alpha to beta also brought a slew of bug fixes, enhancements, and minor improvements. First and foremost, the running header works again (now with tests!). It's possible to size and position cover page images, background images, and images in the running content using the pdfwidth, cover, and position attributes on the image macro. Since the image position can now be controlled, we changed the default to center (vertical and horizontal). SVGs won't go fetching remote images unless the allow-uri-read document attribute is set via the API. There have been quite a number of new knobs and switches added to the theme. And speaking of the theme, we decided to fix the terminology and rename pdf-style and pdf-stylesdir to pdf-theme and pdf-themesdir, respectively (don't worry, though, the old names still work too). And if pdf-theme is a path, and pdf-themesdir is not set, the pdf-themesdir is set automatically. You can now find a custom theme for the chronicles example that you can use as a reference. If you a working with different page layouts in a single document, the running content will now keep up!
Deprecation notices:
- The legacy keys for the running content have been removed. Refer to the theming guide for the current schema.
- The pdf-style and pdf-stylesdir attribute have been renamed to pdf-theme and pdf-themesdir, respectively (though the old names still work too).
- The fallback font has been removed from the default theme (since it really slows down Prawn). Set pdf-theme=default-with-fallback-font to restore previous behavior (or define a fallback font in your own theme).
- The cover images and page background images are now centered by default and resized proportionally to fit the boundaries of the page. Use the pdfwidth (or fit) and position attributes on the image macro to customize this behavior.
- Remote images referenced in an SVG will only be fetched if the allow-uri-read attribute is set via the Asciidoctor API or CLI.
- The text-alignment attribute has been renamed to text-align.
Consult the CHANGELOG for a full list of changes.
Distribution
Changelog
- rename pdf-style and pdf-stylesdir attributes to pdf-theme and pdf-themesdir, respectively (while still honoring the old names for compatibility) (#1127)
- don't load fallback font by default; move fallback font to default-with-fallback-font theme
- apply cell padding to table cells in the head row (#1098)
- allow the theme to control the padding of table cells in the head row using the table_head_cell_padding key (#1098)
- fix position of table caption for reduced-width tables when caption align is center (#1138)
- adjust width of table caption to match width of table unless table_caption_max_width is none in theme (#1138)
- fix position of text in running header (#1087)
- ignore start attribute on ordered list if marker is disabled
- allow start value to be negative for ordered lists that use arabic or roman numbering (#498)
- don't convert values in theme which are not color keys to a string (#1089)
- apply page layout specified on page break even when break falls page boundary (#1091)
- scale SVG background image to fit page in the same way raster image is scaled (#765)
- allow page background size to be controlled using image macro attributes (#1117)
- allow page background image position to be controlled using position attribute on image macro (#1124)
- add support for fit=cover for cover page, page background, and running content images (#1136)
- change default background image position to center (#1124)
- allow cover image position to be controlled using position attribute on image macro (#1134)
- change default cover image position to center (#1134)
- set enable_file_requests_with_root and enable_web_requests options for all SVGs (#683)
- automatically set pdf-stylesdir if pdf-style ends with .yml and pdf-stylesdir is not specified (#1126)
- replace hyphens with underscores in top-level theme keys
- allow hyphens to be used in variable references in theme (#1122)
- allow theme to control background and border of inline code (literal) (#306)
- NOTE: The border will not work correctly if the phrase has nested formatting
- allow theme to control background and border of inline button (#451)
- resolve null color value in theme to nil (aka not set)
- add support for cgi-style options on source language when syntax highlighting with Rouge (#1102)
- apply custom theme to chronicles example to customize running content and demonstrate how to extend default theme
- drop remapping of legacy running content keys in theme data
- resize running content to fit page layout (#1036)
- exclude border width from running content area (#1109)
- support text-transform property in running content (#702)
- make depth of section titles assigned to section-title attribute in running content configurable (#1141)
- support width attribute on image in running content if no other dimension attribute is specified
- apply correct scale-down logic to image in running content
- allow image format to be specified using format attribute (cover page image, page background image, running content image) (#1132)
- allow theme to set bottom border properties (color, style, and width) of table head row (#770)
- allow column rule and spacing to be specified for running content when multiple columns are specified (#1093)
- never load base theme when loading default theme; otherwise load base theme if extends isn't specified, but only if theme data hasn't been initialized
- shorten text-alignment attribute to text-align
- set PDF version to 1.4 by default (#302)
- allow PDF version to be set using pdf-version document attribute (#302)
Release meta
Released on: 2019-07-08
Released by: @mojavelinux
Release beer: Piggie Smalls Wee Heavy by Resolute Brewing Company
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.