Asciidoctor is a pure-Ruby processor for turning AsciiDoc documents or strings into HTML (and, eventually other formats as well…'stay tuned!').
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.
|
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
To render a file containing AsciiDoc markup to HTML:
lines = File.readlines('your_file.asciidoc')
doc = Asciidoctor::Document.new(lines)
html = doc.render
File.open('your_file.html', 'w+') do |file|
file.puts html
end
To 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 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.
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, the template names would be
document.html.erb and section.html.erb, for instance. For Haml, they
would be document.html.haml and section.html.haml.
Templates for specific elements, like a Paragraph or Anchor, would begin
with section_<element>.. For instance, to override the default Paragraph
template with an ERB template, 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.
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, etc.)
-
by refactoring code
-
by fixing issues
-
by reviewing patches
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.
-
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.
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.
Copyright (c) 2012 Ryan Waldron. See LICENSE for details.