Middleman AsciiDoc (gem: middleman-asciidoc) is an extension for the Middleman static site generator that adds support for the AsciiDoc lightweight markup language. Specifically, this extension converts AsciiDoc files in your site source to HTML pages. This conversion is performed using Asciidoctor by default.

Important
This extension is designed for Middleman >= 4.0.0. Prior to Middleman 4, AsciiDoc support was part of Middleman core.

Installation

If you’re just getting started, install the Middleman gem:

$ NOKOGIRI_USE_SYSTEM_LIBRARIES=1 gem install middleman

then generate a new project:

$ middleman init MY_PROJECT

If you’re working with an existing project, you can skip the previous steps.

Next, add the gem for this extension to your project’s Gemfile.

gem 'middleman-asciidoc'

Finally, run Bundler using the bundle command:

$ bundle

You’re now ready to activate this extension and begin putting it to work.

Activation and Configuration

activate :asciidoc

You can also pass AsciiDoc configuration options to the underlying Asciidoctor processor:

activate :asciidoc, attributes: ['source-highlighter=coderay']

The following option keys from the Asciidoctor API can be added to the Hash of the second argument to activate:

attributes (type: Hash or Array, default: [])

Custom AsciiDoc attributes to pass to the processor. The following implicit attributes are automatically appended to this collection.

  • env=site

  • env-site

  • site-gen=middleman

  • site-gen-middleman

  • builder=middleman

  • builder-middleman

  • middleman-version=(value of Middleman::VERSION constant)

  • imagesdir=(value of http_prefix + images_dir in app config)@

    • skipped if !imagesdir is defined as a custom attribute

    • can be overridden in page (hence the trailing @)

backend (type: Symbol, default: :html5)

The moniker for a converter, which determines the output format to generate.

base_dir (type: String, default: nil)

The base directory to use for the current AsciiDoc document; if not specified, defaults to the document directory (i.e., docdir). To set the base directory to the source directory, use the value app.source_dir.expand_path.

safe (type: Symbol, default: :safe)

The safe mode level under which to run the AsciiDoc processor.

Tip
The full set of options can be seen on your preview server’s config page at the path /__middleman/config/.

Creating Pages

Each AsciiDoc file in the source directory (except for files that begin with +_+ or which are located in a directory that begins with +_+) becomes a page in the site. AsciiDoc files can have the file extension .adoc or .html.adoc. These extensions are stripped and replaced with the value of the outfilesuffix attribute, which defaults to .html.

Note
For details about how the file extension is substituted, see the discussion in issue #7.

To add a page composed in AsciiDoc, simply add an AsciiDoc file that has one of the aforementioned AsciiDoc file extensions to the project source directory.

sample.adoc
= Sample Page
:page-layout: page
:uri-asciidoctor: http://asciidoctor.org

This is a sample page composed in AsciiDoc.
The Middleman AsciiDoc extension converts it to HTML using {uri-asciidoctor}[Asciidoctor].

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

Adding Custom Page Data

AsciiDoc attributes defined in the document header whose names begin with page- are promoted to page data (aka front matter). The part of the name after the page- prefix is used as the entry’s key (e.g., page-layout becomes layout). The value is parsed as YAML data (that which can be expressed in a single line).

In addition to these explicit page attributes, the following AsciiDoc attributes are also promoted to page data:

  • doctitle (i.e., the document title) (becomes title)

  • author

  • email

  • revdate (becomes date; value is converted to a DateTime object)

Tip
You can continue to specify page data using the front matter header. The AsciiDoc page- attributes override matching entries in the front matter header.

Specifying a Layout

The most important of these page attributes is page-layout, which determines the layout that is applied to the page. Middleman will look for the first file that matches this root name under the source directory and use it as the layout. For example, if page-layout has the value page, Middleman might resolve a layout named page.erb. You can fix the extension of the layout file using the page-layout-engine attribute.

If a layout is not specified, or the value of the page-layout attribute is empty, the default layout for the site is used.

If the page-layout attribute is unset, the AsciiDoc processor will generated a standalone document (header_footer: true). In this case, the page will appear like an HTML file that is generated by the AsciiDoc processor directly.

To review, here are the different ways to specify a layout:

  • :page-layout: default — use the page layout named "default" (e.g., default.erb)

  • :!page-layout: — no layout; generate a standalone HTML document

  • :page-layout: — use the auto-detected layout

  • (not specified) — use the auto-detected layout

Warning
Layout for blog posts
If you’re using the Middleman Blog extension to write blog posts, you must specify the page layout using the page-layout attribute for each post written in AsciiDoc. Otherwise, an exception will be thrown. This requirement will be lifted once the fix for issue middleman-blog#296 makes it into a release.

Building Your Site

You can now build your site using:

$ middleman build

or preview it using:

$ middleman serve

If you’re using Bundler, use the following commands instead:

$ bundle exec middleman build
$ bundle exec middleman serve

Community

The official community forum for Middleman can be found at http://forum.middlemanapp.com. For questions related to this extension or general questions about AsciiDoc, please post to the Asciidoctor discussion list at http://discuss.asciidoctor.org.

Bug Reports

Github Issues are used for managing bug reports and feature requests. If you run into issues, please search the issues and submit new problems in the project’s issue tracker.

The best way to get quick responses to your issues and swift fixes to your bugs is to submit detailed bug reports, include test cases and respond to developer questions in a timely manner. Even better, if you know Ruby, you can submit pull requests containing Cucumber Features which describe how your feature should work or exploit the bug you are submitting.

How to Run Tests

The tests are based on Cucumber. Here’s how to clone the project and run the tests.

  1. Clone the repository:

    $ git clone https://github.com/middleman/middleman-asciidoc.git &&
      cd middleman-asciidoc
    
  2. Install Bundler (if not already installed):

    $ gem install bundler
    
  3. Run Bundler (from the project root) to install the gem dependencies:

    $ bundle
    
  4. Run test cases (based on Cucumber) using Rake:

    $ bundle exec rake cucumber
    

Copyright © 2014-2016 Dan Allen 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.