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.4
-
Rubinius 2.0 - testing suspended until a release is available
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 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!
- Enhancements
-
-
added support for inline rendering by setting doctype to inline (#328)
-
added support for using font-based icons (#115)
-
honor haml/slim/jade-style shorthand for id and role attributes (#313)
-
support Markdown-style headings as section titles (#373)
-
support Markdown-style quote blocks
-
added section level 5 (maps to h6 element in the html5 backend) (#334)
-
added btn inline macro (#259)
-
added menu inline menu to identify a menu selection (@bleathem) (#173)
-
added kbd inline macro to identify a key or key combination (@bleathem) (#172)
-
support alternative quote forms (#196)
-
added indent attribute to verbatim blocks (#365)
-
added prettify source-highlighter (#202)
-
link section titles (#122)
-
introduce shorthand syntax for table format (#350)
-
parse attributes in link when use-link-attrs attribute is set (#214)
-
support preamble toc-placement (#295)
-
exclude attribute div if quote has no attribution (#309)
-
support attributes passed to API as string or string array (#289)
-
allow safe mode to be set using string, symbol or int in API (#290)
-
make level 0 section titles more prominent in TOC (#369)
-
- Compliance
-
-
~ 99.5% compliance with AsciiDoc
-
drop line if target of include directive is blank (#376)
-
resolve attribute references in target of include directive (#367)
-
added irc scheme to link detection (#314)
-
toc should honor numbered attribute (#341)
-
added toc2 layout to default stylesheet (#285)
-
consecutive terms in labeled list share same entry (#315)
-
support set:name:value attribute syntax (#228)
-
block title not allowed above document title (#175)
-
assign caption even if no title (#321)
-
horizontal dlist layout in docbook backend (#298)
-
set doctitle attribute (#337)
-
allow any backend to be specified in cli (@lightguard) (#320)
-
support for abstract and partintro (#297)
-
- Bug Fixes
-
-
fixed file path resolution on Windows (#330)
-
fixed bad variable name that was causing crash, add test for it (#335)
-
set proper encoding on input data (#308)
-
don’t leak doctitle into nested document (#382)
-
handle author(s) defined using attributes (#301)
-
- Improvements
-
-
added tests for all special sections (#80)
-
added test for attributes defined as string or string array (@lightguard) (#291)
-
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.
-
Add tests for your unimplemented feature or bug fix.
-
Run bundle exec rake. If your tests pass, return to step 3.
-
Implement your feature or bug fix.
-
Run bundle exec rake. 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.
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.