Asciidoctor Mallard: A Project Mallard converter for AsciiDoc

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.

Notable Features

• Direct AsciiDoc to Mallard conversion

• Configuration-driven style and layout

• Document metadata (title, authors, subject, keywords, etc)

• Internal cross reference links

• Page breaks avoided in block content

• Orphan section titles avoided

• Table border settings honored

Missing Features

See WORKLOG.

Prerequisites

All that’s needed is Ruby 1.9.3 or better (2.1.5 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.1@asciidoctor-mallard --create

We like RVM because it keeps the dependencies required by various projects isolated.

Getting Started

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.

Retrieve the source code

You can retrieve the Asciidoctor Mallard project in one of two ways:

1. Clone the git repository

2. Download a zip archive of the repository

Option 1: Fetch using git clone

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

Option 2: Download the archive

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.

Install the 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.

Example AsciiDoc document

If you don’t already have an AsciiDoc document, you can use the example.adoc file found in the examples directory of this project.

example.adoc

= 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 2

It’s time to convert the AsciiDoc document directly to Mallard.

Convert AsciiDoc 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.

Contributing

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.

Authors

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

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.

For the full text of the license, see the LICENSE file. Refer to the NOTICE file for information about third-party Open Source software in use.