Jekyll One

QuickSearch

For J1 Theme, the primary source code engine for content pages is Asciidoctor. In difference to other Jekyll templates, J1 is using Asciidoc for the markup language of content sources. The language Asciidoc is much more powerful than Markdown, the default Markup Language for Jekyll. Because of the rich and powerful markups available with Asciidoc, content pages can be simple one-pagers but can be used for complex documents up to a book-level.

The processing engine for Markdown-based content source is build-in into Jekyll. To support Asciidoc-based source, the Asciidoctor plugins asciidoctor and jekyll-asciidoc are required for Jekyll to convert Asciidoc source files to HTML pages.

Setting up Asciidoc

The setup to use the Asciidoc Markup language for J1 Theme and Jekyll is already done. The global Ruby Gemfile for a J1 project is requesting the required libraries (Ruby GEMs) with the group jekyll_plugins:

# ------------------------------------------------------------------------------
# Jekyll Plugins
# If any (additional) Jekyll Plugins are used, they goes here
#
group :jekyll_plugins do
  # Base Jekyll Plugins (required)
  #
  gem 'asciidoctor', '~> 2.0'
  gem 'jekyll-asciidoc', '>= 3.0.0'
  ...
end

In the site-wide configuration file _config.yml, the required loads for Jekyll can be found in the plugin loader section:

# ------------------------------------------------------------------------------
# PLUGIN loader
#
plugins:
 - asciidoctor
 - jekyll-asciidoc
 ...

To make the Asciidoc core engine Asciidoctor usable for Jekyll, the following plugin configuration is used:

# ------------------------------------------------------------------------------
# Asciidoctor plugin configuration
#
asciidoc_attributes:                    &asciidoc_attributes
 hardbreaks-option:
 source-highlighter:                   rouge
 icons:                                font
 imagesdir:                            /assets/images
 iconsdir:                             '{imagesdir}/icons/asciidoc'
 experimental:                         false
asciidoc:
 processor:                            asciidoctor
 require_front_matter_header:          true
 ext:                                  adoc
asciidoctor:
 safe:                                 unsafe
 template_dir:                         _templates
 attributes:                           *asciidoc_attributes

Plugin asciidoctor

The plugin Asciidoctor is the core engine to convert Asciidoc-based text data into HTML code. The engine is implicitely called by the integration library jekyll-asciidoc. To interprete and compile Asciidoc Markups, the plugin calls the Converter API of jekyll-asciidoc.

The core engine of Asciidoctor is completely silent from the prospective of Jekyll. All the integration work is handled by the plugin jekyll-asciidoc. Read the next section how Asciidoc integration is managed for Jekyll.

Plugin jekyll-asciidoc

The plugin Jekyll-Asciidoc is the integration library for Jekyll. All the managing of Asciidoc code is done by this integration library The plugin consists of three extensions to be used by Jekyll to manage Asciidoc-based content sources:

Table 1. Jekyll Asciidoc API
Extention API Description

Converter

Jekyll::AsciiDoc::Converter::

Converts AsciiDoc files to HTML pages. This plugin currently uses Asciidoctor to convert AsciiDoc content.

Generator

Jekyll::AsciiDoc::Integrator::

Promotes eligible AsciiDoc attributes (e.g. doctitle, id, author, and attributes that begin with the page attribute prefix) to page variables. These attributes are merged with the page variables defined in the front matter header.

Filters

Liquid Filters::

The available (Liquid) filter asciidocify make use of the converter from this plugin to convert a string of AsciiDoc content to HTML. A second filter tocify_asciidoc generates a table of contents in HTML from the parsed AsciiDoc document of the current page.
The extensions are automatically registered if the Gem jekyll-asciidoc is loaded.

Configure plugin jekyll-asciidoc

This section describes the configuration options for this plugin, which are optional. You should at least assign an empty Hash as a default (e.g. {}) to the asciidoc and asciidoctor keys in site config file _config.yml, respectively, if you don’t plan on making any further customizations.

asciidoc:         {}
asciidoctor:      {}

Using these placeholder values prevents initialization from being performed more than once when using watch mode (see issue jekyll#4858).

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

asciidoc:
  processor:      asciidoctor
The asciidoc block should only appear once inside site config file _config.yml. If you define any other options that are documented in this section, you should append them to the asciidoc block.

To tell Jekyll which file extensions to match as AsciiDoc files, append the ext option to the asciidoc block of your site config file _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.

AsciiDoc attributes defined in the document header whose names begin with page- are promoted to page variables* The part of the name after the page- prefix is used as the key (e.g. page-layout becomes layout)* If you want to change this attribute prefix, append the page_attribute_prefix option to the asciidoc block of your site config file _config.yml:

asciidoc:
  page_attribute_prefix: jekyll

A hyphen is automatically added to the value of this configuration setting if the value is non-empty (e.g, jekyll-).

Since version 2.0.0 of this plugin, all non-hidden AsciiDoc files are processed by default, even those without a front matter header* If you only want files containing a front matter header to be processed (as was the behavior prior to version 2.0.0), add the require_front_matter_header option to the asciidoc block of your site config file _config.yml:

asciidoc:
  require_front_matter_header: true

In addition to the built-in attributes in AsciiDoc, the following additional AsciiDoc attributes are automatically defined by this plugin and available to all Asciidoc-based pages:

site-root=(absolute path of root directory)
site-source=(absolute path of source directory)
site-destination=(absolute path of output directory)
site-baseurl=(value of the baseurl config option)
site-url=(value of the url config option)
env=site
env-site
site-gen=jekyll
site-gen-jekyll
builder=jekyll
builder-jekyll
jekyll-version=(value of the Jekyll::VERSION constant)
idprefix
idseparator=-
linkattrs=@

The following attributes are defined per page:

outpath=(path of page relative to baseurl)

You can pass additional attributes to AsciiDoc, or override default attributes provided by the plugin, by using the attributes option of the asciidoctor block in your site config file _config.yml* The value of this option can either be an Array containing key-value pairs:

asciidoctor:
  attributes:
    - idprefix=_
    - source-highlighter=pygments
    - pygments-css=style

or key-value pairs defined as a Hash:

asciidoctor:
  attributes:
    idprefix: _
    source-highlighter: pygments
    pygments-css: style

When using the Hash syntax, you must use an empty string value to set a valueless attribute such as sectanchors:

asciidoctor:
  attributes:
    sectanchors:  ''

You may use attribute references in the attribute value to reference any implicit or already defined attribute* For example, to set the iconsdir attribute based on the imagesdir attribute, use the following:

asciidoctor:
  attributes:
    imagesdir:    /images
    iconsdir:     '{imagesdir}/icons'
If the value begins with an attribute reference, and you’re defining the attributes using the Hash structure, you must enclose the value in quotes. Beware that there are additional edge cases when the value must be enclosed in quotes.

Since version 2.1.0 of this plugin, you can remove a previously defined attribute by prefixing the name with a minus sign (without any space between):

asciidoctor:
  attributes:
    - idprefix:

In addition to attributes, you may define any other option key (e.g. safe) recognized by the Asciidoctor API. One of those is base_dir, which is covered in the next section.

Specifying the Base Directory

In Asciidoctor, the base directory (i.e., base_dir option) is used as the root when resolving relative include paths in top-level documents.

By default, this plugin does not specify a base directory when invoking the Asciidoctor API* Asciidoctor will therefore use the current working directory (i.e., the project root) as the base directory.

If your source directory is not the project root, and you want Asciidoctor to use the source directory as the base directory, set the value of the base_dir option to :source.

asciidoctor:
  base_dir:       ':source'
  ...

If, instead, you want the base directory to track the directory of the document being processed, and you’re using Jekyll 3 or better, you can set the value of the base_dir option to :docdir* This behavior matches how Asciidoctor works when running it outside of Jekyll* Since the base directory is also the jail, we also recommend setting the safe option to unsafe so that you can still resolve paths outside of this directory.

asciidoctor:
  base_dir:       ':docdir'
  safe:           unsafe
  ...
The :docdir setting is not available when using Jekyll 2.

You can also set the base_dir option to any relative or absolute path. In that case, the same value will be used for all documents.

Using Asciidoc attributes in Liquid

Let’s say you want to reuse your AsciiDoc attributes in a Liquid template. This section describes how to do it.

Liquid can only access simple data structures, not complex ones like the one used to store site-wide AsciiDoc attributes* (Site-wide AsciiDoc attributes are stored deep within the Jekyll configuration data as a Hash with symbol keys)* This puts them out of the reach of Liquid templates by default.

This plugin must store site-wide AsciiDoc attributes in this way due to how Jekyll is implemented and the lifecycle it exposes for plugins* That part can’t be changed.

The plugin is limited by Jekyll’s design* However, YAML provides a mechanism that we can leverage to expose these attributes to our Liquid templates.

First, you define your AsciiDoc attributes at the top level of your configuration file where Liquid is able to access them* If you also assign a YAML reference to this key, you can then pass that Hash to the attributes key in the asciidoctor block, thus allowing the configuration to be shared.

asciidoc_attributes: &asciidoc_attributes
  imagesdir=/images
asciidoctor:
  attributes: *asciidoc_attributes
  ...

You can now reference one of the site-wide AsciiDoc attributes in the Liquid template as follows:

{% raw %}{{ site.asciidoc_attributes.imagesdir }}{% endraw %}

Keep in mind that the value of the attribute will be unmodified from the value defined in the configuration file.

Enabling Hard Line Breaks globally

Many Jekyll users are used to writing in GitHub-flavored Markdown (GFM), which preserves hard line breaks in paragraph content* Asciidoctor supports this feature for AsciiDoc files.

(In fact, previous versions of this plugin enabled this behavior by default). If you want to enable this behavior for AsciiDoc files, add the hardbreaks-option attribute to the Asciidoctor attributes configuration in your site’s site config file _config.yml file:

asciidoctor:
  attributes:
    - hardbreaks-option

If you want to allow individual files to override this setting, then assign the value @ to the attribute:

asciidoctor:
  attributes:
    - hardbreaks-option=@

If you already have AsciiDoc attributes defined in the site config file _config.yml, the new attribute should be added as a sibling entry in the YAML collection.

Keep in mind, if you enable hard line breaks, you won’t be able to use the one sentence-per-line writing technique, {window}.

Running in Safe Mode

If you want to use this plugin when running Jekyll in safe mode, you must add the jekyll-asciidoc gem to the whitelist in your site’s site config file _config.yml file:

whitelist:
  - jekyll-asciidoc

Safe mode is enabled either through the --safe flag:

  jekyll build --safe

or the safe configuration option in your site’s site config file _config.yml file:

safe: true

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

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 layout to include resources typically present in a standalone HTML document that Asciidoctor produces.

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

  • 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 }}">

Stylesheet for Code Highlighting

Asciidoctor integrates with Pygments to provide code highlighting of source blocks in AsciiDoc content* This integration is separate from the Pygments integration in Jekyll 2.

To enable Pygments, you must install the pygments.rb gem* To use Pygments with Ruby >= 2.4 or JRuby, you must install pygments.rb >= 1.1.0, which also equires Jekyll >= 3.0.0* If you’re using Jekyll 3, add the pygments.rb gem to your Gemfile:

gem 'pygments.rb', '~> 1.1.2'

As part of this integration, Asciidoctor generates a custom stylesheet tailored specially to work with the HTML that Asciidocotor produces* Since this stylesheet is backed by the Pygments API, it provides access to all the themes in Pygments

This plugin will automatically generate a stylesheet for Pygments into the source directory if the AsciiDoc attributes in your site’s site config file _config.yml are configured as follows:

  • source-highlighter has the value pygments

  • pygments-css has the value class or is not set

  • pygments-stylesheet is not unset (if set, it can have any value)

By default, the stylesheet is written to stylesdir + pygments-stylesheet. If the pygments-stylesheet attribute is not specified, the value defaults to asciidoc-pygments.css* You can customize this value to your liking.

The Pygments theme is selected by the value of the pygments-style attribute. If this attribute is not set, it defaults to vs.

The stylesheet file will be created if it does not yet exist or the theme has been changed* Jekyll will handle copying the file to the output directory.

You’ll need to add a line to your template to link to this stylesheet, such as:

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

To disable this feature, either set the pygments-css to style (to enable inline styles) or unset the pygments-stylesheet attribute in your site’s site config file _config.yml.

It may still be necessary to make some tweaks to your site’s stylesheet to accomodate this integration.

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">
You can also link to a 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.