Overview

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

These extensions are loaded automatically when the jekyll-asciidoc is required.

Installation

The plugin depends on the asciidoctor gem. You can install the gem using:

$ gem install asciidoctor

If you’re using Bundler to manage the dependencies in your Jekyll project, instead add the asciidoctor gem to your Gemfile (beneath the jekyll gem):

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 the 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 the 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, use:

$ rake install

An alternative—​though not recommend—​approach is to copy the file lib/jekyll-asciidoc.rb to the _plugins directory in the root of your site source.

Note
 If the _plugins directory does not exist, 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

Disabling 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.

Enabling Asciidoctor Diagram (optional)

Asciidoctor Diagram is a set of extensions for Asciidoctor that allow you to embed diagrams written using the PlantUML, Graphviz, ditaa, or Shaape syntax inside your AsciiDoc documents.

Important
 For Graphviz and PlantUML diagram generation, Graphviz must be installed (i.e., the dot utility must be available on your $PATH.

Installation

Using Bundler

Add asciidoctor-diagram gem to your Gemfile

group :jekyll_plugins do
  ....
  gem 'asciidoctor-diagram', '>= 1.3.1' <b class="conum">(1)</b>
  ...
end

  1. version can be configured differently

Then, run the Bundler command to install it:

$ bundle install
Without Bundler

Install gems manually

$ gem install asciidoctor-diagram

Then, add the asciidoctor-diagram gem to the list of gems for Jekyll to load in your site’s _config.yml file:

gems:
  - asciidoctor-diagram

Both of the previous configurations are the equivalent of passing -r asciidoctor-diagram to the asciidoctor command.

Generated image location

By default diagram images are generated in the root folder. Thus, images URLs are not properly referenced from the generated HTML pages.

To fix this, set the imagesdir attribute in any AsciiDoc file that contains diagrams.

_posts/2015-12-24-diagrams.adoc
---
---
= Diagrams
:imagesdir: /images/2015-12-24 <b class="conum">(1)</b>

[graphviz, dot-example, svg]
----
digraph g {
    a -> b
    b -> c
    c -> d
    d -> a
}
----

  1. the date in the imagesdir value must match the date of the post (e.g., 2015-12-24)

Warning
 The images are generated after Jekyll copies assets to the _site directory. Therefore, you’ll have to run jeykll twice before you see the images in the preview.

Supplemental AsciiDoc Assets

Certain Asciidoctor features, such as icons, require additional CSS rules and other assets to work. These CSS rules and other assets do not get automatically included in the pages generated by Jekyll. This section documents how to configure these additional resources.

Tip
 If you want to take a shortcut that skips all this configuration, clone the Jekyll AsciiDoc Quickstart (JAQ) repository and use it as a starting point for your site. JAQ provides a page layout out of the box configured to fully style body content generated from AsciiDoc.

Setup

The Jekyll AsciiDoc plugin converts AsciiDoc to embeddable HTML. This HTML is then inserted into the page layout. You need to augment the page layout to include resources typically present in a standalone HTML document that Asciidoctor produces.

  1. Create a stylesheet in the css directory named asciidoc.css to hold additional CSS for body content generated from AsciiDoc.

  2. Add this stylesheet to the HTML <head> in _includes/head.html under the main.css declaration:

    <link rel="stylesheet" href="{{ "/css/asciidoc.css" | prepend: site.baseurl }}">

Font-based Admonition and Inline Icons

To enable font-based admonition and inline icons, you first need to add Font Awesome to _includes/head.html file under the asciidoc.css declaration:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.4.0/css/font-awesome.min.css">
Note
 You can also link to local copy of Font Awesome.

Next, you need to add the following CSS rules from the default Asciidoctor stylesheet to the css/asciidoc.css file:

span.icon>.fa {
  cursor: default;
}
.admonitionblock td.icon {
  text-align: center;
  width: 80px;
}
.admonitionblock td.icon [class^="fa icon-"] {
  font-size: 2.5em;
  text-shadow: 1px 1px 2px rgba(0,0,0,.5);
  cursor: default;
}
.admonitionblock td.icon .icon-note:before {
  content: "\f05a";
  color: #19407c;
}
.admonitionblock td.icon .icon-tip:before {
  content: "\f0eb";
  text-shadow: 1px 1px 2px rgba(155,155,0,.8);
  color: #111;
}
.admonitionblock td.icon .icon-warning:before {
  content: "\f071";
  color: #bf6900;
}
.admonitionblock td.icon .icon-caution:before {
  content: "\f06d";
  color: #bf3400;
}
.admonitionblock td.icon .icon-important:before {
  content: "\f06a";
  color: #bf0000;
}

Feel free to modify the CSS to your liking.

Finally, you need to enable the font-based icons in the header of the document:

:icons: font

or in the site configuration:

asciidoctor:
  attributes:
    - icons=font
    ...

Image-based Admonition and Inline Icons

As an alternative to font-based icons, you can configure Asciidoctor to use image-based icons. In this case, all you need to do is provide the icons at the proper location.

First, enable image-based icons and configure the path to the icons in the header of the document:

:icons:
:iconsdir: /images/icons

or your site configuration:

asciidoctor:
  attributes:
    - icons
    - iconsdir=/images/icons

Then, simply put the icon images that the page needs in the images/icons directory.

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).

Releasing the gem to RubyGems.org

When you are ready for a release, first set the version in the file lib/jekyll-asciidoc/version.rb. Then, commit the change using the following commit message template:

Release X.Y.Z

where X.Y.Z is the version number of the gem.

Next, package, tag and release the gem to RubyGems.org, run the following rake task:

$ rake release
Important
 Ensure you have the proper credentials setup as described in the guide Publishing to RubyGems.org.

Once you finish the release, you should update the version to the next micro version in the sequence using the .dev suffix (e.g., 1.0.1.dev).