:syringe: A Jekyll plugin that converts AsciiDoc source files in your site to HTML pages using Asciidoctor.
:syringe: A Jekyll plugin that converts AsciiDoc source files in your site to HTML pages using Asciidoctor.
= Jekyll AsciiDoc Plugin (powered by Asciidoctor) Dan Allen ; Paul Rayner v3.0.1, 2023-11-06 // Settings: :idprefix: :idseparator: - ifndef::env-github[:icons: font] ifdef::env-github,env-browser[] :toc: macro :toclevels: 1 endif::[] ifdef::env-github[] :branch: main :status: :outfilesuffix: .adoc :!toc-title: :caution-caption: :fire: :important-caption: :exclamation: :note-caption: :paperclip: :tip-caption: :bulb: :warning-caption: :warning: endif::[] // Aliases: :path-config: pass:q[[.path]_config.yml] :conum-guard: {sp} ifndef::icons[:conum-guard: {sp}#{sp}] // URIs: :url-repo: https://github.com/asciidoctor/jekyll-asciidoc :url-issues: {url-repo}/issues :url-search-issues: {url-repo}/search?type=Issues :url-chat: https://chat.asciidoctor.org :url-gem: https://rubygems.org/gems/jekyll-asciidoc :url-gem-asciidoctor: https://rubygems.org/gems/asciidoctor :url-asciidoc: https://asciidoc.org :url-asciidoctor: https://asciidoctor.org :url-asciidoctor-backends: https://github.com/asciidoctor/asciidoctor-backends :url-asciidoctor-docs: {url-asciidoctor}/docs :url-asciidoctor-diagram: {url-asciidoctor-docs}/asciidoctor-diagram :url-asciidoctor-manual: {url-asciidoctor-docs}/user-manual :url-asciidoc-practices: {url-asciidoctor-docs}/asciidoc-recommended-practices :url-jaq: https://github.com/asciidoctor/jekyll-asciidoc-quickstart :url-jekyll: https://jekyllrb.com :url-jekyll-docs: {url-jekyll}/docs :url-jekyll-discuss: https://talk.jekyllrb.com :url-front-matter: {url-jekyll-docs}/frontmatter :url-liquid-templates: {url-jekyll-docs}/templates :url-variables: {url-jekyll-docs}/variables :url-graphviz: https://www.graphviz.org :url-tilt: https://github.com/rtomayko/tilt :url-yaml: https://en.wikipedia.org/wiki/YAML :url-guide-publish-gem: https://guides.rubygems.org/publishing/#publishing-to-rubygemsorg
ifdef::status[] image:https://img.shields.io/gem/v/jekyll-asciidoc.svg[Latest Release, link={url-gem}] image:https://img.shields.io/badge/license-MIT-blue.svg[MIT License, link=#copyright-and-license] image:{url-repo}/actions/workflows/ci.yml/badge.svg?branch={branch}[Build Status (GitHub Actions),link={url-repo}/actions/workflows/ci.yml?query=branch%3A{branch}] image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg[Project Chat (Zulip),link={url-chat}] endif::[]
A plugin for {url-jekyll}[Jekyll] (>= 3.0.0) that converts {url-asciidoc}[AsciiDoc] source files in your site to HTML pages using {url-asciidoctor}[Asciidoctor].
IMPORTANT: We're currently seeking a new maintainer for this project as the current maintainers can no longer dedicate time to working on it. As of November 2023, this project is fully up to date and features both automated testing and releases. This situation presents an opportunity for someone to come into the project and run it witih plenty of autonomy. If no one comes forward by the start of 2025, we plan to archive this project and halt releases.
ifeval::['{branch}' == 'main'] NOTE: You're viewing the documentation for the upcoming release. If you're looking for the documentation for an older release, please refer to one of the following branches: + {url-repo}/tree/v3.0.x#readme[3.0.x] ⁃ {url-repo}/tree/v2.1.x#readme[2.1.x] ⁃ {url-repo}/tree/v2.0.x#readme[2.0.x] ⁃ {url-repo}/tree/v1.1.x#readme[1.1.x] ⁃ {url-repo}/tree/v1.0.x#readme[1.0.x] endif::[]
toc::[]
== Overview
The plugin consists of three extensions:
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.
Liquid Filters::
asciidocify -- Uses the converter from this plugin to convert a string of AsciiDoc content to HTML.tocify_asciidoc -- Generates a table of contents in HTML from the parsed AsciiDoc document of the current page (since 2.1.0).These extensions are registered automatically when the [.app]jekyll-asciidoc gem is required.
== Prerequisites
To use this plugin, you must be using Jekyll >= 3.0.0 and Ruby >= 2.7.0 (with development headers installed). You should also be familiar with creating sites with Jekyll. If you're not, you should first read the {url-jekyll-docs}[Jekyll documentation] to familiarize yourself with how it works. Experience with AsciiDoc and Asciidoctor is also helpful, but not a requirement.
Like Jekyll, this plugin was designed for developers, so some assembly is required. That means you'll be expected to edit configuration, modify HTML templates, and customize CSS to use it fully.
== Installation
This plugin is packaged as a gem named [.app]{url-gem}[jekyll-asciidoc] and published to RubyGems.org. The plugin depends on the [.app]{url-gem-asciidoctor}[asciidoctor] gem, which gets installed automatically.
Your method of installation will depend on whether you use Bundler to manage the dependencies for your Jekyll project.
IMPORTANT: Jekyll relies on several native gems, so it's necessary to have the Ruby development headers (e.g., ruby.h) on your machine in order to install AsciiDoc Jekyll (due to the requirements of Jekyll). The instructions for how to install the Ruby development headers are platform-specific and outside of the scope of this document.
TIP: If you're using RVM, you should add a [.path].ruby-version file to the project so your shell automatically switches to the correct version of Ruby each time you enter the project. For more information, refer to the the page https://rvm.io/workflow/projects[RVM Project Workflow].
=== Installation Using Bundler
If you're using Bundler to manage the dependencies for your project (as recommended), simply add the [.app]jekyll-asciidoc gem to the :jekyll_plugins group in your [.path]Gemfile:
Then, run the bundle command from Bundler to install the gem:
$ bundle
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:
$ bundle config set --local path .bundle/gems bundle
TIP: Subsequent calls to bundle will retain the path setting.
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.
=== Manual Installation
If you're not using Bundler to manage the dependencies for your Jekyll project, you'll need to install the gem manually:
$ [sudo] gem install jekyll-asciidoc
NOTE: The sudo prefix is only required if you are installing gems into your system.
To avoid this bad practice, we recommend using RVM (or another Ruby version manager), which sets up Ruby safely in your home directory.
Then add the [.app]jekyll-asciidoc gem to the list of gems for Jekyll to load in your site's _config.yml file:
plugins:
If you're running Jekyll 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 [.app]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 [.app]jekyll-archives plugin alongside the [.app]jekyll-asciidoc plugin.
The [.app]jekyll-archives plugin should be listed after the [.app]jekyll-asciidoc plugin since it needs to access front matter that is promoted from the header of the AsciiDoc document.
== Creating Pages
This plugin converts eligible AsciiDoc files located inside the source directory (by default, the project root) to HTML pages in the generated site. There are a few conditions that must be met in order for an AsciiDoc file to be eligible:
. The file must have an AsciiDoc file extension (see >).
. The name of the file must not begin with a dot (.) or an underscore (_).footnote:excluded_files[Hidden files and folders are automatically excluded by Jekyll.]
. The file must not be located in a folder whose name begins with a dot (.) or an underscore (_) (unless the folder is a designated collection, such as _posts).footnote:excluded_files[]
. While you can use a Jekyll front matter header, it is not required.
Here's a sample AsciiDoc file that meets these criteria:
= Sample Page :url-asciidoctor: https://asciidoctor.org
This is a sample page composed in AsciiDoc. Jekyll converts it to HTML using {url-asciidoctor}[Asciidoctor].
Alternatively, you can define the page variables directly in the AsciiDoc header, which we recommend:
= Sample Page :page-layout: info :page-permalink: /sample/ :url-asciidoctor: https://asciidoctor.org
This is a sample page composed in AsciiDoc. Jekyll converts it to HTML using {url-asciidoctor}[Asciidoctor].
=== Page Attributes
Any AsciiDoc attribute defined in the AsciiDoc document header whose name begins with page-footnote:[The prefix used to label page attributes can be customized.] gets promoted to a {url-variables}[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 {url-yaml}[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.
IMPORTANT: Page attributes must be defined in the document header. That means either putting them directly below the document title (the line beginning with a single equals sign in the sample above) or above all other AsciiDoc content if the document title is not defined in AsciiDoc. The AsciiDoc document header stops after the first blank line. For more details about the document header, see the https://asciidoctor.org/docs/user-manual/#doc-header[Document Header] chapter in the Asciidoctor User Manual.
IMPORTANT: You may use include directives in the the document header. However, you must ensure that the file included does not contain blank lines.
CAUTION: If an attribute defined in the header of an AsciiDoc document is not visible to another plugin or Liquid template, you may have a plugin ordering problem. See <> to learn how to fix it.
=== Specifying a Layout
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 [.path]_{empty}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 [.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 AsciiD
No open issues yet, or sync has not completed.