Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
J

jekyll-asciidoc

> 编程语言
Open source

:syringe: A Jekyll plugin that converts AsciiDoc source files in your site to HTML pages using Asciidoctor.

322 stars0 likes1 views
WebsiteGitHub

About

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

[source,ruby]

group :jekyll_plugins do gem 'jekyll-asciidoc' end

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:

[source,yaml]

plugins:

  • jekyll-asciidoc

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.

[source,ruby]

group :jekyll_plugins do gem 'jekyll-asciidoc' gem 'jekyll-archives' end

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.adoc [source,asciidoc]


layout: info permalink: /sample/

= Sample Page :url-asciidoctor: https://asciidoctor.org

This is a sample page composed in AsciiDoc. Jekyll converts it to HTML using {url-asciidoctor}[Asciidoctor].

[source,ruby] puts "Hello, World!"

Alternatively, you can define the page variables directly in the AsciiDoc header, which we recommend:

.sample.adoc [source,asciidoc]

= 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].

[source,ruby] puts "Hello, World!"

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

[source,asciidoc]

:page-header: { image: logo.png }

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

[source,asciidoc]

:page-short-name: slug

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

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Ruby

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 18, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言