Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


:gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML5, DocBook 5 (or 4.5) and other formats.

Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star half bd79095782ee4930099175e5ce7f4c89fa3ddabcd56fffcc7c74f6f2a2d46b27 (1 ratings)
Rated 4.5 out of 5
Subscribe to updates I use asciidoctor

Statistics on asciidoctor

Number of watchers on Github 1795
Number of open issues 638
Average time to close an issue 8 days
Main language Ruby
Average time to merge a PR 1 day
Open pull requests 44+
Closed pull requests 32+
Last commit over 1 year ago
Repo Created over 7 years ago
Repo Last Updated over 1 year ago
Size 9.75 MB
Homepage https://asciidoct...
Organization / Authorasciidoctor
Latest Releasev1.5.6.1
Page Updated
Do you use asciidoctor? Leave a review!
View open issues (638)
View asciidoctor activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating asciidoctor for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

= Asciidoctor Dan Allen[@mojavelinux]; Sarah White[@graphitefriction]; Ryan Waldron[@erebor] // settings: :idprefix: :idseparator: - :source-language: ruby :language: {source-language} ifndef::env-github[:icons: font] ifdef::env-github[] :status: :outfilesuffix: .adoc :caution-caption: :fire: :important-caption: :exclamation: :note-caption: :paperclip: :tip-caption: :bulb: :warning-caption: :warning: endif::[] // Variables: :release-version: // URIs: :uri-org: :uri-repo: {uri-org}/asciidoctor :uri-asciidoctorj: {uri-org}/asciidoctorj :uri-asciidoctorjs: {uri-org}/asciidoctor.js :uri-project: ifdef::env-site[:uri-project: link:] :uri-docs: {uri-project}/docs :uri-news: {uri-project}/news :uri-manpage: {uri-project}/man/asciidoctor :uri-issues: {uri-repo}/issues :uri-contributors: {uri-repo}/graphs/contributors :uri-rel-file-base: link: :uri-rel-tree-base: link: ifdef::env-site[] :uri-rel-file-base: {uri-repo}/blob/master/ :uri-rel-tree-base: {uri-repo}/tree/master/ endif::[] :uri-changelog: {uri-rel-file-base}CHANGELOG.adoc :uri-contribute: {uri-rel-file-base}CONTRIBUTING.adoc :uri-license: {uri-rel-file-base}LICENSE :uri-tests: {uri-rel-tree-base}test :uri-discuss: :uri-irc: irc:// :uri-rubygem: :uri-what-is-asciidoc: {uri-docs}/what-is-asciidoc :uri-user-manual: {uri-docs}/user-manual :uri-install-docker: //:uri-install-doc: {uri-docs}/install-toolchain :uri-install-macos-doc: {uri-docs}/install-asciidoctor-macos :uri-render-doc: {uri-docs}/render-documents :uri-themes-doc: {uri-docs}/produce-custom-themes-using-asciidoctor-stylesheet-factory :uri-gitscm-repo: :uri-prototype: {uri-gitscm-repo}/commits/master/lib/asciidoc.rb :uri-freesoftware: :uri-foundation: :uri-tilt: :uri-ruby: // images: :image-uri-screenshot:

{uri-project}/[Asciidoctor] is a fast text processor and publishing toolchain for converting {uri-what-is-asciidoc}[AsciiDoc] content to HTML5, DocBook 5 (or 4.5) and other formats. Asciidoctor is written in Ruby, packaged as a RubyGem and published to {uri-rubygem}[]. The gem is also included in several Linux distributions, including Fedora, Debian, Ubuntu, and Alpine. Asciidoctor is open source, {uri-repo}[hosted on GitHub] and released under {uri-license}[the MIT license].

ifndef::env-site[] Translations of this document are available in the following languages:

  • {uri-rel-file-base}README-zh_CN.adoc[]
  • {uri-rel-file-base}README-fr.adoc[Franais]
  • {uri-rel-file-base}README-jp.adoc[] endif::[]

.Key documentation [.compact]

  • {uri-docs}/what-is-asciidoc[What is Asciidoc?]
  • {uri-docs}/asciidoc-writers-guide[AsciiDoc Writer's Guide]
  • {uri-docs}/asciidoc-syntax-quick-reference[AsciiDoc Syntax Reference]
  • {uri-docs}/user-manual[Asciidoctor User Manual]

.Where Ruby goes, Asciidoctor follows

You can run Asciidoctor on the JVM using JRuby. To invoke the Asciidoctor API directly from Java and other JVM languages, use {uri-asciidoctorj}[AsciidoctorJ]. There are plugins available, based on AsciidoctorJ, that integrate the Asciidoctor processor into Apache Maven, Gradle or Javadoc builds.

Asciidoctor also runs in JavaScript. We use[Opal] to transcompile the Ruby source to JavaScript to produce {uri-asciidoctorjs}[Asciidoctor.js], a fully-functional version of Asciidoctor that works in any JavaScript environment, such as a web browser or Node.js. Asciidoctor.js is used to power the AsciiDoc preview extensions for Chrome, Atom, Brackets and other web-based tooling.

ifdef::status[] .Project health image:[Build Status (Travis CI), link=] image:[Build Status (AppVeyor), link=] //image:[Coverage Status, link=] //image:[Code Climate, link=] image:[Inline docs, link=] endif::[]

== The Big Picture

Asciidoctor reads content written in plain text, as shown in the panel on the left in the image below, and converts it to HTML5, as shown rendered in the right panel. Asciidoctor applies a default stylesheet to the HTML5 document to provide a pleasant out-of-the-box experience.

image::{image-uri-screenshot}[Preview of AsciiDoc source and corresponding rendered HTML]

== AsciiDoc Processing

Asciidoctor reads and parses text written in the AsciiDoc syntax, then feeds the parse tree to a set of built-in converters to produce HTML5, DocBook 5 (or 4.5) or man(ual) page output. You have the option of using your own converter or loading {uri-tilt}[Tilt]-supported templates to customize the generated output or produce additional formats.

NOTE: Asciidoctor is a drop-in replacement for the original AsciiDoc Python processor ( The Asciidoctor test suite has {uri-tests}[> 1,900 tests] to ensure compatibility with the AsciiDoc syntax.

In addition to the classic AsciiDoc syntax, Asciidoctor recognizes additional markup and formatting options, such as font-based icons (e.g., +icon:fire[]+) and UI elements (e.g., +button:[Save]+). Asciidoctor also offers a modern, responsive theme based on {uri-foundation}[Foundation] to style the HTML5 output.

== Requirements

Asciidoctor works on Linux, macOS and Windows and requires one of the following implementations of {uri-ruby}[Ruby]:

  • Ruby (MRI/CRuby 1.8.7 - 2.5)
  • JRuby (1.7 in Ruby 1.8 and 1.9 modes, 9000)
  • Rubinius 2.2.x
  • Opal (JavaScript)

We welcome your help testing Asciidoctor on these and other platforms. Refer to the <> section to learn how to get involved.


If you're using a non-English Windows environment, you may bump into an Encoding::UndefinedConversionError when invoking Asciidoctor. To solve this issue, we recommend changing the active code page in your console to UTF-8:

chcp 65001

Once you make this change, all your Unicode headaches will be behind you. If you're using an IDE like Eclipse, make sure you set the encoding to UTF-8 there as well.

Asciidoctor works best when you use UTF-8 everywhere.

== Installation

Asciidoctor can be installed using (a) the gem install command, (b) Bundler, (c) package managers for popular Linux distributions, or (d) Homebrew for macOS.

TIP: The benefit of using a Linux package manager to install the gem is that it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine. The drawback is that the package may not be available immediately after the release of the gem. If you need the latest version, you can always fallback to using the gem command.

=== (a) gem install

Open a terminal and type (excluding the leading $):

$ gem install asciidoctor

If you want to install a pre-release version (e.g., a release candidate), use:

$ gem install asciidoctor --pre

.Upgrading your installation


If you have an earlier version of Asciidoctor installed, you can update it using:

$ gem update asciidoctor

If you install a new version of the gem using gem install instead of gem update, you'll have multiple versions installed. If that's the case, use the following gem command to remove the old versions:

$ gem cleanup asciidoctor

=== (b) Bundler

. Create a Gemfile in the root folder of your project (or the current directory) . Add the asciidoctor gem to your Gemfile as follows: +


source '' gem 'asciidoctor'

or specify the version explicitly

gem 'asciidoctor', '{release-version}'

. Save the Gemfile . Open a terminal and install the gem using:

$ bundle

To upgrade the gem, specify the new version in the Gemfile and run bundle again. Using bundle update is not recommended as it will also update other gems, which may not be the desired result.

=== (c) Linux package managers

==== DNF (Fedora 21 or greater)

To install the gem on Fedora 21 or greater using dnf, open a terminal and type:

$ sudo dnf install -y asciidoctor

To upgrade the gem, use:

$ sudo dnf update -y asciidoctor

TIP: Your system may be configured to automatically update rpm packages, in which case no action is required by you to update the gem.

==== apt-get (Debian, Ubuntu, or Mint)

To install the gem on Debian, Ubuntu or Mint, open a terminal and type:

$ sudo apt-get install -y asciidoctor

To upgrade the gem, use:

$ sudo apt-get upgrade -y asciidoctor

TIP: Your system may be configured to automatically update deb packages, in which case no action is required by you to update the gem.

The version of Asciidoctor installed by the package manager (apt-get) may not match the latest release of Asciidoctor. Consult the package repository for your distribution to find out which version is packaged per distribution release.

  •[asciidoctor package by Debian release]
  •[asciidoctor package by Ubuntu release]
  •[asciidoctor package by Mint release]


You're advised against using the gem update command to update a gem managed by the package manager. Doing so puts the system into an inconsistent state as the package manager can no longer track the files (which get installed under /usr/local). Simply put, system gems should only be managed by the package manager.

If you want to use a version of Asciidoctor that is newer than what is installed by the package manager, you should use[RVM] to install Ruby in your home directory (i.e., user space). Then, you can safely use the gem command to install or update the Asciidoctor gem.

When using RVM, gems are installed in a location isolated from the system.

==== apk (Alpine Linux)

To install the gem on Alpine Linux, open a terminal and type:

$ sudo apk add asciidoctor

To upgrade the gem, use:

$ sudo apk add -u asciidoctor

TIP: Your system may be configured to automatically update apk packages, in which case no action is required by you to update the gem.

=== (d) Homebrew (macOS)

You can use Homebrew to install Asciidoctor on macOS. If you haven't yet installed Homebrew, follow the instructions at[].

Once Homebrew is installed, you can install the asciidoctor gem using the[asciidoctor] package. To do so, open a terminal and type:

$ brew install asciidoctor

To upgrade the gem, use:

$ brew update $ brew upgrade asciidoctor

TIP: Homebrew installs the asciidoctor gem into an exclusive prefix that's independent of system gems.

=== Other installation options

  • {uri-install-docker}[Installing Asciidoctor using Docker]
  • {uri-install-macos-doc}[Installing Asciidoctor on macOS] // at the moment, the following entry is just a reiteration of the information in this README //* {uri-install-doc}[Installing the Asciidoctor toolchain]

== Usage

If the Asciidoctor gem installed successfully, the asciidoctor command line interface (CLI) will be available on your PATH. To verify it's available, run the following in your terminal:

$ asciidoctor --version

You should see information about the Asciidoctor version and your Ruby environment printed in the terminal.

[.output,subs=attributes+] .... Asciidoctor {release-version} [] Runtime Environment (ruby 2.4.1p111 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8) ....

Asciidoctor also provides an API. The API is intended for integration with other Ruby software, such as Rails, Sinatra and GitHub, and other languages, such as Java (via {uri-asciidoctorj}[AsciidoctorJ]) and JavaScript (via {uri-asciidoctorjs}[Asciidoctor.js]).

=== Command line interface (CLI)

The asciidoctor command allows you to invoke Asciidoctor from the command line (i.e., a terminal).

The following command converts the file README.adoc to HTML and saves the result to the file README.html in the same directory. The name of the generated HTML file is derived from the source file by changing its file extension to .html.

$ asciidoctor README.adoc

You can control the Asciidoctor processor by adding various flags and switches, which you can learn about using:

$ asciidoctor --help

For instance, to write the file to a different directory, use:

$ asciidoctor -D output README.adoc

The asciidoctor {uri-manpage}[man page] provides a complete reference of the command line interface.

Refer to the following resources to learn more about how to use the asciidoctor command.

  • {uri-render-doc}[How do I convert a document?]
  • {uri-themes-doc}[How do I use the Asciidoctor stylesheet factory to produce custom themes?]

=== Ruby API

To use Asciidoctor in your application, you first need to require the gem:

[source] require 'asciidoctor'

You can then convert an AsciiDoc source file to an HTML file using:

[source] Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe

WARNING: When using Asciidoctor via the API, the default safe mode is :secure. In secure mode, several core features are disabled, including the include directive. If you want to enable these features, you'll need to explicitly set the safe mode to :server (recommended) or :safe.

You can also convert an AsciiDoc string to embeddable HTML (for inserting in an HTML page) using:


content = 'Zen in the art of writing[AsciiDoc].'

Asciidoctor.convert content, safe: :safe

If you want the full HTML document, enable the header_footer option as follows:


content = 'Zen in the art of writing[AsciiDoc].'

html = Asciidoctor.convert content, header_footer: true, safe: :safe

If you need access to the parsed document, you can split the conversion into discrete steps:


content = 'Zen in the art of writing[AsciiDoc].' document = Asciidoctor.load content, header_footer: true, safe: :safe puts document.doctitle

html = document.convert

Keep in mind that if you don't like the output Asciidoctor produces, you can change it! Asciidoctor supports custom converters that can handle converting from the parsed document to the generated output.

One easy way to customize the output piecemeal is by using the template converter. The template converter allows you to supply a {uri-tilt}[Tilt]-supported template file to handle converting any node in the document.

However you go about it, you can have 100% control over the output. For more information about how to use the API or to customize the output, refer to the {uri-user-manual}[user manual].

== Contributing

In the spirit of {uri-freesoftware}[free software], everyone is encouraged to help improve this project. If you discover errors or omissions in the source code, documentation, or website content, please don't hesitate to submit an issue or open a pull request with a fix. New contributors are always welcome!

Here are some ways you can contribute:

  • by using prerelease (alpha, beta or preview) versions
  • by reporting bugs
  • by suggesting new features
  • by writing or editing documentation
  • by writing specifications
  • by writing code -- No patch is too small. ** fix typos ** add comments ** clean up inconsistent whitespace ** write tests!
  • by refactoring code
  • by fixing {uri-issues}[issues]
  • by reviewing patches

The {uri-contribute}[Contributing] guide provides information on how to create, style, and submit issues, feature requests, code, and documentation to the Asciidoctor Project.

== Getting Help

The Asciidoctor project is developed to help you easily write and publish your content. But we can't do it without your feedback! We encourage you to ask questions and discuss any aspects of the project on the discussion list, on Twitter or in the chat room.

Discussion list (Nabble):: {uri-discuss} Twitter::[#asciidoctor] hashtag or[@asciidoctor] mention Chat (Gitter):: image:[Gitter, link=] //// Chat (IRC):: {uri-irc}[#asciidoctor] on FreeNode IRC ////

ifdef::env-github[] Further information and documentation about Asciidoctor can be found on the project's website.

{uri-project}/[Home] | {uri-news}[News] | {uri-docs}[Docs] endif::[]

The Asciidoctor organization on GitHub hosts the project's source code, issue tracker, and sub-projects.

Source repository (git):: {uri-repo} Issue tracker:: {uri-issues} Asciidoctor organization on GitHub:: {uri-org}

== Copyright and Licensing

Copyright (C) 2012-2018 Dan Allen, Ryan Waldron and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License.

See the {uri-license}[LICENSE] file for details.

== Authors

Asciidoctor is led by[Dan Allen] and[Sarah White] and has received contributions from {uri-contributors}[many other individuals] in Asciidoctor's awesome community. The project was initiated in 2012 by[Ryan Waldron] and based on {uri-prototype}[a prototype] written by[Nick Hengeveld].

AsciiDoc was started by Stuart Rackham and has received contributions from many other individuals in the AsciiDoc community.

ifndef::env-site[] == Changelog

ifeval::[{safe-mode-level} < 20] include::CHANGELOG.adoc[tag=compact,leveloffset=+1] endif::[]

Refer to the {uri-changelog}[CHANGELOG] for a complete list of changes in older releases. endif::[]

asciidoctor open issues Ask a question     (View All Issues)
  • almost 3 years Automatically add bibliography style to list in bibliography section
  • almost 3 years Parser leaves behind closing conditional directive if adjacent to admonition paragraph
  • almost 3 years Allow syntax highlighter extensions in document header
  • almost 3 years Document attributes, in a document with a header, are not processed when using the include macro with a leveloffset=1
  • almost 3 years Use a specific (or multiple) vocabluary (markup) for class attributes in html conversion
  • almost 3 years Asciidoc to Markdown conversion (graceful downgrade)
  • almost 3 years Asciidoc to Asciidoc conversion
  • almost 3 years User comments, inline AsciiDoc
  • almost 3 years epub3 gem not installing
  • almost 3 years relative links do not work when including the file
  • almost 3 years Add support for tel tag
  • almost 3 years avoid inline javascript when using :source-highlighter: highlightjs
  • almost 3 years File objects created by must be closed explicitly
  • about 3 years Specifying the dimensions of images by other means than pixels or % (for html output)
  • about 3 years Asciidoctor And Google Tag Manager Extremely Cumbersome
  • about 3 years asciidoctor plugin 1.5.3 failed in ubuntu(NotImplementedError) fstat unimplemented unsupported or native support failed to load
  • about 3 years menu macro doesn't work with non-english words
  • about 3 years Asciidoctor should issue a warning if there is a block but it's not a candidate for inline conversion
  • about 3 years Reasons for LoadErrors when loading Ruby libs are swallowed.
  • about 3 years :author: attribute should support rich text (such as a link)
  • about 3 years Problems with docbook output for bibliography
  • about 3 years audio and video blocks are using imagesdir, but should have a dedicated attribute
  • about 3 years multiple problems when declaring inline anchor ids in headers
  • about 3 years multiple anchor preceding section headers willbe removed from final output
  • about 3 years some non-alphanumeric characters in anchor ids can cause parsing problems for headers - doc oversight?
  • about 3 years Content Security Policy violations
  • about 3 years when included in the same wrapper files, inter-doc links not converted to intra-doc links in some cases
  • about 3 years conflicting anchor names and Intra/Inter-doc links between multiple included adoc files are not rectified in final document
  • about 3 years Attribute scope of included files
  • about 3 years Multiple RevisionInfo entries are processed as content
asciidoctor open pull requests (View All Pulls)
  • Manpage default boilerplate
  • track ordered list starting marker
  • resolves #1240 read docinfo footer files in AsciiDoc format
  • resolves #1487 add flag to control automatic promotion of index terms
  • Implementation of epigraphs using roles
  • upgrade Nokogiri to 1.6.x (except on Ruby 1.8)
  • added Prism.js syntax highlighting option
  • WIP Allow icons/images to be used for list item bullets
  • resolves #858 use captioned title in block xref
  • use stronger CSS rule for general text color in Pygments stylesheet
  • Support alternate font icon sets
  • skip-front-matter: also support TOML front matter
  • resolves #1861 add attribute to control maximum attribute value size
  • fix tags for languages like Mathematica, OCaml or F#
  • Use a special logic for include processing only on a browser environment
  • Pull request to fix Issue 1895
  • resolves #1895 remove max-width on the callout number icon
  • support anchors on labeled lists
  • Adds option to include the section number in a cross-reference
  • resolves #1996 set sectname of header section to sectname
  • resolves #1981 allow use of option to enable line numbers on source block
  • Allow japanese Hiragana, Katakana, Kanji to section id for opal
  • Encode filename by UTF-8 when convert_file
  • add stripes attribute for tables
  • path_resolver.relative_path: use standard library that just works
  • Adds sourcemap on list items
  • resolves #2204 use [ \t] instead of \p{Blank} to match spaces
  • resolves #1729 add support for include tags in languages with only circumfix comments
  • resolves #858 Add possibility to use figure number or text in link
  • resolves #1694 apply title substitutions to reftext
  • update the zh-CN README file.
  • Have parse_section_title turn off Markdown compliance on seeing = header
  • Make default output Kindle-friendly
  • resolves #661 number special sections if sectnums contains the value "special"
  • resolves #1521 don't output title of special section if concealed option is set
  • resolves #2369 add XML circumfix comments to .js and .ts files
  • resolves #2347 allow inline footnote macro to define footnote ref
  • refactor sub_attributes
  • Fix for #1121 - Introduce four tilde syntax for open blocks and deprecate '--'
  • Fix wrong `Asciidoctor::AbstractBlock#lineno` of nested lists and tables
  • Support newline in asciimath stem block in HTML5 output.
  • base_dir can be a uri
  • resolves #2599 and #2602 correctly resolve includes in browser environment
asciidoctor questions on Stackoverflow (View All Questions)
  • How to generate a cover image picture with asciidoctor-fopub
  • markdown source code callouts like asciidoctor?
  • asciidoctor makes wrong rendering?
  • Custom style for custom role in Asciidoctor PDF
  • How to use tocify with asciidoctor for a dynamic toc?
  • Asciidoctor 'snippets' attribute not found from gradle
  • Change location of MathJax Javascript in AsciiDoctor-generated HTML
  • Render non english characters in asciidoctor-pdf
  • How to render asciidoc filename in asciidoctor template?
  • Asciidoctor: how to replace expression in included document?
  • Asciidoctor attribute replacement in codeblock
  • Overhanding properties when rendering Asciidoctor documents with Maven Site plugin
  • Creating custom HTML with asciidoctor
  • Rendering AsciiDoctor doc with includes within Maven Site run
  • How to set Asciidoc toc.section.depth value from simple 'asciidoctor file.txt -o file.html' command?
  • Asciidoctor navigation bar
  • How to prevent substitution with two instances of C++ in an asciidoctor sentence?
  • asciidoctor breaks rendering deck.js backend
  • How can I place two images side-by-side with Asciidoctor?
  • How to display AsciiDoc in RoR view with AsciiDoctor Gem?
  • Unit of measure for image dimensions in AsciiDoc/AsciiDoctor documents
  • How do I configure asciidoctor-gradle-plugin to handle plantuml?
  • Using the richness of syntax highlighting produced by asciidoctor
  • asciidoctor-maven-plugin: use infodoc file to include javascript in the html output
  • Can Asciidoctor render a separate HTML page per chapter?
  • add cover page with asciidoctor
  • Render .adoc file in HTML template using asciidoctor
  • syntax highlighting with coderay, asciidoctor not working
  • Asciidoctor::HTML5::DocumentTemplate replacement
  • Using Asciidoctor in Rails
asciidoctor list of languages used
asciidoctor latest release notes
v1.5.6.1 v1.5.6.1

This release fixes regressions and integration problems that were introduced in the 1.5.6 release. Mostly notably, compatibility with Asciidoctor Diagram was restored, content in a delimited block after a skipped block is preserved, attributes are substituted in the target of inline image occurring in a section or block title, and an unnecessary warning when attempting to copy the stylesheet is suppressed. We're also happy to report that Travis CI now takes care of releasing the gem to Additional changes can be found in the changelog below.

If you're upgrading from an earlier version, you're advised to skip 1.5.6 and move directly to Downstream projects, such as Asciidoctor.js and AsciidoctorJ, will based their 1.5.6 release on this version rather than 1.5.6.


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


Bug fixes

  • continue to read blocks inside a delimited block after content is skipped (PR #2318)
  • don't create an empty paragraph for skipped content inside a delimited block (PR #2319)
  • allow the subs argument of Substitutors#apply_subs to be nil
  • coerce group name to symbol when registering extension (#2324)
  • eagerly substitute attributes in target of inline image macro (#2330)
  • don't warn if source stylesheet can't be read but destination already exists (#2323)
  • track include path correctly if path is absolute and outside of base directory (#2107)
  • preprocess second line of setext section title (PR #2321)
  • preprocess second line of setext discrete heading (PR #2332)
  • return filename as relative path if filename doesn't share common root with base directory (#2107)

Improvements / Refactoring

  • change default text for inter-document xref (PR #2316)
  • add additional tests to test behavior of Reader#peek_lines
  • parse revision info line correctly that only has version and remark; add missing test for scenario
  • rename AtxSectionRx constant to AtxSectionTitleRx for consistency with SetextSectionTitleRx constant
  • use terms atx and setext to refer to section title syntax (PR #2334)
  • rename HybridLayoutBreakRx constant to ExtLayoutBreakRx
  • change terminology from floating title to discrete heading
  • consolidate skip blank lines and check for end of reader (PR #2325)
  • have Reader#skip_blank_lines report end of file (PR #2325)
  • don't mix return type of Parser.build_block method (PR #2328)
  • don't track eof state in reader (PR #2320)
  • use shift instead of advance to consume line when return value isn't needed (PR #2322)
  • replace terminology floating title with discrete heading
  • remove unnecessary nil_or_empty? checks in substitutor
  • leverage built-in assert / refute methods in test suite

Build / Infrastructure

  • config Travis CI job to release gem (PR #2333)
  • add SHA1 hash to message used for triggered builds
  • trigger build of AsciidoctorJ on every change to core
  • trigger build of Asciidoctor Diagram on every change to core

Release meta

Released on: 2017-07-23 Released by: @mojavelinux Release beer: She'brew Double IPA

Logs: resolved issues | full diff


Thanks to the following people who contributed to this release:

@Mogztter, @JBR69, @robertpanzer, @ztmr, and @pepijnve.

Special thanks goes to @vogella for providing additional financial support following the 1.5.6 release.

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

v1.5.6 v1.5.6

This iteration began as a minor release and morphed into one of the most important and substantial releases to date. This release brings several landmark features, major performance improvements (25% increase in speed), critical bug fixes, and lots of important internal restructuring.

The most recognizable new feature is surely the formal cross reference text (e.g., Figure 1, Architecture). To support this feature, the references table is now populated with nodes instead of just reference text, making it easier for extensions to use this information. Additionally, bibliography anchors now support reference text and more warnings have been added if references are invalid.

There are also major enhancements to partial includes, which can now be used to exclude in addition to including tagged regions. In the area of security, rel=noopener attribute is added to all links that target _blank. Block extensions now have access to the context of the block that was matched via the cloaked-context attribute. In the bug category, complex content on callout list items is retained in HTML output, the operation logic for ifndef has been made compliant, lines that shouldn't be recognized aren't, and substitutions are applied more consistently and accurately.

But that's just a partial summary. To get the whole story, check out the changelog below.


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



  • use custom cross reference text if xrefstyle attribute is set (full, short, basic) (#858, #1132)
  • store referenceable nodes under refs key in document catalog (PR #2220)
  • apply reftext substitutions (specialchars, quotes, replacements) to value returned by reftext method (PR #2220)
  • add xreftext method to AbstractBlock, Section, and Inline to produce formatted text for xref (PR #2220)
  • introduce attributes chapter-refsig, section-refsig, and appendix-refsig to set reference signifier for chapter, section, and appendix, respectively (PR #2220)
  • add rel=noopener to links that target _blank or when noopener option is set (#2071)
  • add option to exclude tags when including a file (#1516)
  • add meta for shortcut icon if favicon attribute is set (#1574)
  • allow use of linenums option to enable line numbers on a source block (#1981)
  • allow extension groups to be unregistered individually (#1701)
  • catalog bibliography anchors and capture reftext (#560, #1562)
  • automatically add bibliography style to unordered list in bibliography section (#1924)
  • disable startinline option when highlighting PHP if mixed option is set on source block (PR #2015) (@ricpelo)
  • configure Slim to resolve includes in specified template dirs (#2214)
  • dump manpage when -h manpage flag is passed to CLI (#2302)
  • add resolves_attributes method to DSL for macros (#2122)
  • invoke convert on result of custom inline macro if value is an inline node (#2132)
  • resolve attributes for custom short inline macros if requested (#1797)
  • add convenience method to create section from extension; use same initialization logic as parser (#1957)
  • add handles? method to DSL for IncludeProcessor (#2119)
  • pass through preload attribute to video tag (#2046)
  • add start and end times for audio element (#1930)
  • set localyear and docyear attributes (#1372)
  • pass cloaked context to block extension via cloaked-context attribute (#1606)
  • add support for covers in DocBook 5 converter (#1939)
  • accept named pipe (fifo) as the input file (#1948)
  • add AbstractBlock#next_adjacent_block helper method
  • rename Document#references to catalog; alias references to catalog (PR #2237)
  • rename extensions_registry option to extension_registry
  • rename Extensions.build_registry method to create
  • autoload extensions source file when Asciidoctor::Extensions is referenced (PR #2114, PR #2312)
  • apply default_attrs to custom inline macro (PR #2127)
  • allow tab separator for table to be specified using \t (#2073)
  • add Cell#text= method


  • significant improvements to performance, especially in parser and substitutors
  • process include directive inside text of short form preprocessor conditional (#2146)
  • add support for include tags in languages that only support only circumfix comments (#1729)
  • allow spaces in target of block image; target must start and end with non-space (#1943)
  • add warning in verbose mode if xref is not found (@fap-) (#2268)
  • add warning if duplicate ID is detected (#2244)
  • validate that output file will not overwrite input file (#1956)
  • include docfile in warning when stylesheet cannot be read (#2089)
  • warn if doctype=inline is used and block has unexpected content model (#1890)
  • set built-in docfilesuffix attribute (#1673)
  • make sourcemap field on Document read/write (#1916)
  • allow target of xref to begin with attribute reference (#2007)
  • allow target of xref to be expressed with leading # (#1546)
  • allow kbd and btn macros to wrap across multiple lines (#2249)
  • allow menu macro to span multiple lines; unescape escaped closing bracket
  • make menu macro less greedy
  • allow ampersand to be used as the first character of the first segment of a menu (#2171)
  • enclose menu caret in HTML tag (#2165)
  • use black text for menu reference; tighten word spacing (#2148)
  • fix parsing of keys in kbd macro (PR #2222)
  • add support for the window option for the link on a block image (#2172)
  • set correct level for special sections in parser (#1261)
  • always set numbered property on appendix to true
  • store number for formal block on node (#2208)
  • set sectname of header section to header (#1996)
  • add the remove_attr method to AbstractNode (#2227)
  • use empty string as default value for set_attr method (#1967)
  • make start argument to system_path optional (#1965)
  • allow API to control subs applied to ListItem text (#2035)
  • allow text of ListItem to be assigned (in an extension) (#2033)
  • make generate_id method on section a static method (#1929)
  • validate name of custom inline macro; cache inline macro rx (#2136)
  • align number in conum list to top by default (#1999)
  • fix CSS positioning of interactive checkbox (#1840)
  • fix indentation of list items when markers are disabled (none, no-bullet, unnumbered, unstyled) (PR #2286)
  • instruct icon to inherit cursor if inside a link
  • close all files opened internally (#1897)
  • be more precise about splitting kbd characters (#1660)
  • rename limit method on String to limit_bytesize (#1889)
  • leverage Ruby's match? method to speed up non-capturing regexps (PR #1938)
  • preserve inline break in manpages (@letheed)
  • check for presence of SOURCE_DATE_EPOCH instead of value; fail if value is malformed
  • add Rows#by_section method to return table sections (#2219)
  • cache which template engines have been loaded to avoid unnecessary processing
  • rename assign_index method to enumerate_section (PR #2242)
  • don't process double quotes in xref macro (PR #2241)
  • optimize attr and attr? methods (PR #2232)
  • use IO.write instead of w/ block; backport for Opal
  • backport IO.binread to Ruby 1.8.7 to avoid runtime check
  • cache backend and doctype values on document
  • allow normalize option to be set on PreprocessorReader; change default to false
  • move regular expression constants for Opal to Asciidoctor.js build (PR #2070)
  • add missing comma in warning message for callout list item out of sequence
  • combine start_with? / end_with? checks into a single method call
  • rename UriTerminator constant to UriTerminatorRx
  • promote subs to top-level constants; freeze arrays
  • rename PASS_SUBS constant to NONE_SUBS
  • rename EOL constant to LF (retain EOL as alias)
  • rename macro regexp constants so name follows type (e.g., InlineImageMacroRx)


  • retain block content in items of callout list when converting to HTML and man page (#1478)
  • only substitute specialchars for content in literal table cells (#1912)
  • fix operator logic for ifndef directive with multiple attributes (#1983)
  • only recognize uniform underline for setext section title (#2083)
  • don't match headings with mixed leading characters (#2074)
  • fix layout break from matching lines it shouldn't
  • fix behavior of attribute substitution in docinfo content (PR #2296)
  • encode spaces in URI (PR #2274)
  • treat empty string as a valid block title
  • preprocess lines of a simple block (#1923)
  • don't drop trailing blank lines when splitting source into lines (PR #2045)
  • only drop known AsciiDoc extensions from the inter-document xref path (#2217)
  • don't number special sections or special subsections by default (#2234)
  • assign sectname based on name of manuscript element (#2206)
  • honor leveloffset when resolving implicit doctitle (#2140)
  • permit leading, trailing, and repeat operators in target of preprocessor conditional (PR #2279)
  • don't match link macro in block form (i.e., has two colons after prefix) (#2202)
  • do not match bibliography anchor that begins with digit (#2247)
  • use \t instead of \p{Blank} to match spaces (#2204)
  • allow named entity to have trailing digits (e.g., there4) (#2144)
  • only assign style to image alt text if alt text is not specified
  • substitute replacements in non-generated alt text of block image (PR #2285)
  • keep track of whether alt text is auto-generated by assigning default-alt attribute (PR #2287)
  • suppress info element in docbook output if noheader attribute is set (#2155)
  • preserve leading indentation in literal and verse table cells (#2037)
  • preserve whitespace in literal and verse table cells (#2029)
  • set doctype-related attributes in AsciiDoc table cell (#2159)
  • fix comparison logic when preprocessing first line of AsciiDoc table cell
  • set filetype to man when backend is manpage (#2055)
  • respect image scaling in DocBook converter (#1059)
  • share counters between AsciiDoc table cells and main document (#1942)
  • generate ID for floating title from converted title (#2016)
  • split treeprocessor into two words; add aliases for compatibility (PR #2179)
  • allow trailing hyphen in attribute name used in attribute reference
  • allow escaped closing bracket in text of xref macro
  • process pass inline macro with empty text; invert extract logic
  • drop support for reftext document attribute (must be specified on node)
  • fix compliance with Haml >= 5 (load Haml eagerly; remove ugly option)
  • don't match inline image macro if target contains endline or leading or trailing spaces
  • assign id instead of target on ref/bibref node (PR #2307)
  • remove regexp hacks for Opal (#2110)
  • drop outdated quoting exceptions for Opal (PR #2081)

Bug fixes

  • don't allow table borders to cascade to nested tables (#2151)
  • escape special characters in reftext of anchor (#1694)
  • sanitize content of authors meta tag in HTML output (#2112)
  • fix stray marks added when unescaping unconstrained passthroughs (PR #2079)
  • don't confuse escaped quotes in CSV data as enclosing quotes (#2008)
  • don't activate implicit header if cell in first line of table contains a blank line (#1284, #644)
  • allow compat-mode in AsciiDoc table cell to inherit from parent document (#2153)
  • manify all normal table cell content (head, body, foot) in manpage output
  • add missing newline after table caption in manpage output (#2253)
  • correctly format block title on video in manpage output
  • don't crash if substitution list resolves to nil (#2183)
  • fail with informative message if converter cannot be resolved (#2161)
  • fix regression of not matching short form of custom block macro
  • encode double quotes in image alt text when used in an attribute (#2061)
  • encode double quote and strip XML tags in value of xreflabel attribute in DocBook converter (PR #2220)
  • fix typo in base64 data (PR #2094) (@mogztter)
  • permit pass macro to surround a multi-line attribute value with hard line breaks (#2211)
  • fix sequential inline anchor macros with empty reftext (#1689)
  • don't mangle compound names when document has multiple authors (#663)
  • don't drop last line of verbatim block if it contains only a callout number (#2043)
  • prevent leading & trailing round brackets from getting caught in indexterm (#1581)
  • remove cached title when title is set on block (#2022)
  • remove max-width on the callout number icon (#1895)
  • eagerly add hljs class for highlight.js (#2221)
  • fix SOURCE_DATE_EPOCH lookup in Opal
  • fix paths with file URI scheme are inevitably absolute (PR #1925) (@mogztter)
  • only resolve file URLs when JavaScript IO module is xmlhttprequest (PR #1898) (@mogztter)
  • fix formatting of video title in manpage converter
  • don't increment line number if peek_lines overruns buffer (fixes some cases when line number is off)
  • freeze extension processor instance, not class
  • fix numbering bug in reindex_sections
  • handle cases when there are no lines for include directive to select


  • enable admonition icons in README when displayed on GitHub
  • add German translation of chapter-label (PR #1920) (@fap-)
  • add Ukrainian translation of built-in attributes (PR #1955) (@hedrok)
  • add Norwegian Nynorsk translation; updated Norwegian Bokml translation of built-in attributes (PR #2142) (@huftis)
  • add Polish translation of built-in attributes (PR #2131) (@ldziedziul)
  • add Romanian translation of built-in attributes (PR #2125) (@vitaliel)
  • fix Japanese translation of built-in attributes (PR #2116) (@haradats)
  • add Bahasa Indonesia translation of built-in labels (@triyanwn)

Build / Infrastructure

  • upgrade highlight.js to 9.12.0 (#1652)
  • include entire test suite in gem (PR #1952) (@voxik)
  • upgrade Slim development dependency to 3.0.x (PR #1953) (@voxik)
  • upgrade Haml development dependency to 5.0.x
  • upgrade Nokogiri to 1.6.x (except on Ruby 1.8) (PR #1213)
  • add Ruby 2.4 to CI test matrix (PR #1980)
  • upgrade cucumber and JRuby in CI build (PR #2005)
  • fix reference to documentation in attributes.adoc (PR #1901) (@stonio)
  • trap and verify all warnings when tests are run with warnings enabled
  • set default task in build to test:all
  • configure script to run all tests
  • configure feature tests to only show progress
  • configure Slim in feature tests to use html as format instead of deprecated html5
  • lock version of yard to fix invalid byte sequence in Ruby 1.9.3
  • modify rake build to trigger dependent builds (specifically, Asciidoctor.js) (@mogztter) (PR #2305)

Release meta

Released on: 2017-07-12 Released by: @mojavelinux Release beer: Stickee Monkey (2017)

Logs: resolved issues | full diff


Thanks to the following people who contributed to this release:

@graphitefriction, @fap-, @vogella, @shahryareiv, @ricpelo, @mattadamson, @ceefour, @filiphr, @eikerethmeier, @robertpanzer, @gpakosz, @janicecmt, @cristoper, @jjaderberg, @getreu, @oncletom, @hsablonniere, @nerk, @megathaum, @k-mack, @jmini, @indigo423, @davidgamba, @sanmai-nl, @github-login, @deepaksingla14, @farleylai, @prudhomm, @littleancientforestkami, @zaxebo1, @lefou, @msc-, @jirutka, @elextr, @wolandscat, @lordofthejars, @lodestone, @asknet, @iandarwin, @jexp, @voxik, @kito99, @tduchateau, @owenh000, @mogztter, @jponge, @nathany, @jxxcarlson, @ramsey, @edoverflow, @pavs, @otavio, @rahmanusta, @sandersk, @hedrok, @huftis, @ldziedziul, @vitaliel, @haradats, @triyanwn, @stonio, and @letheed

Special thanks goes to @vogella and @fap-, both for their financial support of the project as well as critical insight and important patches to make the custom cross reference text feature happen.

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

v1.5.5 v1.5.5

Primarily a bug, compatibility, and security fix release, this update also introduces a full set of translations for built-in labels thanks to our awesome community! Additionally, during this release cycle, @diguage contributed a Chinese translation of the README and @Mizuho32 contributed a Japanese translation of the README.


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



  • Add preference to limit the maximum size of an attribute value (#1861)
  • Honor SOURCE_DATE_EPOCH environment variable to accomodate reproducible builds (@JojoBoulix) (#1721)
  • Add reversed attribute to ordered list if reversed option is enabled (#1830)
  • Add support for additional docinfo locations (e.g., :header)
  • Configure default stylesheet to break monospace word if exceeds length of line; add roles to prevent breaks (#1814)
  • Introduce translation file for built-in labels (@ciampix)
  • Provide translations for built-in labels in 21 languages:
    • kr - @JmyL
    • it - @ciampix
    • bg - @ivannov
    • da - @maxandersen
    • pt - @radcortez
    • es - @eddumelendez
    • jp - @leathersole
    • no - @aslakknutsen
    • fa - @shahryareiv
    • ru - @AlexanderZobkov
    • zh - @dongwq
    • pt_BR - @rmpestano
    • fr - @ncomet
    • fi - @lgvz
    • hu - @patoi
    • sr - @BojanStipic
    • de - @fwilhe
    • tr - @rahmanusta
    • ca - @abelsromero
    • ar - @aboullaite
    • nl - @roelvs
  • Translate README to Chinese (@diguage)
  • Translate README to Japanese (@Mizuho32)


  • Style nested emphasized phrases properly when using default stylesheet (#1691)
  • Honor explicit table width even when autowidth option is set (#1843)
  • Only explicit noheader option on table should disable implicit table header (#1849)
  • Support docbook orient=land attribute on tables (#1815)
  • Add alias named list to retrieve parent List of ListItem
  • Update push_include method to support chaining (#1836)
  • Enable font smoothing on Firefox on OSX (#1837)
  • Support combined use of sectanchors and sectlinks in HTML5 output (#1806)
  • fix API docs for find_by
  • Upgrade to Font Awesome 4.6.3 (@allenan, @mogztter) (#1723)
  • README: add install instructions for Alpine Linux
  • README: Switch yum commands to dnf in README
  • README: Mention Mint as a Debian distro that packages Asciidoctor
  • README: Add caution advising against using gem update to update a system-managed gem (@oddhack)
  • README: sync French version with English version (@flashcode)
  • Add missing endline after title element when converting open block to HTML
  • Move list_marker_keyword method from AbstractNode to AbstractBlock
  • Rename definition list to description list internally


  • Support 6-digit decimal char refs, 5-digit hexidecimal char refs (#1824)
  • Compatibility fixes for Opal
  • Check for number using Integer instead of Fixnum class for compatibility with Ruby 2.4

Bug fixes

  • Use method_defined? instead of respond_to? to check if method is already defined when patching (#1838)
  • Fix invalid conditional in HTML5 converter when handling of SVG
  • Processor#parse_content helper no longer shares attribute list between blocks (#1651)
  • Fix infinite loop if unordered list marker is immediately followed by a dot (#1679)
  • Don't break SVG source when cleaning if svg start tag name is immediately followed by endline (#1676)
  • Prevent template converter from crashing if .rb file found in template directory (#1827)
  • Fix crash when generating section ID when both idprefix & idseparator are blank (#1821)
  • Use stronger CSS rule for general text color in Pygments stylesheet (#1802)
  • Don't duplicate forward slash for path relative to root (#1822)


  • Build gem properly in the absense of a git workspace, make compatible with JRuby (#1779)
  • Run tests in CI using latest versions of Ruby, including Ruby 2.3 (@ferdinandrosario)

Release meta

Released on: 2016-10-05 Released by: @mojavelinux Release beer: Boulevard Rye-on-Rye X - Sazerac (2016)

Logs: resolved issues | full diff


Thanks to the following people who contributed to this release:

@JmyL, @ciampix, @ivannov, @maxandersen, @radcortez, @eddumelendez, @leathersole, @aslakknutsen, @shahryareiv, @AlexanderZobkov, @dongwq, @rmpestano, @ncomet, @lgvz, @patoi, @BojanStipic, @fwilhe, @rahmanusta, @abelsromero, @aboullaite, @roelvs, @gjtorikian, @thoragan, @pavs, @bk2204, @jojoboulix, @mogztter and @andya9.

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

Other projects in Ruby