Instructions for configuring AsciiDoc in Middleman 3.

middleman-asciidoctor.adoc

How to enable AsciiDoc in a Middleman 3 site

Follow these steps to setup AsciiDoc in a Middleman 3 site.

Note	Middleman 4 will require the use of the middleman-asciidoc gem.

1. Install middleman

   $ gem install middleman

2. Create a new project

   $ middleman init sample

3. Add Asciidoctor (asciidoctor) to the Gemfile

   Gemfile

   source 'https://rubygems.org'
   
   gem 'middleman', '~> 3.3.7'
   
   # Live-reloading plugin
   gem 'middleman-livereload', '~> 3.4.2'
   
   # For faster file watcher updates on Windows:
   gem 'wdm', '~> 0.1.0', :platforms => [:mswin, :mingw]
   
   # Windows does not come with time zone data
   gem 'tzinfo-data', :platforms => [:mswin, :mingw]
   
   # Activate support for AsciiDoc
   gem 'asciidoctor', '~> 1.5.2'

4. Configure Asciidoctor

   config.rb

   set :asciidoc_attributes, %w(source-highlighter=coderay coderay-css=style)
   
   ...

5. Create an AsciiDoc page

   source/sample.adoc

   = Rendered by Asciidoctor
   Author Name
   :page-layout: layout (1)
   
   Learn more about Asciidoctor at http://asciidoctor.org.

   1. Optionally specify the page layout using the page-layout attribute

6. Run the preview server

   $ middleman

7. Visit the AsciiDoc page at http://localhost:4567/sample.html

There you have it! You can now write any page in AsciiDoc!

You can also add this to your config.rb for using an :asciidoc filter for inline AsciiDoc in HAML:

# Add an AsciiDoc filter to HAML
# (Use ':asciidoc' for AsciiDoctor-powered blocks in HAML)
Haml::Filters.register_tilt_filter "AsciiDoc"

(It's basically like HAML's Markdown filters, but using AsciiDoc instead.)