github asciidoctor/asciidoctor v1.5.8


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

According to the release notes for 1.5.7, there wasn't supposed be another releases in the 1.5.x line. However, due to scheduling conflicts, the 2.0.0 release got pushed back. So this semi-major release was cut to get us back on track.

This release consists of over 50 enhancements and fixes that accumulated in the meantime, as well as a response to a CVE and several updates needed for Asciidoctor.js. Although unintentional, this release also includes a 10% boost in performance.

A huge thanks to @zelivans for throwing curveballs at the processor and uncovering numerous hard-to-catch bugs, including one which became CVE-2018-18385. Fixes for all those issues have been included in this release.

The most significant change in this release is that unordered and ordered lists can be nested to any depth. Also related to lists, it's now possible to specify auto-numbered callout numbers using <.>. And guard comments in front of callouts are preserved if font-based icons are not enabled. You can now set a starting line number for numbered source blocks when using Pygments or CodeRay for source highlighting in HTML or when converting to DocBook. Attribute references in the target of a custom block macro or the attrlist of an include directive are now replaced automatically. If the part-signifier and/or chapter-signifier attributes are set, the values of these attributes are prepended to the part and chapter title, respectively.

If you're using the API, there are several nice enhancements as well. It's now possible to short-circuit the AbstractBlock#find_by method once a match is found or you want to abort the search. The authors of the document can be retrieved neatly as an array. The imagesdir that was set at the location of an image is now recorded on the image node as well as in the catalog.

Thanks to @jwehmschulte for translating the README into German, to @mogztter for syncing the French translation, @jonasbjork for adding Swedish translations for the built-in attributes, @BojanStipic for updating the Serbian translations for the built-in attributes, and @stoeps13 for improving the Windows installation instructions. Also thanks to @junaruga for replacing the deprecated thread_safe gem integration with concurrent-ruby.

Following this release, the master branch will transition to 2.0.0 and semantic versioning (really, this time). Work will continue on the new documentation site for Asciidoctor that's based on Antora.


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-10-28
Released by: @mojavelinux
Release beer: Trappistes Rochefort 10

Logs: resolved issues | full diff


This release cycle welcomed in our first Change Maker sponsor, Okta. We want to thank Okta and our other generous sponsors, without whose support Asciidoctor would not be possible. Thank you to all our sponsors for your dedication to improving the state of technical documentation!

Thanks to the following people who contributed to this release:

@zelivans, @mogztter, @graphitefriction, @jwehmschulte, @jonasbjork, @junaruga, @owenh000, @BojanStipic, @aerostitch, @ds26gte, @diguage, @kikijiki, @ztmr, @gilgamaze, @ecki, @sometimesfood, @mperktold, @ilvetz, @pdmayoSFI, and @stoeps13.

A very special thanks to all our awesome supporters on BountySource (Salt) and OpenCollective. Their support provided critical funding for the development of this release and the ongoing development of the project.

You can support this project by becoming a sponsor on OpenCollective. For those still contributing via BountySource, we kindly ask that you switch your donations over to OpenCollective because it's a nicer system and better aligns with our values.



  • if set, add value of part-signifier and chapter-signifier attributes to part and chapter titles (#2738)
  • allow position (float) and alignment (align) to be set on video block (#2425)
  • substitute attribute references in attrlist of include directive (#2761)
  • add Document#set_header_attribute method for adding method directly to document header during parsing (#2820)
  • add helper method to extension processor classes to create lists and list items
  • allow ordered and unordered lists to be nested to an arbitrary / unlimited depth (#2854)
  • add prefer DSL method to extension registry and document processor to flag extension as preferred (#2848)
  • allow manname and manpurpose to be set using document attributes; don't look for NAME section in this case (#2810)
  • substitute attribute references in target of custom block macro (honoring attribute-missing setting) (#2839)
  • interpret <.> as an auto-numbered callout in verbatim blocks and callout lists (#2871)
  • require marker for items in callout list to have circumfix brackets (e.g., <1> instead of 1>) (#2871)
  • preserve comment guard in front of callout number in verbatim block if icons is not enabled (#1360)
  • add more conventional styles to quote block when it has the excerpt role (#2092)
  • colspecs can be separated by semi-colon instead of comma (#2798)
  • change AbstractBlock#find_by to respond to StopIteration exception; stop traversal after matching ID (#2900)
  • change AbstractBlock#find_by to honor return values :skip and :skip_children from filter block to skip node and its descendants or just its descendants, respectively (#2067)
  • add API to retrieve authors as array; use API in converters (#1042) (@mogztter)
  • add support for start attribute on source block to set starting line number when converting to DocBook (#2915)
  • track imagesdir for image on node and in catalog (#2779)
  • allow starting line number to be set using start attribute when highighting source block with Pygments or CodeRay (#1742)
  • upgrade highlight.js to 9.13.1


  • don't hang on description list item that begins with /// (#2888)
  • don't crash when using AsciiDoc table cell style on column in CSV table (#2817)
  • show friendly error if CSV data for table contains unclosed quote (#2878) (@zelivans)
  • don't crash when attribute entry continuation is used on last line of file (#2880) (@zelivans)
  • treat empty/missing value of named block attribute followed by other attributes (e.g., caption=,cols=2*) as empty string
  • AbstractNode#set_option does nothing if option is already set (PR #2778)
  • allow revnumber to be an attribute reference in revision info line (#2785)
  • use instead of ::IO.binread in Reader for Asciidoctor.js compatibility
  • add fallback for timezone when setting doctime
  • preserve UNC path that begins with a double backslash (Windows) (#2869)
  • fix formatting of quote block (indentation) in manpage output (#2792)
  • catalog inline anchors in ordered list items (#2812)
  • detect closing tag on last line with no trailing newline (#2830)
  • process !name@ attribute syntax properly; follow-up to #642
  • change document extension processor DSL methods to return registered extension instance instead of array of instances
  • use fallback value for manname-title to prevent crash in manpage converter
  • consolidate inner whitespace in prose in manpage output (#2890)
  • only apply subs to node attribute value if enclosed in single quotes (#2905)
  • don't hide URI scheme if target of link macro is a bare URI scheme
  • fix crash when child section of part is out of sequence and section numbering is enabled (#2931)
  • fix crash when restoring passthroughs if passthrough role is enclosed in single quotes (#2882, #2883)
  • don't eagerly apply subs to inline attributes in general
  • make sure encoding of output file is UTF-8
  • prevent warning about invalid :asciidoc option when using custom templates with Slim 4 (#2928)
  • use Pathname#relative_path_from to compute relative path to file outside of base directory (#2108)


  • change trailing delimiter on part number to colon (:) (#2738)
  • interpret open line range as infinite (#2914)
  • rename number property on AbstractBlock to numeral, but keep number as deprecated alias
  • use CSS class instead of hard-coded inline float style on tables and images (#2753)
  • use CSS class instead of hard-coded inline text-align style on block images (#2753)
  • allow hyphen to be used custom block macro name as long as it's not the first character (#2620)
  • use shorthands %F and %T instead of %Y-%m-%d and %H:%M:%S to format time
  • read file in binary mode whenever contents are being normalized
  • use .drop(0) to duplicate arrays (roughly 1.5x as fast as .dup)
  • only recognize a bullet glyph which is non-repeating as an unordered list marker
  • rename SyntaxDsl module to SyntaxProcessorDsl (internal)
  • fail if name given to block macro contains illegal characters
  • normalize all whitespace in value of manpurpose attribute
  • make space before callout number after custom line comment character optional
  • parse attrlist on inline passthrough as a shorthand attribute syntax or literal role (#2910)
  • add support for range syntax (.. delimiter) to highlight attribute on source block (#2918)
  • add support for unbounded range to highlight attribute on source block (#2918)
  • automatically assign title and caption on image block if title is set on custom block source (#2926)
  • use OS independent timezone (UTC or time offset) in doctime and localtime attributes (#2770)
  • report correct line number for inline anchor with id already in use (#2769)
  • generate manpage even if input is non-conforming or malformed (#1639)
  • allow authorinitials for single author to be overridden (#669)


  • translate README into German (#2829) (@jwehmschulte)
  • sync French translation of README (@mogztter)
  • add Swedish translation of built-in attributes (PR #2930) (@jonasbjork)

Build / Infrastructure

  • replace thread_safe with concurrent-ruby (PR #2822) (@junaruga)
latest releases: v2.0.16, v2.0.15, v2.0.14...
2 years ago