Asciidoctor

An open source Ruby processor for converting AsciiDoc markup into HTML 5, DocBook 4.5 and other formats

= Hello, AsciiDoc!
Doc Writer <doc@example.com>

An introduction to http://asciidoc.org[AsciiDoc].

== First Section

* item 1
* item 2

[source,ruby]
puts "Hello, World!"

Asciidoctor is a pure Ruby processor for converting AsciiDoc source files and strings into HTML 5, DocBook 4.5 and other formats. It’s published as a RubyGem and is available under the MIT open source license.

Asciidoctor uses a set of built-in ERB templates to render the document to HTML 5 or DocBook 4.5. We’ve matched the rendered output as close as possible to the default output of the native Python processor. You can override this behavior by providing Tilt-compatible templates. See the Usage section for more details.

Asciidoctor currently works (read as tested) with Ruby 1.8.7, Ruby 1.9.3, Ruby 2.0.0, JRuby 1.7.5 and Rubinius 2.0 (on Linux, Mac and Windows). We expect it will work with other versions of Ruby as well and would welcome help in testing it out.

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 commit history of asciidoc.rb to view the initial contributions and contributors.

The source code can now be found in the Asciidoctor source repository on GitHub.

Installation

We’re working hard to make Asciidoctor a drop-in replacement for AsciiDoc. We’re very close, with over 700 tests that ensure compatibility. The march is on towards full compliance and beyond.

To install the gem:

gem install asciidoctor

Or if you prefer bundler, add the asciidoctor gem to your Gemfile,

source 'https://rubygems.org'
gem 'asciidoctor'

then install it using bundler:

bundle install

If you’re running Fedora, you can install the gem using yum:

sudo yum install rubygem-asciidoctor

The benefit of installing the gem via yum is that yum will also install Ruby if it’s not already on your machine.

Usage

Asciidoctor has both a command line interface (CLI) and an API. The CLI is a drop-in replacement for the asciidoc.py command from the Python implementation. The API is intended for integration with other software projects and is suitable for server-side applications, such as Rails, Sinatra and GitHub.

Command line interface (CLI)

After installing the asciidoctor gem, the asciidoctor commandline interface should be available on your PATH. To invoke it, simply 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.

Ruby API

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.

Loading a document

To parse a file into an Asciidoctor::Document object:

doc = Asciidoctor.load_file('your_file.asciidoc')

You can get information about the document:

puts doc.doctitle
puts doc.attributes

More than likely, you want to just render the document.

Rendering files

To render a file containing AsciiDoc markup to HTML 5:

Asciidoctor.render_file('your_file.asciidoc', :in_place => true)

The command will output to the file your_file.html in the same directory. You can render the file to DocBook 4.5 by setting the backend attribute to docbook:

Asciidoctor.render_file('your_file.asciidoc', :in_place => true,
  :attributes => {'backend' => 'docbook'})

The command will output to the file your_file.xml in the same directory. (If you’re on Linux, you can view the file using yelp).

Rendering strings

To render an AsciiDoc-formatted string:

puts Asciidoctor.render('*This* is it.')

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 it.', :header_footer => true)

Now you’ll get a full HTML 5 file. As before, you can also produce DocBook 4.5:

puts Asciidoctor.render('*This* is it.', :header_footer => true,
  :attributes => {'backend' => 'docbook'})

If you don’t like the output you see, you can change it. Any of it!

Custom templates

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 it.', :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 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.

Contributing

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

Submitting an Issue

We use the GitHub issue tracker 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.

Submitting a Pull Request

  1. Fork the repository.

  2. Create a topic branch.

  3. Add tests for your unimplemented feature or bug fix.

  4. Run bundle exec rake. If your tests pass, return to step 3.

  5. Implement your feature or bug fix.

  6. Run bundle exec rake. If your tests fail, return to step 5.

  7. Add documentation for your feature or bug fix.

  8. If your changes are not 100% documented, go back to step 7.

  9. Add, commit, and push your changes.

  10. Submit a pull request.

Supported Ruby Versions

This library aims to support the following Ruby implementations:

  • Ruby 1.8.7

  • Ruby 1.9.3

  • Ruby 2.0.0

  • JRuby 1.7.5

  • Rubinius 2.0

If something doesn’t work on one of these interpreters, it should be considered a bug.

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 personally responsible for providing 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.

Authors

AsciiDoc was written by Stuart Rackham and has received contributions from many other individuals.

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 Project

The Asciidoctor project, including this website, is an effort to bring a comprehensive and accessible documentation toolchain, centered around the AsciiDoc syntax, to the Ruby and JVM ecosystems.

In addition to an AsciiDoc processor and a collection of stylesheets, the project provides plugins for Maven, Gradle and Guard and packages for operating systems such as Fedora. It also pushes AsciiDoc to evolve by introducing new ideas and innovation and helps promote AsciiDoc through education and advocacy.

Download: Gem version
Development: GitHub
Discussions: Nabble
Chat (IRC): #asciidoctor on FreeNode
Twitter:
Google+: Asciidoctor

Contribute to asciidoctor.org

This website is open source! The source is hosted under the Asciidoctor organization on GitHub.

If you want to help by improving upon it, fork the project, revise the content, then send a pull request. When the pull request is merged, the site will be updated automatically.