|
Caution
|
Project status
Asciidoctor Mallard is currently alpha software.
Use accordingly.
Though the bulk of AsciiDoc content is converted, there’s still work needed to fill in gaps where conversion is incomplete, incorrect or not implemented.
Once it’s ready, the project will be moved into the Asciidoctor organization on GitHub.
|
See WORKLOG.
All that’s needed is Ruby 2.0 or better (2.2 recommended) and a few RubyGems, which we explain how to install in the next section.
To check you have Ruby available, use the ruby command to query the version installed:
$ ruby --version
If you’re using RVM, we recommend creating a new gemset to work with Asciidoctor and Asciidoctor Mallard:
$ rvm use 2.2@asciidoctor-mallard --create
We like RVM because it keeps the dependencies required by various projects isolated.
The Asciidoctor Mallard project is published in pre-release on RubyGems.org. You can either install the pre-release version using the following command:
$ gem install --pre asciidoctor-mallard
Assuming all the required gems install properly, verify you can run the asciidoctor-mallard script:
$ asciidoctor-mallard -v
If you see the version of Asciidoctor Mallard printed, you’re ready to use Asciidoctor Mallard!
Skip ahead to the Example AsciiDoc document section to start putting Asciidoctor Mallard to use. Alternatively, you can follow the steps below to install the project from source.
You can retrieve the Asciidoctor Mallard project in one of two ways:
-
Clone the git repository
-
Download a zip archive of the repository
If you want to clone the git repository, simply copy the GitHub repository URL and pass it to git clone command:
$ git clone https://github.com/asciidoctor/asciidoctor-mallard
Next, change to the project directory:
$ cd asciidoctor-mallard
If you want to download a zip archive, click the Download Zip button on the right-hand side of the repository page on GitHub. Once the download finishes, extract the archive, open a console and change to that directory.
|
Tip
|
Instead of working out of the asciidoctor-mallard directory, you can simply add the absolute path of the bin directory to your PATH environment variable.
|
We’ll leverage the project configuration to install the necessary dependencies.
The dependencies needed to use Asciidoctor Mallard are defined in the Gemfile at the root of the project. We can use Bundler to install the dependencies for us.
To check you have Bundler available, use the bundle command to query the version installed:
$ bundle --version
If it’s not installed, use the gem command to install it.
$ gem install bundler
Then use the bundle command to install the project dependencies:
$ bundle
Assuming all the required gems install properly, verify you can run the asciidoctor-mallard script using Ruby:
$ ruby ./bin/asciidoctor-mallard -v
If you see the version of Asciidoctor Mallard printed, you’re ready to use Asciidoctor Mallard!
Let’s grab an AsciiDoc document to distill.
If you don’t already have an AsciiDoc document, you can use the example.adoc file found in the examples directory of this project.
= Document Title
Doc Writer <doc@example.com>
:doctype: book
:source-highlighter: coderay
:listing-caption: Listing
A simple http://asciidoc.org[AsciiDoc] document.
== Introduction
A paragraph followed by a simple list with square bullets.
[square]
* item 1
* item 2It’s time to convert the AsciiDoc document directly to Mallard.
Converting to Mallard is a simple as running the ./bin/asciidoctor-mallard script using Ruby and passing our AsciiDoc document as the first argument.
$ ruby ./bin/asciidoctor-mallard example.adoc
When the script completes, you should see the file example.page in the same directory.
|
Important
|
You’ll need to the coderay gem installed to run this example since it uses the source-highlighter attribute with the value of coderay.
|
Open the example.page file with yelp to see the result.
You’re also encouraged to try converting this README as well as the documents in the examples directory to see more of what Asciidoctor Mallard can do. Another good example is the CDI Specification.
In the spirit of free software, everyone is encouraged to help improve this project.
To contribute code, simply fork the project on GitHub, hack away and send a pull request with your proposed changes.
Feel free to use the issue tracker or Asciidoctor mailing list to provide feedback or suggestions in other ways.
Asciidoctor Mallard was written by brian m. carlson on behalf of the Asciidoctor Project. It is derived in part from the AsciiDoc Mallard Backend and the Asciidoctor DocBook and PDF backends.
Copyright © 2013-2015 Daniele Pezzini, brian m. carlson, and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License.