If you’re using Bundler to manage the dependencies for your project (as recommended), simply add the jekyll-asciidoc gem to the :jekyll_plugins group in your Gemfile:

Then, run the bundle command from Bundler to install the gem:

Jekyll will automatically activate any plugins listed in the :jekyll_plugins group.

If you want to keep the installed gems inside the project, use this command instead:

Keep in mind that the gems Bundler installs are linked to the current version of Ruby. If you switch Ruby versions, you’ll need to run bundle again.

If you’re not using Bundler to manage the dependencies for your Jekyll project, you’ll need to install the gem manually:

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

If you’re running Jekyll < 3.5.0, you’ll need to use gems in place of plugins:

Since the jekyll-asciidoc plugin promotes page attributes to the front matter, it must run first. To make sure it does, rearrange the sequence of plugins in your Gemfile or _config.yml file so the jekyll-asciidoc plugin is listed before other plugins. By doing so, other plugins will be able to access any front matter that this plugin assigns.

Let’s consider the case of using the jekyll-archives plugin alongside the jekyll-asciidoc plugin.

1. The jekyll-archives plugin should be listed after the jekyll-asciidoc plugin since it needs to access front matter that is promoted from the header of the AsciiDoc document.

Any AsciiDoc attribute defined in the AsciiDoc document header whose name begins with page-^[2] gets promoted to a page variables. The part of the name after the page- prefix is lowercased and used as the variable name (e.g., page-layout becomes layout). The value is processed as YAML data (single-line form).

Since the attribute value is processed as YAML data, you can build nested data structure using the inline YAML syntax. For example, here’s how you can assign a value to the page.header.image page variable:

To define a page attribute that contains multiple words, use either a hyphen or underscore character to connect the words.

The most commonly defined page variable is layout, which determines which template is used to wrap the generated content. Jekyll will look for a template file inside the _layouts folder whose root name matches the name of the layout. For example, if the layout variable has the value info, Jekyll looks for a layout template at the path _layout/info.html.

If the layout is empty, the auto-selected layout layout is used (documented in the list below). If the layout is unset or false, the AsciiDoc processor will generate a standalone document. In this case, the page will appear like an HTML file generated by the AsciiDoc processor directly (with the option header_footer: true). If the layout is ~, no layout is applied.

To review, here are the different ways to specify a layout using the AsciiDoc attribute page-layout:

• :page-layout: info — use the layout named info (e.g., _layout/info.html)

• not specified, :page-layout: or :page-layout: _auto — use the automatic layout (i.e., page for pages, post for posts, the singular form of the collection label for a document; if the auto-selected layout isn’t available, the layout default is used)

• :!page-layout: or :page-layout: false — don’t use a layout; instead, generate a standalone HTML document

• :page-layout: none or :page-layout: ~ — don’t use a layout or create a standalone HTML document (often produces an HTML fragment); use of the value ~ is discouraged; the value none is preferred

To prevent a page from being published, set the page attribute named page-published to false (which, in turn, sets the page variable named published to false.

In addition to page attributes defined explicitly (e.g., layout, permalink, etc), the following implicit AsciiDoc attributes are also promoted to page variables:

• doctitle (aka the document title) (becomes title)

• id (becomes docid)

• author

• revdate (becomes date; value is converted to a DateTime object; not applied to pages)

Although not an implicit page variable, another very common page variable to set is page-description, which becomes description in the model.

Unlike other content files, the Liquid template preprocessor is not applied to AsciiDoc files by default (since version 2.0.0 of this plugin). If you want the Liquid template preprocessor to be applied to an AsciiDoc file (prior to the content being passed to the AsciiDoc processor), you must enable it by setting the liquid page variable (shown here defined using a page attribute).

Liquid processing does not extend to files included using the AsciiDoc include directive (see #166).

If you’re using the Liquid include tag to include HTML into the AsciiDoc document, you need to enclose it in a passthrough block.

This is necessary since AsciiDoc will escape HTML by default. To pass it through raw requires enclosing it in a passthrough block.

The Liquid preprocessor does not process content included using the AsciiDoc include directive. However, if those files are otherwise publishable, they are processed independently by Jekyll with the Liquid preprocessor and will appear in your site. If this is not the behavior you want, you can exclude them from being processed independently using one of the following techniques:

• Place them in an automatically excluded location, such as a directory starting with _ (e.g. _includes).

• Name them in such a way that they are automatically excluded, such as starting the name with _ (_excluded-include.yml).

• Adding them to the excludes key in the Jekyll configuration.

This plugin will extract an excerpt for any post or document in a collection if the excerpt page variable isn’t set using the same logic as for Markdown files. By default, it will use the content between the header and the first blank line. If the excerpt page variable is set, that value will be used instead. The excerpt will automatically be converted from AsciiDoc to embedded HTML whereever the excerpt property is referenced in a Liquid template.

If you want to use a different excerpt separator for AsciiDoc files, set the excerpt_separator under the asciidoc key in the site configuration. For example, you can configure the plugin to use the line comment //more as the excerpt separator as follows:

If you’re only working with AsciiDoc files in your site, you can go ahead and set this for all files by using the top-level property:

If the excerpt separator isn’t found, the content of the whole document is used instead.

By default, the excerpt is converted to HTML using the article doctype. If you want to use a different doctype, such as inline, you can set it in the site configuration as follows:

You can also set the excerpt doctype per page using the page attribute named page-excerpt_doctype.

$ jekyll build

$ bundle exec jekyll build

$ jekyll serve

$ jekyll serve --no-watch

$ jekyll build --watch

$ jekyll serve --incremental

$ jekyll build --watch --incremental

$ jekyll build --verbose

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 _config.yml:

To tell Jekyll which file extensions to match as AsciiDoc files, append the ext option to the asciidoc block of your _config.yml:

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 _config.yml:

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 _config.yml:

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:

The following additional attributes are defined per page:

You can pass custom attributes to AsciiDoc, or override default attributes provided by the plugin, using the attributes option of the asciidoctor block in your _config.yml. The value of this option can either be a Hash of key-value pairs:

or an Array containing key-value pairs:

When using the Hash syntax, you may find that you need to enclose the value in single quotes for it to be accepted as valid YAML.

When using the Array syntax, you can set a valueless attribute by using the name along, such as sectanchors:

When using the Hash syntax, you must use an empty string value to indicate that you want to set the attribute:

By default, an attribute value defined in _config.yml overrides the same attribute set in the front matter or header of a document. For example, if you set page-layout in _config.yml, you won’t be able to set it per page.

If you want to allow individual pages to be able to override the attribute, append the charcter @ to the value in _config.yml:

You may use attribute references in the attribute value to reference any attribute that’s already defined, including implicit attributes. For example, to set the iconsdir attribute based on the imagesdir attribute, use the following:

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

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

$ jekyll build --safe

You can use the asciidocify filter to convert an arbitrary AsciiDoc string anywhere in your template. This filter allows you to compose site-wide data in AsciiDoc, such your site’s description or synopsis, then convert it to HTML for use in the page template(s).

Let’s assume you’ve defined a page variable named synopsis that you want treat as AsciiDoc. You can convert it in your template as follows:

By default, the AsciiDoc content is parsed as an embedded AsciiDoc document. If the content represents a single paragraph, and you only want to perform inline substitutions on that content, add the inline doctype as the filter’s first argument:

Since version 2.1.0 of this plugin, you can use the tocify_asciidoc filter to generate a table of contents from the content of any page that is generated from AsciiDoc. This filter gives you the ability to place this table of contents anywhere inside the page layout, but outside the main content.

You apply the tocify_asciidoc filter to page.document, the page variable that resolves to the parsed AsciiDoc document, as shown here:

The number of section levels (i.e., depth) shown in the table of contents defaults to the value defined by the toclevels attribute in the AsciiDoc document. To tune the number of levels, pass a numeric value as the filter’s first argument.

When you use the tocify_asciidoc filter, you’ll also want to disable the toc attribute in your document. You can do this using a conditional preprocessor directive.

By default, the tocify_asciidoc filter will insert a table of contents on any page that has even one section below the page title. It’s possible to conditionally disable this by using a Liquid if statement in your template with a custom attribute, similar to:

Then in the front matter of pages where you do not want a table of contents to appear, use the attribute :page-show-toc: false. Note that since this example uses a custom attribute, its name can be anything you’d like, it only needs to start with with page-. If you change the attribute name from this example, be sure to update the it in the if statement as appropriate.

You’ll first need to add the thread_safe gem as well as the gem for the templating language you plan to use. We’ll assume that you are using Slim.

Now run the bundle command to install the new gems.

Next, create a new folder in your site named _templates to store your templates.

In your site’s _config.yml file, configure Asciidoctor to load the templates by telling it the location where the templates are stored.

The final step is to compose a template. We’ll be customizing the unordered list node. Name the file ulist.html.slim.

The next time you build your site, Asciidoctor will use your custom template to generate the HTML for unordered lists.

$ bundle

Using Bundler

Add the asciidoctor-diagram gem to your Gemfile:

group :jekyll_plugins do
  gem 'asciidoctor-diagram', '~> 1.5.4' # # (1)
  gem 'jekyll-asciidoc'
  ...
end

1. Customize the version of Asciidoctor Diagram as needed.

Then, run Bundler’s install command to install the new gem:

$ bundle

Without Bundler

Install gems manually

$ [sudo] gem install asciidoctor-diagram

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

plugins:
- asciidoctor-diagram
- jekyll-asciidoc

If you’re running Jekyll < 3.5.0, you’ll need to use gems in place of plugins:

gems:
- asciidoctor-diagram
- jekyll-asciidoc

The preceding configurations are equivalent to passing -r asciidoctor-diagram to the asciidoctor command.

Asciidoctor Diagram needs some context in order to write the images to the proper location. At a minimum, you must set the following configuration in _config.yml:

With this configuration, Asciidoctor Diagram will generate images relative to the generated HTML page (i.e., in the same directory) within the destination folder.

You can use the following example to test your setup:

If you prefer to serve all images from the same folder, assign a value to the imagesdir attribute that is relative to the site root:

With this configuration, Asciidoctor Diagram will generate images into the images directory within the destination folder.

The first thing you need to do is activate the STEM processing integration in the processor itself. To do that, set the stem attribute on the document. One way is to set the stem attribute in the document header:

Alternatively, you can enable it the stem attribute globally for all AsciiDoc documents in your site by adding the following to your site’s _config.yml file:

To learn more about the built-in STEM integration, see the STEM chapter in the Asciidoctor User Manual.

Technically, Asciidoctor only prepares the STEM equations for interpretation by MathJax. That means you have to load MathJax on any page that contains STEM equations (or all pages, if that’s easier). To do so requires some customization of the page layout.

First, create the file _includes/mathjax.html and populate it with the following contents:

Then, include this file before the closing </body> tag in your page layout.

With that configuration in place, the STEM equations in your AsciiDoc file will be presented beautifully using MathJax.

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.

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

Asciidoctor integrates with Pygments to provide code highlighting of source blocks in AsciiDoc content.

To enable Pygments, you must install the pygments.rb gem. To do so, add the pygments.rb gem to your Gemfile:

As part of this integration, Asciidoctor generates a custom stylesheet tailored specially to work with the HTML that Asciidoctor 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 _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 you want the stylesheet to be written to the css directory, add the following configuration to your site’s _config.yml file:

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 (assuming stylesdir=css), such as:

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 _config.yml.

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:

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

Feel free to modify the CSS to your liking.

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

or in the site configuration:

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:

or your site configuration:

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

GitHub doesn’t (yet) whitelist the AsciiDoc plugin, so you must run Jekyll either on your own computer or on a continuous integration (CI) server.

But don’t despair! You can still automate publishing of the generated site to GitHub Pages using a continuous integration job. Refer to the Automate GitHub Pages publishing with Jekyll and Travis CI tutorial to find step-by-step instructions. You can also refer to the Transfuse website build for an example in practice.

In fact, if you’re using Travis CI, it’s even easier than that. Travis CI provides a deployer for GitHub Pages! Using this deployer, Travis CI can push your generated site to GitHub Pages after a successful build on your behalf, as long as you’ve completed these steps:

1. Create a personal access token on GitHub that has write access to your GitHub repository (public_repo or repo scope)

2. Define the token as a secure variable name GITHUB_TOKEN on the Travis CI settings page for your repository

3. Add a deploy configuration to your CI job configuration

Here’s a sample deploy configuration you can use:

Deployment to GitLab Pages is much simpler. That’s because GitLab allows you to control the execution of Jekyll yourself. There’s no need to mess around with CI jobs and authentication tokens. You can find all about how to use Jekyll with GitLab Pages in the tutorial Hosting on GitLab.com with GitLab Pages. More in-depth information regarding setting up your repository for GitLab Pages can be found in the GitLab Enterprise Edition / Pages documentation.

Assuming the following are true:

1. The source of your site resides on the master branch (though you can use any branch for this purpose).

2. You’re using Bundler to manage the dependencies for your project.

You can then use the following .gitlab-ci.yml file to get starting hosting your Jekyll site on GitLab Pages.

This script runs Jekyll on the official Ruby Docker container.

You also need to add an additional configuration file, _config-gitlab.yml, to set the url and baseurl options when deploying your site to GitLab Pages.

1. Replace <username> with your GitLab username or group.

2. Replace <projectname> with the basename of your project repository.

The next time you push to the master branch, the GitLab Pages runner will execute Jekyll and deploy your site to https://<username>.gitlab.io/<projectname>, where <username> is your GitLab username or group and <projectname> is the basename of your project repository.

Like GitHub Pages, you can also have your site respond to a custom domain name, which is explained in the referenced tutorial. In this case, update the _config-gitlab.yml file with the appropriate values.

This project uses the GitHub issue tracker to manage bug reports and feature requests. If you encounter a problem, please browse or search the issues to find out if your problem has already been reported. If it has not, you may submit a new issue.

The best way to get a timely response and quick fix for your issue is to write a detailed report and respond to replies in a timely manner.

If you know Ruby (or you’re willing to learn), we encourage you to submit a pull request. Please include an RSpec behavior that describes how your feature should work or demonstrates the problem you’re encountering. Make sure to send your pull request from a branch in your fork. If the pull request resolves an issue, please name the branch using the issue number (e.g., issue-N, where N is the issue number).

If you aren’t able to submit a pull request, please provide a sample so that the developers can reproduce your scenario.

You can retrieve the source code from GitHub using git. Simply copy the URL of the GitHub repository and pass it to the git clone command:

Next, switch to the project directory.

The dependencies needed to develop the Jekyll AsciiDoc plugin are defined in the Gemfile at the root of the project. You’ll use Bundler to install these dependencies.

To check if you have Bundler installed, use the bundle command to query for the version:

If Bundler is not installed, use the gem command to install it.

Finally, invoke the bundle command (which is provided by the bundler gem) from the root of the project to install the dependencies into the project:

The tests are based on RSpec. The test suite is located in the spec directory.

You can run the tests using Rake.

For more fine-grained control, you can also run the tests using RSpec directly.

If you only want to run a selection of tests, you can do so by assigning those specifications a tag and filtering the test run accordingly.

Start by adding the focus tag to one or more specifications:

Then, run RSpec with the focus flag enabled:

You should see that RSpec only runs the specifications that have this flag.

To generate a code coverage report when running tests using simplecov, set the COVERAGE environment variable as follows when running the tests:

You’ll see a total coverage score as well as a link to the HTML report in the output. The HTML report helps you understand which lines and branches were missed, if any.

Despite being fast, the downside of using simplecov is that it misses branches. You can use deep-cover to generate a more thorough report. To do so, set the COVERAGE environment variable as follows when running the tests:

You’ll see a total coverage score, a detailed coverage report, and a link to HTML report in the output. The HTML report helps you understand which lines and branches were missed, if any.

Before you commit code, you should run it through the linter to make sure it adheres to the coding style. You can run the linter using the following command:

The coding style is enforced by Rubocop. The rules are defined in .rubocop.yml. These rules extend from the default rule set provided by Rubocop to match the style of the project.

You can install the development version of the gem as follows:

This allows you to use an unreleased version of the gem to build your site.

If you want to build the gem and install it yourself, use these commands instead:

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:

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:

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

This plugin was created by Dan Allen and Paul Rayner and has received contributions from many other individuals in the Asciidoctor community.

Copyright © 2013-2018 Dan Allen, Paul Rayner, and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License. See LICENSE for details.