Marketplace

AsciiDoc JRuby

plugin Source

Full AsciiDoctor via JRuby with support for all extensions and macros

Install

Terminal
$ roq add plugin:asciidoc-jruby

Usage

Full-featured Asciidoctor implementation based on AsciidoctorJ. Offers the complete AsciiDoc feature set including all extensions. Slower startup than the Java variant but covers all advanced AsciiDoc options.

Add the .adoc or .asciidoc file extension to pages and they will be processed using Asciidoctor.

Use Qute in AsciiDoc files

Qute parsing is disabled by default on AsciiDoc files, to enable it:

quarkus.asciidoc.qute=true

You can also use the :qute: AsciiDoc header attribute to enable Qute parsing (or not :qute: false) per page.

AsciiDoc includes

You may use includes from anywhere in the site directory. Make sure the included file is ignored by Roq by prefixing the file or directory with _.

include::_includes/attributes.adoc[]

Headers

AsciiDoc headers are parsed by Roq and used as page data:

  • = Title is used as page title
  • author is available through page.data.author and page.data.author-email
  • revision is available through page.data.revision.number, page.data.revision.date and page.data.revision.remark
  • attribute :description: is used as page description
  • attributes starting with page- will be used as page data (:page-image: becomes image in the data)
  • all other header attributes are also available in page.data.attributes

You can also use FrontMatter headers to set the page data like any other page.

Roq attributes

Name Description

| {site-url} | The full site url (e.g. https://my-site.com/blog/) | | {site-path} | The site path (e.g. /blog/) | | {page-url} | The full page url (e.g. https://my-site.com/blog/about/) | | {page-path} | The page path (e.g. /blog/about) |

AsciiDoc attributes configuration

Attributes can be configured globally:

quarkus.asciidoc.attributes.source-highlighter=highlight.js
quarkus.asciidoc.attributes.icons=font

Or as an include file in the AsciiDoc headers, or as part of the Frontmatter data asciidoc-attributes in a page or layout:

---
asciidoc-attributes:
  notitle: true
---

Table of Contents (TOC)

To add a Table of Contents, use the page-content-toc attribute in your AsciiDoc header:

:page-content-toc: true
:page-content-toc-title: Contents
:page-content-toc-levels: 2

This works with the default Roq theme and creates a dynamic sidebar TOC that highlights the current section as you scroll.

AsciiDoc Data Conversion

Convert data containing AsciiDoc into HTML using the asciidocToHtml template extension:

---
bar: |
    == Hello
    * that's nice
    * I can use asciidoc in the data
---

{page.data.foo.asciidocToHtml}