Asciidoctor is an open source text processor and publishing toolchain for transforming AsciiDoc markup into HTML 5, DocBook 4.5 and 5.0 and other custom formats. Asciidoctor is written entirely in Ruby, packaged as a RubyGem and published to RubyGems.org. There are also Fedora, Debian and Ubuntu packages available for installing Asciidoctor. Asciidoctor is released under the MIT license.
Project health:
Asciidoctor reads and parses AsciiDoc markup (from a file or string) and feeds the parsed result to a set of built-in templates to render the document as HTML 5, DocBook 4.5 or DocBook 5.0. Asciidoctor is a drop-in replacement for the original AsciiDoc processor. We’ve matched the output to that produced by the AsciiDoc Python processor as faithfully as possible. You can override the built-in templates, or produce a custom format, by pointing the processor at a set of template files written in a language supported by Tilt. See the Usage section for more details.
|
Note
|
With few exceptions, Asciidoctor is compliant with the original AsciiDoc processor. Asciidoctor has well over 1,000 tests to ensure compatibility with the AsciiDoc syntax. We continue to work hard to ensure Asciidoctor continues to serve as a drop-in replacement for AsciiDoc. |
Asciidoctor requires one of the following implementations of Ruby:
-
Ruby 1.8.7
-
Ruby 1.9.3
-
Ruby 2.0.0
-
JRuby 1.7.5 (Ruby 1.8 and 1.9 modes)
-
Rubinius 2.1.1
-
Opal (JavaScript)
We expect Asciidoctor to work with other versions of Ruby as well. We welcome your help testing those versions if you are interested in seeing them supported.
The latest source code is located in the Asciidoctor git repository on GitHub.
Asciidoctor can be installed via the gem command, bundler, or popular Linux package managers.
To install Asciidoctor using the gem command:
-
Open a terminal
-
Type the gem command
$ gem install asciidoctor
To install Asciidoctor using bundler:
-
Open your system Gemfile
-
Add the asciidoctor gem to your Gemfile using the following text
source 'https://rubygems.org' gem 'asciidoctor'
-
Save the Gemfile
-
Open a terminal
-
Install the gem with bundler
$ bundle install
To install Asciidoctor on Fedora 17 or greater:
-
Open a terminal
-
Type the yum command
$ sudo yum install rubygem-asciidoctor
The benefit of installing the gem via yum is that the package manager will also install Ruby and RubyGems if not already on your machine.
To install Asciidoctor on Debian Sid or Ubuntu Saucy or greater:
-
Open a terminal
-
Type the apt-get command
$ sudo apt-get install asciidoctor
The benefit of installing the gem via apt-get is that the package manager will also install Ruby and RubyGems if not already on your machine.
If you have an earlier version of Asciidoctor installed, you can update it using the gem command:
$ gem update asciidoctor
|
Tip
|
If you accidentally use gem install instead of gem update then you will have both versions installed. If you wish to remove the older version use the gem command: $ gem cleanup asciidoctor |
On Fedora, you can update it using:
$ sudo yum update rubygem-asciidoctor
|
Tip
|
Your Fedora system may be configured to automatically update packages, in which case no further action is required by you. Refer to the Fedora docs if you are unsure. |
On Debian or Ubuntu, you can update it using:
$ sudo apt-get upgrade asciidoctor
|
Note
|
The Fedora, Debian and Ubuntu packages will not be available right away after a release of the RubyGem. It may take several weeks before the packages become available for a new release. If you need the latest version immediately, use the gem install option. |
If the Asciidoctor gem installed successfully, the asciidoctor command line interface (CLI) will be available on your PATH. To invoke it, execute:
$ asciidoctor --version
In the console, you should see:
Asciidoctor 0.1.4 [http://asciidoctor.org]
In addition to the CLI, Asciidoctor provides a Ruby API The API is intended for integration with other software projects and is suitable for server-side applications, such as Rails, Sinatra and GitHub.
|
Tip
|
Asciidoctor also has a Java API that mirrors the Ruby API. The Java API calls through to the Ruby API using an embedded JRuby runtime. See the Asciidoctor Java integration project for more information. |
Asciidoctor’s CLI is a drop-in replacement for the asciidoc.py command from the Python implementation. To invoke Asciidoctor from the CLI, execute:
asciidoctor <asciidoc_file>
This will use the built-in defaults for options and create a new file in the same directory as the input file, with the same base name, but with the .html extension.
There are many other options available and full help is provided via:
asciidoctor --help
or in the man page.
There is also an asciidoctor-safe command, which turns on safe mode by default, preventing access to files outside the parent directory of the source file. This mode is very similar to the safe mode of asciidoc.py.
Additional documentation:
To use Asciidoctor in your application, you first need to require the gem:
require 'asciidoctor'
With that in place, you can start processing AsciiDoc documents.
To parse a file into an Asciidoctor::Document object:
doc = Asciidoctor.load_file 'sample.adoc'
You can get information about the document:
puts doc.doctitle puts doc.attributes
More than likely, you will want to render the document.
To render a file containing AsciiDoc markup to HTML 5, use:
Asciidoctor.render_file 'sample.adoc', :in_place => true
The command will output to the file sample.html in the same directory.
You can render the file to DocBook 4.5 by setting the :backend option to 'docbook':
Asciidoctor.render_file 'sample.adoc', :in_place => true, :backend => 'docbook'
The command will output to the file sample.xml in the same directory. (If you’re on Linux, you can view the file using yelp).
To render an AsciiDoc-formatted string:
puts Asciidoctor.render '*This* is Asciidoctor.'
When rendering a string, the header and footer are excluded by default to make Asciidoctor consistent with other lightweight markup engines like Markdown. If you want the header and footer, just enable it using the :header_footer option:
puts Asciidoctor.render '*This* is Asciidoctor.', :header_footer => true
Now you’ll get a full HTML 5 file. If you only want the inline markup to be processed, set the :doctype option to 'inline':
puts Asciidoctor.render '*This* is Asciidoctor.', :doctype => 'inline'
As before, you can also produce DocBook 4.5:
puts Asciidoctor.render '*This* is Asciidoctor.', :header_footer => true, :backend => 'docbook'
If you don’t like the output you see, you can change it. Any of it!
Asciidoctor allows you to override the built-in templates used to render almost any individual AsciiDoc element. If you provide a directory of Tilt-compatible templates, named in such a way that Asciidoctor can figure out which template goes with which element, Asciidoctor will use the templates in this directory instead of its built-in templates for any elements for which it finds a matching template. It will fallback to its default templates for everything else.
puts Asciidoctor.render '*This* is Asciidoctor.', :header_footer => true, :template_dir => 'templates'
The Document and Section templates should begin with document. and section., respectively. The file extension is used by Tilt to determine which view framework it will use to use to render the template. For instance, if you want to write the template in ERB, you’d name these two templates document.html.erb and section.html.erb. To use Haml, you’d name them document.html.haml and section.html.haml.
Templates for block elements, like a Paragraph or Sidebar, would begin with block_<style>.. For instance, to override the default Paragraph template with an ERB template, put a file named block_paragraph.html.erb in the template directory you pass to the Document constructor using the :template_dir option.
For more usage examples, see the (massive) test suite.
Copyright © 2012-2013 Dan Allen and Ryan Waldron. Free use of this software is granted under the terms of the MIT License.
See the LICENSE file for details.
Asciidoctor was written by Dan Allen, Ryan Waldron, Jason Porter, Nick Hengeveld and other contributors.
The initial code from which Asciidoctor emerged was written by Nick Hengeveld to process the git man pages for the Git project site. Refer to the commit history of asciidoc.rb to view the initial contributions.
AsciiDoc was written by Stuart Rackham and has received contributions from many other individuals.
The Asciidoctor project is developed to help you sucessfully write and publish your content. But we can’t do that without your feedback! We encourage you to ask questions and discuss any aspects of the project on the mailing list or IRC.
- Mailing list
- Chat
-
#asciidoctor on FreeNode IRC
Further information and documentation about Asciidoctor can be found on the project’s website.
The Asciidoctor organization on GitHub hosts the project’s source code, issue tracker, and sub-projects.
- Source repository (git)
- Issue tracker (GitHub)
- Asciidoctor organization (GitHub)
If you discover errors or ommisions in the source code, documentation, or website content, please don’t hesitate to submit an issue or open a pull request with a fix. The Contributing section provides information on how to create, style, and submit issues, feature requests, code, and documentation to the Asciidoctor Project. New contributors are always welcome!
- Performance
-
-
15% increase in speed compared to 0.1.3
-
- Enhancements
-
-
updated xref inline macro to support inter-document references (#417)
-
added extension API for document processing (#79)
-
added include directive processor extension (#100)
-
added id and role shorthand for formatted (quoted) text (#517)
-
added shorthand syntax for specifying block options (#481)
-
added support for checklists in unordered list (#200)
-
added support for inline style for unordered lists (#620)
-
added DocBook 5 backend (#411)
-
added docinfo option for footer (#486)
-
added Pygments as source highlighter option (pygments) (#538)
-
added icon inline macro (#529)
-
recognize implicit table header row (#387)
-
uri can be used in inline image (#470)
-
add float attribute to inline image (#616)
-
allow role to be specified on text enclosed in backticks (#419)
-
added XML comment-style callouts for use in XML listings (#582)
-
made callout bullets non-selectable in HTML output (#478)
-
pre-wrap literal blocks, added nowrap option to listing blocks (#303)
-
skip (retain) missing attribute references by default (#523)
-
added attribute-missing attribute to control how a missing attribute is handled (#495)
-
added attribute-undefined attribute to control how an undefined attribute is handled (#495)
-
permit !name syntax for undefining attribute (#498)
-
ignore front matter used by static site generators if skip-front-matter attribute is set (#502)
-
sanitize contents of HTML title element in html5 backend (#504)
-
support toc position for toc2 (#467)
-
cli accepts multiple files as input (@lordofthejars) (#227)
-
added Markdown-style horizontal rules and pass Markdown tests (#455)
-
added float clearing classes (.clearfix, .float-group) (#602)
-
don’t disable syntax highlighting when explicit subs is used on listing block
-
asciidoctor package now available in Debian Sid and Ubuntu Saucy (@avtobiff) (#216)
-
- Compliance
-
-
embed CSS by default, copy stylesheet when linkcss is set unless copycss! is set (#428)
-
refactor reader to track include stack (#572)
-
made include directive resolve relative to current file (#572)
-
track include stack to enforce maximum depth (#581)
-
fixed greedy comment blocks and paragraphs (#546)
-
enable toc and numbered by default in DocBook backend (#540)
-
ignore comment lines when matching labeled list item (#524)
-
correctly parse footnotes that contain a URL (#506)
-
parse manpage metadata, output manpage-specific HTML, set docname and outfilesuffix (#488, #489)
-
recognize preprocessor directives on first line of AsciiDoc table cell (#453)
-
include directive can retrieve data from uri if allow-uri-read attribute is set (#445)
-
support escaping attribute list that precedes formatted (quoted) text (#421)
-
made improvements to list processing (#472, #469, #364)
-
support percentage for column widths (#465)
-
substitute attributes in docinfo files (#403)
-
numbering no longer increments on unnumbered sections (#393)
-
fixed false detection of list item with hyphen marker
-
skip include directives when processing comment blocks
-
added xmlns to root element in docbook45 backend, set noxmlns attribute to disable
-
added a Compliance module to control compliance-related behavior
-
added linkattrs feature to AsciiDoc compatibility file (#441)
-
added level-5 heading to AsciiDoc compatibility file (#388)
-
added new XML-based callouts to AsciiDoc compatibility file
-
added absolute and uri image target matching to AsciiDoc compatibility file
-
added float attribute on inline image macro to AsciiDoc compatibility file
-
removed linkcss in AsciiDoc compatibility file
-
fixed fenced code entry in compatibility file
-
- Bug Fixes
-
-
lowercase attribute names passed to API (#508)
-
numbered can still be toggled even when enabled in API (#393)
-
allow JRuby Map as attributes (#396)
-
don’t attempt to highlight callouts when using CodeRay and Pygments (#534)
-
correctly calculate line length in Ruby 1.8 (#167)
-
write to specified outfile even when input is stdin (#500)
-
only split quote attribution on first comma in Markdown blockquotes (#389)
-
don’t attempt to print render times when doc is not rendered
-
don’t recognize line with four backticks as a fenced code block (#611)
-
- Improvements
-
-
upgraded Font Awesome to 3.2.1 (#451)
-
improved the built-in CodeRay theme to match Asciidoctor styles
-
link to CodeRay stylesheet if linkcss is set (#381)
-
style the video block (title & margin) (#590)
-
added Groovy, Clojure, Python and YAML to floating language hint
-
only process callouts for blocks in which callouts are found
-
added content_model to AbstractBlock, rename buffer to lines
-
use Untitled as document title in rendered output if document has no title
-
rename include-depth attribute to max-include-depth, set 64 as default value (#591)
-
the tag attribute can be used on the include directive to identify a single tagged region
-
output multiple authors in HTML backend (#399)
-
allow multiple template directories to be specified, document in usage and manpage (#437)
-
added option to cli to specify template engine (#406)
-
added support for external video hosting services in video block macro (@xcoulon) (#587)
-
strip leading separator(s) on section id if idprefix is blank (#551)
-
customized styling of toc placed inside body content (#507)
-
consolidate toc attribute so toc with or without toc-position can make sidebar toc (#618)
-
properly style floating images (inline & block) (#460)
-
add float attribute to inline images (#616)
-
use ul list for TOC in HTML5 backend (#431)
-
support multiple terms per labeled list item in model (#532)
-
added role?, has_role?, option? and roles methods to AbstractNode (#423, 474)
-
added captioned_title method to AbstractBlock
-
honor showtitle attribute as alternate to notitle! (#457)
-
strip leading indent from literal paragraph blocks assigned the style normal
-
only process lines in AsciiDoc files
-
emit message that tilt gem is required to use custom backends if missing (#433)
-
use attributes for version and last updated messages in footer (#596)
-
added a basic template cache (#438)
-
include line info in several of the warnings (for lists and tables)
-
print warning/error messages using warn (#556)
-
lines are not preprocessed when peeking ahead for section underline
-
introduced Cursor object to track line info
-
fixed table valign classes, no underline on image link
-
removed dependency on pending library, lock Nokogiri version to 1.5.10
-
removed require rubygems line in asciidoctor.rb, add to cli if RUBY_VERSION < 1.9
-
added tests for custom backends
-
added test that shorthand doesn’t clobber explicit options (#481)
-
removed unnecessary monospace class from literal and listing blocks
-
See the CHANGELOG.adoc file for a list of changes in older releases as well as for the upcoming release.
In the spirit of free software, everyone is encouraged to help improve this project.
Here are some ways you can contribute:
-
by using alpha, beta, and prerelease 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 issues
-
by reviewing patches
We use the issue tracker on GitHub associated with this project to track bugs and features. Before submitting a bug report or feature request, check to make sure it hasn’t already been submitted. When submitting a bug report, please include a Gist that includes any details that may help reproduce the bug, including your gem version, Ruby version, and operating system.
Most importantly, since Asciidoctor is a text processor, reproducing most bugs requires that we have some snippet of text on which Asciidoctor exhibits the bad behavior.
An ideal bug report would include a pull request with failing specs.
-
Run bundle install to install dependencies.
-
Add tests for your unimplemented feature or bug fix. (See Writing and Executing Tests)
-
Run bundle exec rake to run the tests. If your tests pass, return to step 3.
-
Implement your feature or bug fix.
-
Run bundle exec rake to run the tests. If your tests fail, return to step 5.
-
Add documentation for your feature or bug fix.
-
If your changes are not 100% documented, go back to step 7.
-
Add, commit, and push your changes.
Tests live inside the test directory and are named <topic>_test.rb. For instance, tests for the different types of blocks can be found in the file test/blocks_test.rb.
Within a test file, individual test cases are organized inside of contexts. A context is type of logical container that groups related tests together.
Each test case follows the same structure:
test 'description of test' do # test logic end
At the moment, the tests are quite primitive. Here’s how a typical test operates:
-
Defines sample AsciiDoc source
-
Renders the document to HTML or DocBook
-
Uses XPath and CSS expressions to verify expected output
Here’s how we might test the open block syntax:
test 'should render content bounded by two consecutive hyphens as an open block' do input = <<-EOS -- This is an open block. -- EOS result = render_embedded_string input assert_css '.openblock', result, 1 assert_css '.openblock p', result, 1 assert_xpath '/div[@class="openblock"]//p[text()="This is an open block."]', result, 1 end
As you can see, several helpers are used to facilitate the test scenario. The render_embedded_string invokes Asciidoctor’s render method with the header and footer option disabled. This method is ideal for unit-level tests. If you need to test the whole document, use render_string instead. The assert_css and assert_xpath assertion methods take a CSS or XPath selector, respectively, the rendered result and the number of expected matches. You can also use built-in assertions in Ruby’s test library.
To run all the tests, simply execute rake:
$ rake
If you want to run a single test file, you can use testrb:
$ testrb test/blocks_test.rb
To test a single test case, first add the string "wip" to the beginning of the description. For example:
test 'wip should render ...' do ... end
Then, run testrb again, but this time pass a selector argument so it finds matching tests:
$ testrb test/blocks_test.rb -n /wip/
Once you are done with your test, make sure to remove "wip" from the description and run all the tests again using rake.
We plan on switching to a more elegant testing framework in the future, such as RSpec or Cucumber, in order to make the tests more clear and robust.
If you would like this library to support another Ruby version, you may volunteer to be a maintainer. Being a maintainer entails making sure all tests run and pass on that implementation. When something breaks on your implementation, you will be expected to provide patches in a timely fashion. If critical issues for a particular implementation exist at the time of a major release, support for that Ruby version may be dropped.