Jekyll AsciiDoc Plugin (powered by Asciidoctor)

A Jekyll plugin that converts AsciiDoc files in your site source to HTML pages using Asciidoctor.

The plugin consists of three extensions:

Jekyll::Converters::AsciiDocConverter

Converts AsciiDoc files to HTML

Jekyll::Generators::AsciiDocPreprocessor

Promotes select AsciiDoc attributes to Jekyll front matter (e.g., title, author, page-layout)

Jekyll::Filters.asciidocify

A Liquid filter for converting AsciiDoc content to HTML using the AsciiDocConverter

All these extensions are included in the file lib/asciidoc_plugin.rb.

Installation

The plugin depends on the Asciidoctor gem (named asciidoctor). You can install the gem using:

$ gem install asciidoctor

If you are using Bundler to manage the dependencies in your Jekyll project, then add the Asciidoctor gem to your Gemfile (below the Jekyll gem, named jekyll):

source 'https://rubygems.org'

gem 'jekyll'
gem 'asciidoctor'

Then, run the Bundler install command

$ bundle install

Installing a released version of the plugin

Using Bundler

Add jekyll-asciidoc plugin gem to your Gemfile

group :jekyll_plugins do
  gem "jekyll-asciidoc"
end

Then, run the Bundler command to install it:

$ bundle install

Without Bundler

If you are not using Bundler for managing Jekyll then install gems manually

$ gem install jekyll-asciidoc

And then, add jekyll-asciidoc gem to the list of gems for Jekyll to load in your site’s _config.yml file:

gems:
  - jekyll-asciidoc

Installing development version of the plugin

To install the development version of this plugin, copy lib/asciidoc_plugin.rb to the _plugins directory in the root of your site source.

Note	If no _plugins directory exists, you need to first create it.

Creating Pages

To add a page composed in AsciiDoc, simply add an AsciiDoc file to the root of the project with an AsciiDoc file extension.

sample.adoc

---
---
= Sample Page
:layout: page
:permalink: /page/

This is a sample page composed in AsciiDoc.
Jekyll converts it to HTML using http://asciidoctor.org[Asciidoctor].

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

Important

The AsciiDoc file must have a YAML front matter header or else it won’t be recognized as a page. You can use an empty front matter header, as shown above, or you can define all your document metadata (e.g., document title) in the front matter instead of AsciiDoc attributes.

You can now build your site using:

$ jekyll build

and preview it using:

$ jekyll serve

If you are using Bundler then use following commands to do the same

$ bundle exec jekyll build
$ bundle exec jekyll serve

Important

If you use the --safe option, the AsciiDoc plugin will not be activated. The --safe flag disables third-party plugins such as this one.

Configuration (Optional)

By default, this plugin uses Asciidoctor to convert AsciiDoc files. Since Asciidoctor is the only option, the default setting is equivalent to the following configuration in _config.yml:

asciidoc: asciidoctor

To tell Jekyll which extensions to recognize as AsciiDoc files, add the following line to your _config.yml:

asciidoc_ext: asciidoc,adoc,ad

The extensions shown in the previous listing are the default values, so you don’t need to specify this option if those defaults are sufficient.

To pass additional attributes to AsciiDoc, or override the default attributes defined in the plugin, add the following lines to your _config.yml:

asciidoctor:
  attributes:
    - hardbreaks!
    - source-highlighter=pygments
    - pygments-css=style

Hard line breaks

The Jekyll AsciiDoc integration is configured to preserve hard line breaks in paragraph content by default. Since many Jekyll users are used to writing in GitHub-flavored Markdown (GFM), this default was selected to ease the transition to AsciiDoc. If you want the standard AsciiDoc behavior of collapsing hard line breaks in paragraph content, add the following settings to your site’s _config.yml file:

asciidoctor:
  attributes:
    - hardbreaks!

If you already have AsciiDoc attributes defined in the _config.yml, the hardbreaks! attribute should be added as a sibling entry in the YAML collection.

GitHub Pages

GitHub doesn’t (yet) whitelist the AsciiDoc plugin, so you can only run it on your own machine.

Tip	GitHub needs to hear from enough users that they want to plugin in order to enable it. Our recommendation is to keep lobbying for them to enable it.

You can automate publishing of the generated site to GitHub Pages using a continuous integration job. Refer to the tutorial Automate GitHub Pages publishing with Jekyll and Travis CI to find step-by-step instructions to setup this job. You can also refer to the Tranfuse website build for an example in practice.

Refer to the Jekyll Plugins on GitHub Pages for a list of the plugins currently supported on the server-side (in addition to Markdown, which isn’t listed).