asciidoctor/asciidoctor v1.5.7 on GitHub

This release was made possible by support from our Change Maker sponsor, Okta.

Summary

Continuing with the Asciidoctor tradition of major patch releases, this release resolves over 100 issues. As impressive as that sounds, it's time to break with this tradition. Starting with the next major release (v2.0.0), Asciidoctor will switch to semantic versioning (SemVer). By adopting SemVer, fixes can be released sooner and the version number will reflect the impact of the changes being introduced. The next major release will also drop support for versions of Ruby that are no longer maintained (which includes Ruby 1.8.7 through 2.1 or 2.2).

Now on to what's new and noteworthy...

The most significant change in this release is that all warning and error messages are now routed through a logger (finally!). Many of the messages also include context about the source location (file, dir, path, lineno), which can be useful for integrations and tooling. You can even force the CLI to exit with a non-successful exit code if the messages reach the threshold specified using the --failure-level option. When using the API, you can feed your own logger to the LoggerManager to capture, route, or observe the messages.

Good log messages demand good line number tracking. In this release, the line numbers reporting is much more accurate, especially for lists and tables. When reported, line numbers will be within a single line of the source of the problem.

Section ID generation has been enhanced. XML tags are now dropped from a section title before an ID is generated from it, and character references and non-word characters (except hyphens, dots, and spaces) are dropped instead of being replaced with the idseparator character. This behavior is more compatible with other systems (i.e., GitHub) and produces nicer IDs. But there's a chance that auto-generated IDs you're relying on will change, so please be sure to check.

Other notable changes include numbering of parts when partnums is set (including xref text when using xrefstyle), cataloging and validating inline anchors at the start of a list item or table cell, consolidation of the footnote and footnoteref macros into the footnote macro, allowing table stripes to be controlled using the stripes attribute, support for soft unsetting an attribute from the API or CLI using name!@, allowing the soft set modifier to be placed at the end of the attribute name instead of its value (e.g., icons@=font), intelligent parsing of text as attributes in the xref and link macros, hard line breaks in AsciiMath equations, allowing the position of section anchors to be configured, adding source location information to additional nodes when the sourcemap option is specified, allowing a block title to begin with a period, and support for shadow man pages. To get a full list of what changed, consult out the changelog below.

This release also launched a bright new logo for the project. Thanks to @mmajko, @graphitefriction, and @Mogztter for helping to turn ideas into action and producing a set of logos. You can find the logo files in the brand repository.

Work has also begun on a new documentation portal for Asciidoctor based on Antora. This new site will include documentation for the AsciiDoc language, the Asciidoctor processor, and other components in the Asciidoctor ecosystem.

Distributions

RubyGem (asciidoctor)

Asciidoctor is also packaged for Fedora, Debian, Ubuntu, Alpine Linux, OpenSUSE, and Homebrew. Please use the system's package manager to install the package named asciidoctor.

Release meta

Released on: 2018-05-01
Released by: @mojavelinux
Release beer: Barrel Aged Ten Fidy

Logs: resolved issues | full diff

Credits

This release cycle welcomed in our first Change Maker sponsor, Okta. We'd like to take this opportunity to thank Okta, as well as our other awesome sponsors, without whose support Asciidoctor would not be possible. Thank you sponsors for your dedication to improving the state of technical documentation!

If you'd like to support this project, you can become a sponsor on OpenCollective or BountySource (Salt). This support provides critical funding for the ongoing development of the project.

Thanks to the following people who contributed ideas, code, or documentation to this release:

@Mogztter, @graphitefriction, @aerostitch, @tiwai, @dimztimz, @bk2204, @PauloFrancaLacerda, @seikichi, @akosma, @ahus1, @flashcode, @mmajko, @miltador, @errier, @vivien, @wotsushi, @sindzicat, @zmwangx, @aokiplayer, @chickenkiller, @mareknovotny, and @huiyifyj.

Changelog

Enhancements

BREAKING: drop XML tags, character refs, and non-word characters (except hyphen, dot, and space) when auto-generating section IDs (#794)
- hyphen, dot, and space are replaced with value of idseparator, if set; otherwise, spaces are dropped
BREAKING: disable interdocument xrefs in compat mode (#2740)
pass non-AsciiDoc file extensions in target of xref through unprocessed (#2740)
process any known AsciiDoc file extension in target of shorthand interdocument xref if hash is also present (e.g., <<target.asciidoc#,text>>) (#2740)
only allow .adoc to be used in target of formal xref macro to create an interdocument xref (with or without a hash) (#2740)
allow attribute names to contain any word character defined by Unicode (#2376, PR #2393)
do not recognize attribute entry line if name contains a colon (PR #2377)
route all processor messages through a logger instead of using Kernel#warn (#44, PR #2660)
add MemoryLogger for capturing messages sent to logger into memory (#44, PR #2660)
add NullLogger to prevent messages from being logged (#44, PR #2660)
log message containing source location / cursor as an object; provides more context (#44, PR #2660)
pass cursor for include file to :include_location key in message context (PR #2729)
add :logger option to API to set logger instance (#44, PR #2660)
add --failure-level=LEVEL option to CLI to force non-zero exit code if specified logging level is reached (#2003, PR #2674)
parse text of xref macro as attributes if attribute signature found (equal sign) (#2381)
allow xrefstyle to be specified per xref by assigning the xrefstyle attribute on the xref macro (#2365)
recognize target with .adoc extension in xref macro as an interdocument xref
resolve nested includes in remote documents relative to URI (#2506, PR #2511)
support !name@ (preferred), !name=@, name!@, and name!=@ syntax to soft unset attribute from API or CLI (#642, PR #2649)
allow modifier to be placed at end of name to soft set an attribute (e.g., icons@=font) (#642, PR #2649)
interpret false attribute value defined using API as a soft unset (#642, PR #2649)
number parts if partnums attribute is set (#2298)
allow footnote macro to define or reference footnote reference (footnoteref macro now deprecated) (#2347, PR #2362)
allow custom converter to be used with custom templates; converter must declare that it supports templates (#2619)
allow manpage path for manpage help topic to be specified using ASCIIDOCTOR_MANPAGE_PATH environment variable (PR #2653) (@aerostitch)
if manpage cannot be found in default path inside gem, use man -w asciidoctor to resolve installed path (PR #2653)
uncompress contents of manpage for manpage help topic if path ends with .gz (PR #2653) (@aerostitch)
define source and manual refmiscinfo entries in manpage output if manual and source attributes are defined (PR #2636) (@tiwai)
add syntax for adding hard line breaks in block AsciiMath equations (#2497, PR #2579) (@dimztimz)
add positioning option to sectanchors attribute (sectanchors=before or sectanchors=after) (#2485, PR #2486)
allow table striping to be configured using the stripes attribute (even, odd, all, or none) or stripes roles on table (#1365, PR #2588)
add rel=nofollow property to links (text or image) when nofollow option is set (#2605, PR #2692)
populate Document#source_location when sourcemap option is enabled (#2478, PR #2488)
populate source_location property on list items when sourcemap option is set on document (PR #2069) (@Mogztter)
populate Table::Cell#source_location when sourcemap option is enabled (#2705)
allow local include to be flagged as optional by setting optional option (#2389, PR #2413)
allow block title to begin with a period (#2358, PR #2359)
catalog inline anchor at start of list items in ordered and unordered lists, description list terms, and table cells (#2257)
register document in catalog if id is set; assign reftext to document attributes if specified in a block attribute line (#2301, PR #2428)
allow automatic width to be applied to individual columns in a table using the special value ~ (#1844)
use the quote element in DocBook converter to represent smart quotes (#2272, PR #2356) (@bk2204)
parse and pass all manpage names to output document master (i.e., shadow man pages) (#1811, #2543, PR #2414)
parse credit line of shorthand quote block as block attributes; apply normal subs to credit line in shorthand quote blocks (#1667, PR #2452)
populate copyright element in DocBook output from value of copyright attribute (#2728)
preserve directories if source dir and destination dir are set (#1394, PR #2421)
allow linkcss to be unset from API or CLI when safe mode is secure
convert quote to epigraph element in DocBook output if block has epigraph role (#1195, PR #2664) (@bk2204)
number special sections in addition to regular sections when sectnums=all (#661, PR #2463)
upgrade to Font Awesome 4.7.0 (#2569)
upgrade to MathJax 4.7.4 (#2190)

Bug fixes

set :to_dir option value correctly when output file is specified (#2382)
preserve leading indentation in contents of AsciiDoc table cell if contents starts with a newline (#2712)
the shorthand syntax on the style to set block attributes (id, roles, options) no longer resets block style (#2174)
match include tags anywhere on line as long as offset by word boundary on left and space or newline on right (#2369, PR #2683)
warn if an include tag specified in the include directive is unclosed in the included file (#2361, PR #2696)
use correct parse mode when parsing blocks attached to list item (#1926)
fix typo in gemspec that removed README and CONTRIBUTING files from the generated gem (PR #2650) (@aerostitch)
preserve id, role, title, and reftext on open block when converting to DocBook; wrap in <para> or <formalpara> (#2276)
don't turn bare URI scheme (no host) into a link (#2609, PR #2611)
don't convert inter-document xref to internal anchor unless entire target file is included into current file (#2200)
fix em dash replacement in manpage converter (#2604, PR #2607)
don't output e-mail address twice when replacing bare e-mail address in manpage output (#2654, PR #2665)
use alternate macro for monospaced text in manpage output to not conflict w/ AsciiDoc macros (#2751)
enforce that absolute start path passed to PathResolver#system_path is inside of jail path (#2642, PR #2644)
fix behavior of PathResolver#descends_from? when base path equals / (#2642, PR #2644)
automatically recover if start path passed to PathResolver#system_path is outside of jail path (#2642, PR #2644)
re-enable left justification after invoking tmac URL macro (#2400, PR #2409)
don't report warning about same level 0 section multiple times (#2572)
record timings when calling convert and write on Document (#2574, PR #2575)
duplicate header attributes when restoring; allows header attributes to be restored an arbitrary number of times (#2567, PR #2570)
propagate :catalog_assets option to nested document (#2564, PR #2565)
preserve newlines in quoted CSV data (#2041)
allow opening quote around quoted CSV field to be on a line by itself
output table footer after body rows (#2556, PR #2566) (@PauloFrancaLacerda)
move @page outside of @media print in default stylesheet (#2531, PR #2532)
don't throw exception if text of dd node is nil (#2529, PR #2530)
don't double escape ampersand in manpage output (#2525) (@dimztimz)
fix crash when author_1 attribute is assigned directly (#2481, PR #2487)
fix CSS for highlighted source block inside colist (#2474, PR #2490)
don't append file extension to data uri of admonition icon (#2465, PR #2466)
fix race condition in Helpers.mkdir_p (#2457, PR #2458)
correctly process nested passthrough inside unconstrained monospaced (#2442, PR #2443)
add test to ensure ampersand in author line is not double escaped (#2439, PR #2440)
prevent footnote ID from clashing with auto-generated footnote IDs (#2019)
fix alignment of icons in footnote (#2415, PR #2416)
add graceful fallback if pygments.rb fails to return a value (#2341, PR #2342)
escape specialchars in source if pygments fails to highlight (#2341)
do not recognize attribute entry line if name contains colon (PR #2377)
allow flow indexterm to be enclosed in round brackets (#2363, PR #2364)
set outfilesuffix to match file extension of output file (#2258, PR #2367)
add block title to dlist in manpage output (#1611, PR #2434)
scale text to 80% in print styles (#1484, PR #2576)
fix alignment of abstract title when using default stylesheet (PR #2732)
only set nowrap style on table caption for auto-width table (#2392)
output non-breaking space for man manual if absent in DocBook output (PR #2636)
don't crash if stem type is not recognized (instead, fallback to asciimath)

Improvements / Refactoring

BREAKING: rename table spread role to stretch (#2589, PR #2591)
use cursor marks to track lines more accurately; record cursor at the start of each block, list item, or table cell (PR #2701, PR #2547) (@seikichi)
log a warning message if an unterminated delimited block is detected (#1133, PR #2612)
log a warning when nested section is found inside special section that doesn't support nested sections (#2433, PR #2672)
read files in binary mode to disable automatic endline coercion (then explicitly coerce to UTF-8) (PR #2583, PR #2694)
resolve / expand parent references in start path passed to PathResolver#system_path (#2642, PR #2644)
update PathResolver#expand_path to resolve parent references (#2642, PR #2644)
allow start path passed to PathResolver#system_path to be outside jail if target brings resolved path back inside jail (#2642, PR #2644)
don't run File.expand_path on Dir.pwd (assume Dir.pwd is absolute) (#2642, PR #2644)
posixify working_dir passed to PathResolver constructor if absolute (#2642, PR #2644)
optimize detection for footnote* and indexterm* macros (#2347, PR #2362)
log a warning if a footnote reference cannot be resolved (#2669)
set logger level to DEBUG when verbose is enabled
coerce value of :template_dirs option to an Array (PR #2621)
make block roles specified using shorthand syntax additive (#2174)
allow paragraph to masquerade as open block (PR #2412)
move callouts into document catalog (PR #2394)
document ID defined in block attribute line takes precedence over ID defined inside document title line
don't look for link and window attributes on document when resolving these attributes for an image
when linkattrs is set, only parse attributes in link macro if equals is present
skip line comments in name section of manpage (#2584, PR #2585)
always activate extension registry passed to processor (PR #2379)
skip extension registry activation if no groups are registered (PR #2373)
don't apply lead styling to first paragraph if role is present (#2624, PR #2625)
raise clearer exception when extension class cannot be resolved (#2622, PR #2623)
add methods to read results from timings (#2578, PR #2580)
collapse bottom margin of last block in AsciiDoc table cell (#2568, PR #2593)
set authorcount to 0 if there are no authors (#2519, PR #2520)
validate fragment of interdoc xref that resolves to current doc (#2448, PR #2449)
put id attribute on tag around phrase instead of preceding anchor (#2445, PR #2446)
alias Document#title method to no args Document#doctitle method (#2429, PR #2432)
upgrade missing or unreadable include file to an error (#2424, PR #2426)
add compliance setting to disable natural cross references (#2405, PR #2460)
make hash in inter-document xref target optional if target has extension (#2404, PR #2406)
only append output file extension to interdocument xref if file extension of target is empty or a known AsciiDoc extension (#2404, PR #2406)
add CSS class to part that matches role (#2401, PR #2402)
add fit-content class to auto-width table (#2392)
automatically assign parent reference when adding node to parent (#2398, PR #2403)
leave inline anchor in section title as is if section has ID (#2243, PR #2427)
align and improve error message about invalid use of partintro between HTML5 and DocBook converters
rephrase warning when level 0 sections are found and the doctype is not book
report correct line number when duplicate bibliography anchor is found
only warn if thread_safe gem is missing when using built-in template cache
drop deprecated compact option from CLI; remove from manpage
use more robust mechanism for lazy loading the asciimath gem
use consistent phrase to indicate the processor is automatically recovering from a problem
change Reader#skip_comment_lines to not return skipped lines
add styles to default stylesheet for display on Kindle (kf8) devices (PR #2475)
purge render method from test suite (except to verify alias)
make path_resolver available as property on Document
use 3-value shorthand for CSS property values in default stylesheet, where possible

Documentation

translate section-refsig into German (PR #2633) (@ahus1)
synchronize French README with English version (PR #2637) (@flashcode)

Build / Infrastructure

create an official logo for the project (#48) (@mmajko)
update Ruby versions in AppVeyor build matrix (PR #2388) (@miltador)
add mailinglist, changelog, source, and issues URI to gem spec
allow blocks and substitutions tests to be run directly
an asciidoctor formula is now available for Homebrew (@zmwangx)