Asciidoctor

Asciidoctor is a pure-ruby processor for turning
Asciidoc documents
into HTML (and, eventually, other formats perhaps).

Asciidoctor uses simple built-in ERB templates to style the output in
a way that roughly matches the default HTML 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 with Ruby 1.8.7 and 1.9.3, though I don’t
know of any reason it shouldn’t work with more exotic Ruby versions,
and would welcome help in testing that out.

The initial code from which asciidoctor started was from the Git SCM
site repo.

Installation

NOTE: This gem is very immature, and as yet only supports a small
subset of Asciidoc features. Thus, you should only use it if you have
a high tolerance for bugs, failures, and generally bad and intemperate
behavior.

To install the gem:

gem install ‘asciidoctor’

Or if you prefer bundler:

bundle install ‘asciidoctor’

Usage

To render a file of Asciidoc-marked-up text to html

lines = File.readlines(“your_file.asc”)
doc = Asciidoctor::Document.new(lines)
html = doc.render
File.open(“your_file.html”, “w+”) do |file|
file.puts html
end

Render an Asciidoc-formatted string

doc = Asciidoctor::Document.new(“This is it.”)
puts doc.render

Asciidoctor allows you to override the default template used to render
almost any individual Asciidoc elements. If you provide a directory of
Tilt-compatible templates, named in a way 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 use its
default templates for everything else.

doc = Asciidoctor::Document.new(“This is it.”, :template_dir => ‘templates’)
puts doc.render

The Document and Section templates should begin with document. and
section., respectively. The file extension will depend on which
Tilt-compatible format you’ve chosen. For ERB, they would be
document.html.erb and section.html.erb, for instance.

Specific elements, like a Paragraph or Anchor, would begin with
section_.. So to override the default Paragraph template
with an ERB template you’d put a file called
section_paragraph.html.erb in the template directory you pass in to
Document.new.

For more usage examples, see the 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)
by refactoring code
by fixing issues
by reviewing patches

Submitting an Issue

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

Fork the repository.
Create a topic branch.
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.
Submit a pull request.

Supported Ruby Versions

This library aims to support the following Ruby implementations:

Ruby 1.8.7
Ruby 1.9.3

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.

Modules

Classes