What’s New in 2.0

This page lists the changes made in each of the patch releases in the Asciidoctor 2.0 release line. The releases are ordered from newest to oldest.

Cumulative issues resolved: 2.0.x

Asciidoctor 2.0.11

Release date: 2020.11.02

Bug fixes

  • Fix infinite loop when callout list with obsolete syntax is found inside list item (#3472)

  • Fix infinite loop when xreftext contains a circular reference path in HTML and manpage converters (#3543)

  • Apply text formatting to table cells in implicit header row when column has the "a" or "l" style (#3760)

  • Fix errant reference warning for valid reference when running in compat mode (#3555)

  • Initialize backend traits for converter (if not previously initialized) using assigned basebackend; mimics Asciidoctor < 2 behavior (#3341)

  • Set source_location on preamble block when sourcemap option is enabled (#3799)

  • Link the notitle and showtitle attributes so they act as opposites for the same toggle (#3804)

  • Pass options to constructor of Rouge lexer instead of #lex method; restores compatibility with Rouge >= 3.4 (#3336)

  • Don’t clobber cgi-style options on language when enabling start_inline option on the Rouge PHP lexer (#3336)

  • Fix parsing of wrapped link and xref text, including when an attrlist signature is detected (#3331)

  • Restore deprecated writable number property on AbstractBlock

  • Always use title as xreftext if target block has an empty caption, regardless of xrefstyle value (#3745)

  • Allow a bibliography reference to be used inside a footnote (#3325)

  • Fix bottom margin collapsing on AsciiDoc table cell (#3370)

  • Remove excess hard line break in multi-line AsciiMath blocks (#3407)

  • Only strip trailing spaces from lines of AsciiDoc include file (#3436)

  • Remove errant optional flag in regexp for menu macro that breaks Asciidoctor.js (#3433)

  • Preserve repeating backslashes when generating manpage output (#3456)

  • Honor percentage width specified on macro of inline SVG (#3464)

  • Removing leading and trailing blank lines in AsciiDoc include file to match assumption of parser (#3470)

  • Activate extensions when :extensions option is set even if Extensions API is not yet loaded (#3570)

  • Don’t activate global extensions if :extensions option is false (#3570)

  • Escape ellipsis at start of line in manpage output (#3645) (@jnavila)

  • Don’t register footnote with ID if a footnote is already registered with that ID (#3690)

  • Honor start attribute on ordered list in manpage output (#3714)

  • Warn instead of crashing if SVG to inline is empty (#3638) (@mogztter)

  • Compute highlight line ranges on source block relative to value of start attribute (#3519) (@mogztter)

  • Prevent collapsible block from incrementing example number by assigning an empty caption (#3639)

  • Use custom init function for highlight.js to select the correct code elements (#3761)

  • Fix resolved value of :to_dir when both :to_file and :to_dir options are set to absolute paths (#3778)

  • Fix crash if value of stylesheets attribute contains a folder and the destination directory for the stylesheet does not exist (even when the :mkdirs option is set) (#3808)

  • Fix crash if value passed by API for copycss attribute is not a string (#3592)

  • Restore label in front of each bibliography entry in DocBook output that was dropped by fix for #3085 (#3782)

  • Apply max width to each top-level container instead of body in HTML output (#3513)

  • Don’t apply border-collapse: separate to HTML for table blocks; fixes double border at boundary of colspan/rowspan (#3793) (@ahus1)

  • Don’t remove right border on last table cell in row (#2563)

  • Rework table borders to leverage border collapsing (apply frame border to table, grid border to cells, and selectively override border on cells to accommodate frame) (#3387)

Compliance

  • Add support for muted option to self-hosted video (#3408)

  • Move style tag for convert-time syntax highlighters (coderay, rouge, pygments) into head (#3462)

  • Move style tag for client-side syntax highlighters (highlight.js, prettify) into head (#3503)

  • Define entry point API methods (load, convert, load_file, convert_file) as class methods instead of module_function to avoid conflict with Kernel.load (#3625)

  • Retain attribute order on HTML code tag for source block to remain consistent with output from 1.5.x (#3786)

  • Correct language code for Korean language file from kr to ko (#3807) (@jnavila)

Improvements

  • Apply word wrap (i.e., word-wrap: anywhere) to body in default stylesheet (#3544)

  • Allow nobreak and nowrap roles to be used on any inline element (#3544)

  • Add CSS class to support pre-wrap role to preserve leading, trailing, and repeating spaces in phrase (#3815)

  • Preserve guard around XML-style callout when icons are not enabled (#3319)

  • Use .fam C command to switch font family for verbatim blocks to monospaced text in manpage output (#3561)

  • Remove redundant test for halign and valign attributes on table cell in DocBook converter

  • Allow encoding of include file to be specified using encoding attribute (#3248)

  • Allow template to be used to override outline by only specifying the outline template (#3491)

  • Upgrade MathJax from 2.7.5 to 2.7.9

  • Upgrade highlight.js from 9.15.10 to 9.18.3 (note that this increases script size from 48.8 KB to 71.5 KB)

  • Skip unused default attribute assignments for embedded document

  • Allow a URL macro to have a preceding single or double quote (#3376)

  • Add support for erubi template engine; use it in place of erubis in test suite; note the use of erubis is deprecated (#3737)

  • Download and embed remote custom stylesheet if allow-uri-read is set (#3765)

  • Remove direction property from default stylesheet (#3753) (@abdnh)

  • remove max width setting on content column for print media in default stylesheet (#3802)

  • Normalize frame value "topbot" to "ends" in HTML output (consistently use frame-ends class) (#3797)

  • Add role setter method on AbstractNode (#3614)

  • Map chapter-signifier and part-signifier attributes in locale attribute files to replace chapter-label and part-label (#3817)

Build and infrastructure

  • Run test suite on TruffleRuby nightly (@mogztter, @erebor)

  • Upgrade TruffleRuby to 20.0.0 (@mogztter)

  • Trigger upstream builds for AsciidoctorJ on GitHub Actions (@robertpanzer)

Asciidoctor 2.0.10

Release date: 2019.05.31

Bug fixes

  • fix Asciidoctor.convert_file to honor header_footer: false option when writing to file (#3316)

  • fix placement of title on excerpt block (#3289)

  • always pass same options to SyntaxHighlighter#docinfo, regardless of value of location argument

  • fix signature of SyntaxHighlighter#docinfo method (#3300)

  • when icons is set to image, enable image icons, but don’t use it as the value of the icontype attribute (#3308)

Asciidoctor 2.0.9

Release date: 2019.04.30

Bug fixes

  • process multiple single-item menu macros in same line (#3279)

  • register images in catalog correctly (#3283)

  • rename AbstractNode#options method to AbstractNode#enabled_options so it doesn’t get shadowed by Document#options (#3282)

  • don’t fail to convert document if alt attribute is not set on block or inline image (typically by an extension)

  • fix lineno of source location on blocks that follow a detached list continuation (#3281)

  • assume inline image type is "image" if not set (typically by an extension)

Asciidoctor 2.0.8

Release date: 2019.04.22

Bug fixes

  • restore background color applied to literal blocks by default stylesheet (#3258)

  • use portability constants (CC_ALL, CC_ANY) in regular expressions defined in built-in converters (DocBook5 and ManPage)

  • use portability constant (CC_ANY) in regular expression for custom inline macros

  • use smarter margin collapsing for AsciiDoc table cell content; prevent passthrough content from being cut off (#3256)

  • don’t limit footnote ref to ASCII charset; allow any word character in Unicode to be used (#3269)

Improvements

  • register_for methods accept arguments as symbols (#3274)

  • use Concurrent::Map instead of Concurrent::Hash in template converter

  • use module_function keyword to define methods in Helpers

  • move regular expression definitions to separate source file (internal change)

Asciidoctor 2.0.7

Release date: 2019.04.13

Bug fixes

  • fix crash when resolving ID from text and at least one candidate contains an unresolved xref (#3254)

  • fix compatibility with Rouge 2.0

Improvements

  • improve documentation for the -a CLI option; explain that @ modifier can be placed at end of name as alternative to end of value

  • move source for main API entry points (load, load_file, convert, convert_file) to separate files (internal change)

  • define main API entry points (load, load_file, convert, convert_file) as module functions

Asciidoctor 2.0.6

Release date: 2019.04.04

Bug fixes

  • assume implicit AsciiDoc extension on interdoc xref macro target with no extension (e.g., document#); restores 1.5.x behavior (#3231)

  • don’t fail to load application if call to Dir.home fails; use a rescue with fallback values (#3238)

  • Helpers.rootname should only consider final path segment when dropping file extension

Improvements

  • implement Helpers.extname as a more efficient and flexible File.extname method

  • check for AsciiDoc file extension using end_with? instead of resolving the extname and using a lookup

Asciidoctor 2.0.5

Release date: 2019.04.01

Bug fixes

  • fix crash when source highlighter is Rouge and source language is not set on block (#3223)

  • update CLI and SyntaxHighlighter to allow Asciidoctor to load cleanly on Ruby 2.0 - 2.2

  • CLI should use $stdin instead of STDIN to be consistent with the use of $stdout

  • mark encoding of stdio objects used in CLI as UTF-8 (#3225)

  • make Asciidoctor::SyntaxHighlighter::Config.register_for method public as documented

Asciidoctor 2.0.4

Release date: 2019.03.31

Bug fixes

  • allow Asciidoctor to load cleanly on Ruby 2.0 - 2.2 for distributions that provide support for these older Ruby versions

  • make Asciidoctor::Converter::Config.register_for method public as documented

  • remove unused Asciidoctor::Converter::BackendTraits#derive_backend_traits private method

  • move Asciidoctor::Converter::BackendTraits.derive_backend_traits method to Asciidoctor::Converter

  • mark render and render_file methods as deprecated in API docs

Asciidoctor 2.0.3

Release date: 2019.03.28

Bug fixes

  • fix crash when attrlist is used on literal monospace phrase (#3216)

  • update use of magic regexp variables to fix compatibility with Opal / Asciidoctor.js (#3214)

Asciidoctor 2.0.2

Release date: 2019.03.26

Bug fixes

  • apply verbatim substitutions to literal paragraphs attached to list item (#3205)

  • implement #lines and #source methods on Table::Cell based on cell text (#3207)

Asciidoctor 2.0.1

Release date: 2019.03.25

Bug fixes

  • convert titles of cataloged block and section nodes containing attribute references eagerly to resolve attributes while in scope (#3202)

  • customize MathJax (using a postfilter hook) to apply displaymath formatting to AsciiMath block (#2498)

  • fix misspelling of deprecated default_attrs DSL function (missing trailing "s")

  • remove unused location property (attr_accessor :location) on DocinfoProcessor class

  • look for deprecated extension option :pos_attrs if :positional_attrs option is missing (#3199)

  • add detail to load error message if path differs from gem name (#1884)

Build and infrastructure

  • bundle .yardopts in RubyGem (#3193)

Asciidoctor 2.0.0

Release date: 2019.03.22

Enhancements and compliance

  • drop support for Ruby < 2.3 and JRuby < 9.1 and remove workarounds (#2764)

  • drop support for Slim < 3 (#2998)

  • drop the converter for the docbook45 backend from core; moved to github.com/asciidoctor/asciidoctor-docbook45 (#3005)

  • apply substitutions to section and block titles in normal substitution order (#1173)

  • make syntax highlighter pluggable; extract all logic into adapter classes (#2106)

  • add syntax highlighter adapter for Rouge (#1040)

  • redesign Converter API based on SyntaxHighlighter API; remap deprecated API to new API to ensure compatibility (#2891)

  • repurpose built-in converters as regular converters (#2891)

  • make registration and resolution of global converters thread-safe (#2891)

  • fold the default converter factory into the Converter module (#2891)

  • add a default implementation for Converter#convert in the Base converter (#2891)

  • rename Converter::BackendInfo to Converter::BackendTraits; map backend_info to new backend_traits method (#2891)

  • allow built-in converter classes to be resolved using Converter#for and instantiated using Converter#create (#2891)

  • allow converter factory to be passed using :converter_factory API option (#2891)

  • honor htmlsyntax if defined on converter (#2891)

  • add backend_traits_source keyword argument to CompositeConverter constructor (#2891)

  • add support for start attribute when using prettify to highlight source blocks with line numbering enabled

  • use String#encode to encode String as UTF-8 instead of using String#force_encoding (#2764)

  • add FILE_READ_MODE, URI_READ_MODE, and FILE_WRITE_MODE constants to control open mode when reading files and URIs and writing files (#2764)

  • set visibility of private and protected methods (#2764)

  • always run docinfo processor extensions regardless of safe mode (gives control to extension) (#2966)

  • use infinitive verb form for extension DSL method names; map deprecated method names where appropriate

  • add docinfo insertion slot for header location to built-in converters (#1720)

  • add support for the muted option on vimeo videos (allows autoplay to work in Chrome) (#3014)

  • use value of prettify-theme attribute as is if it starts with http:// or https:// (#3020)

  • allow icontype to be set using icons attribute (#2953)

  • when using a server-side syntax highlighter, highlight content of source block even if source language is not set (#3027)

  • automatically promote a listing block without an explicit style to a source block if language is set (#1117)

  • remove the 2-character (i.e., "") quote block syntax

  • don’t allow block role to inherit from document attribute; only look for role in block attributes (#1944)

  • split out functionality of -w CLI flag (script warnings) from -v CLI flag (verbose logging) (#3030)

  • log possible invalid references at info level (#3030)

  • log dropped lines at info level when attribute-missing=drop-line (#2861)

  • honor attribute-missing setting when processing include directives and block macros (#2855)

  • log warning when include directive is not resolved due to missing attribute or blank target; always include warning in output document (#2868)

  • use the third argument of AbstractNode#attr / AbstractNode#attr? to set the name of a fallback attribute to look for on the document (#1934)

  • change default value of third argument to Abstractnode#attr / AbstractNode#attr? to nil so attribute doesn’t inherit by default (#3059)

  • look for table-frame, table-grid, and table-stripes attributes on document as fallback for frame, grid, and stripes attributes on table (#3059)

  • add support for hover mode for table stripes (stripes=hover) (#3110)

  • always assume the target of a shorthand interdocument xref is a reference to an AsciiDoc document (source-to-source) (#3021)

  • if the target of a formal xref macro has a file extension, assume it’s a path reference (#3021)

  • never assume target of a formal xref macro is a path reference unless a file extension or fragment is present (#3021)

  • encode characters in URI to comply with RFC-3986

  • implement full support for styled xreftext in manpage converter (#3077)

  • allow the ID and role properties to be set on a list item of ordered and unordered lists via the API (#2840)

  • yield processor instance to registration block for document processor if block has non-zero arity (i.e., has parameters)

  • add Document#parsed? method to check whether document has been parsed

  • modify Cell class to extend from AbstractBlock instead of AbstractNode (#2963)

  • implement block? and inline? methods on Column, both which return false (#2963)

  • drop verse table cell style (treat as normal table cell) (#3111)

  • allow negated subs to be specified on inline pass macro (#2191)

  • log warning if footnoteref macro is found and compat mode is not enabled (#3114)

  • log info message if inline macro processor returns a String value (#3176)

  • apply subs to Inline node returned by inline macro processor if subs attribute is specified (#3178)

  • add create_inline_pass helper method to base extension processor class (#3178)

  • log debug message instead of warning if block style is unknown (#3092)

  • allow backend to delegate to a registered backend using the syntax synthetic:delegate when using custom templates (e.g., slides:html) (#891)

  • AbstractBlock#find_by looks inside AsciiDoc table cells if traverse_documents selector option is true (#3101)

  • AbstractBlock#find_by finds table cells, which can be selected using the :table_cell context in the selector (#2524)

  • allow ampersand to be used in e-mail address (#2553)

  • propogate ID assigned to inline passthrough (#2912)

  • rename control keywords in find_by to better align with the standard NodeFilter terminology

  • stop find_by iteration if filter block returns :stop directive

  • rename header_footer option to standalone (while still honoring header_footer for backwards compatibility) (#1444)

  • replace anchors and xrefs before footnotes (replace footnotes last in macros substitution group)

  • apply substitution for custom inline macro before all other macros

  • only promote index terms automatically (A, B, C becomes A > B > C + B > C + C) if indexterm-promotion option is set on document (#1487)

  • add support for see and see-also on index terms; parse attributes on indexterm macros if text contains = (#2047)

  • drop :indexterms table from document catalog (in preparation for solution to #450 in a 2.x release)

  • load additional languages for highlight.js as defined in the comma-separated highlightjs-languages attribute (#3036)

  • log warning if conditional expression in ifeval directive is invalid (#3161)

  • drop lines that contain an invalid preprocessor directive (#3161)

  • rename AbstractBlock#find_by directives; use :prune in place of :skip_children and :reject in place of :skip

  • convert example block into details/summary tag set if collapsible option is set; open by default if open option is set (#1699)

  • substitute replacements in author values used in document header (#2441)

  • require space after semi-colon that separates multiple authors (#2441)

  • catalog inline anchors at start of callout list items (#2818) (@owenh000)

  • add parse_attributes helper method to base extension Processor class (#2134)

Improvements

  • propagate document ID to DocBook output (#3011)

  • always store section numeral as string; compute roman numeral for part at assignment time (@vmj)

  • refactor code to use modern Hash syntax

  • define LIB_DIR constant; rename *_PATH constants to *_DIR constants to be consistent with RubyGems terminology (#2764)

  • only define ROOT_DIR if not already defined (for compatibility with Asciidoctor.js)

  • move custom docinfo content in footer below built-in docinfo content in footer in HTML converter (#3017)

  • read and write files using File methods instead of IO methods (#2995)

  • value comparison in AbstractNode#attr? is only performed if expected value is truthy

  • align default CodeRay style with style for other syntax highlighters (#2106)

  • ensure linenos class is added to linenos column when source highlighter is pygments and pygments-css=style

  • disable table stripes by default (#3110)

  • rename CSS class of Pygments line numbering table to linenotable (to align with Rouge) (#1040)

  • remove unused Converter#convert_with_options method (#2891)

  • add -e, --embedded CLI flag as alias for -s, --no-header-footer (require long option to specify eRuby impl) (#1444)

  • don’t store the options attribute on the block once the options are parsed (#3051)

  • add an options method on AbstractNode to retrieve the set of option names (#3051)

  • pass :input_mtime option to Document constructor; let Document constructor assign docdate/time/year attributes (#3029)

  • never mutate strings; add a frozen_string_literal: true magic comment to top of all Ruby source files (#3054)

  • always use docdate and doctime to compute docyear and docdatetime (#3064)

  • rename PreprocessorReader#exceeded_max_depth? to PreprocessorReader#exceeds_max_depth? and return nil if includes are disabled

  • stop populating :ids table in document catalog (#3084)

  • always use :refs table in document catalog to look for registered IDs (#3084)

  • don’t compute and store reference text in document catalog (#3084)

  • populate reference text table lazily for resolving ID by reference text (#3084)

  • don’t store fallback reference text on :bibref node (#3085)

  • call AbstractNode#reftext instead of AbstractNode#text to retrieve reference text for bibref node (#3085)

  • only map unparsed attrlist of inline macro to target when format is short

  • add clearer exception message when source data is binary or has invalid encoding (#2884)

  • rename context for table cell and table column to :table_cell and :table_column, respectively

  • rename hardbreaks document attribute to hardbreaks-option; retain hardbreaks as a deprecated alias (#3123)

  • extend TLD for implicit e-mail addresses to 5 characters (#3154)

  • truncate with precision (instead of rounding) when computing absolute width for columns in DocBook output (#3131)

  • drop legacy LaTeX math delimiters (e.g, $..$) if present (#1339)

  • use proper terminology in warning message about mismatched preprocessor directive (#3165)

  • rename low-level extension attribute name :pos_attrs to :positional_attrs

  • mark default_attrs extension DSL method deprecated in favor of default_attributes

  • upgrade MathJax to 2.7.5

Bug fixes

  • fix crash caused by inline passthrough macro with the macros sub clearing the remaining passthrough placeholders (#3089)

  • fix crash if ifeval directive is missing expression (#3164)

  • prevent relative leveloffset from making section level negative and causing hang (#3152)

  • don’t fail to parse Markdown-style quote block that only contains attribution line (#2989)

  • enforce rule that Setext section title must have at least one alphanumeric character; fixes problem w/ block nested inside quote block (#3060)

  • apply header subs to doctitle value when assigning it back to the doctitle document attribute (#3106)

  • don’t fail if value of pygments-style attribute is not recognized; gracefully fallback to default style (#2106)

  • do not alter the $LOAD_PATH (#2764)

  • fix crash if stem block is empty (#3118)

  • remove conditional comment for IE in output of built-in HTML converter; fixes sidebar table of contents (#2983)

  • fix styling of source blocks with linenums enabled when using prettify as syntax highlighter (#640)

  • update default stylesheet to support prettify themes (#3020)

  • remove hard-coded color values on source blocks in default stylesheet (#3020)

  • add fallback if relative path cannot be computed because the paths are located on different drives (#2944)

  • ignore explicit section level style (#1852)

  • don’t eat space before callout number in source block if line-comment attribute is empty (#3121)

  • check if type is defined in a way that’s compatible with autoload

  • fix invalid check for DSL in extension class (previously always returned true)

  • scope constant lookups (#2764)

  • use byteslice instead of slice to remove BOM from string (#2764)

  • don’t fail if value of -a CLI option is empty string or equals sign (#2997)

  • allow failure level of CLI to be set to info

  • Reader#push_include should not fail if data is nil

  • fix deprecated ERB trim mode that was causing warning (#3006)

  • move time anchor after query string on vimeo video to avoid dropping options

  • allow color for generic text, line numbers, and line number border to inherit from Pygments style (#2106)

  • enforce and report relative include depth properly (depth=0 rather than depth=1 disables nested includes)

  • allow outfilesuffix to be soft set from API (#2640)

  • don’t split paragraphs in table cell at line that resolves to blank if adjacent to other non-blank lines (#2963)

  • initialize the level to WARN when instantiating the NullLogger

  • next_adjacent_block should not fail when called on dlist item (#3133)

  • don’t suppress browser styles for summary tag; add pointer cursor and panel margin bottom (#3155)

  • only consider TLDs in e-mail address that have ASCII alpha characters

  • allow underscore in domain of e-mail address

Build and infrastructure

  • clear SOURCE_DATE_EPOCH env var when testing timezones (PR #2969) (@aerostitch)

  • remove compat folder (removes the AsciiDoc.py config file that provides pseudo-compliance with Asciidoctor and a stylesheet for an old Font Awesome migration)

  • add Ruby 2.6.0 to build matrix

  • stop running CI job on unsupported versions of Ruby

  • exclude test suite, build script, and Gemfile from gem (#3044)

  • split build tasks out into individual files