= Jekyll AsciiDoc Plugin (powered by Asciidoctor)
Paul Rayner <https://github.com/paulrayner[@paulrayner]>; Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
:toc: preamble
:toclevels: 1

image:https://badge.fury.io/rb/jekyll-asciidoc.svg["Gem Version", link="https://badge.fury.io/rb/jekyll-asciidoc"]

A plugin for http://jekyllrb.com[Jekyll] that converts http://asciidoc.org[AsciiDoc] files in your site source to HTML pages using http://asciidoctor.org[Asciidoctor].

== 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 http://rubygems.org/gems/asciidoctor[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 [path]_Gemfile_ (beneath the jekyll gem):

[source,ruby]
----
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 [path]_Gemfile_

[source,ruby]
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 [path]_{empty}_config.yml_ file:

[source,yaml]
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 [path]_lib/jekyll-asciidoc.rb_ to the [path]_{empty}_plugins_ directory in the root of your site source.

NOTE: If the [path]_{empty}_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
[listing]
....
---
---
= 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 http://jekyllrb.com/docs/frontmatter/[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 [path]_{empty}_config.yml_:

[source,yaml]
asciidoc: asciidoctor

To tell Jekyll which extensions to recognize as AsciiDoc files, add the following line to your [path]_{empty}_config.yml_:

[source,yaml]
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 [path]_{empty}_config.yml_:

[source,yaml]
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 [path]_{empty}_config.yml_ file:

[source,yaml]
asciidoctor:
  attributes:
    - hardbreaks!

If you already have AsciiDoc attributes defined in the [path]_{empty}_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, http://www.graphviz.org[Graphviz] must be installed (i.e., the `dot` utility must be available on your `$PATH`.

=== Installation

Using Bundler::
+
--
Add `asciidoctor-diagram` gem to your [path]_Gemfile_

[source,ruby]
----
group :jekyll_plugins do
  ....
  gem 'asciidoctor-diagram', '>= 1.3.1' <1>
  ...
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 [path]_{empty}_config.yml_ file:

[source,yaml]
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
[listing]
....
---
---
= Diagrams
:imagesdir: /images/2015-12-24 <1>

[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 [path]_{empty}_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 https://github.com/asciidoctor/jekyll-asciidoc-quickstart[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.

. Create a stylesheet in the [path]_css_ directory named [path]_asciidoc.css_ to hold additional CSS for body content generated from AsciiDoc.
. Add this stylesheet to the HTML `<head>` in [path]_{empty}_includes/head.html_ under the main.css declaration:
+
[source,html]
<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 [path]_{empty}_includes/head.html_ file under the asciidoc.css declaration:

[source,html]
<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 [path]_css/asciidoc.css_ file:

[source,css]
----
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:

[source,yaml]
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:

[source,yaml]
asciidoctor:
  attributes:
    - icons
    - iconsdir=/images/icons

Then, simply put the icon images that the page needs in the [path]_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 http://eshepelyuk.github.io/2014/10/28/automate-github-pages-travisci.html[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 https://github.com/johncarl81/transfuse/tree/transfuse-jeykll-site[Tranfuse website build^] for an example in practice.

Refer to the https://help.github.com/articles/using-jekyll-plugins-with-github-pages[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 [path]_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 http://guides.rubygems.org/publishing/#publishing-to-rubygemsorg[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).
