Quarkus Qute AsciiDoc

This extension renders AsciiDoc content inside Qute templates. It adds a Qute section named asciidoc or ascii that converts the content of the section to HTML with the asciidoc-java parser and renderer, in plain Java, so it works in native mode.

Installation

To install the extension, add the following dependency to your project:

<dependency>
    <groupId>io.quarkiverse.qute.web</groupId>
    <artifactId>quarkus-qute-web-asciidoc</artifactId>
    <version>3.4.5</version>
</dependency>

Usage

Create a Qute template with an asciidoc section:

<!-- src/resources/templates/foo.txt -->
{#asciidoc}
= Hello World

A paragraph with *AsciiDoc* markup.
{/asciidoc}

Attributes can be passed to the section, for example {#asciidoc attributes=myAttributes}, and set for every document with quarkus.asciidoc.attributes.<name>=<value>.

Customization

Two CDI beans customize the conversion, the AsciiDoc counterparts of a tree processor and of a custom converter.

Rewrite the document before rendering

Implement AsciidocDocumentProcessor to change the parsed Document before it is rendered, for example to translate paragraphs or to add a section. Every bean is applied, highest @Priority first, each one receiving the document the previous one returned. The model is immutable, so return a new document, or the same one to change nothing.

@Singleton
@Priority(10)
public class NoticeProcessor implements AsciidocDocumentProcessor {
    @Override
    public Document process(Document document, AsciidocRenderingContext context) {
        var children = new ArrayList<>(document.body().children());
        children.add(new Paragraph(List.of(new Text(List.of(), "Rendered by " + context.attributes().get("sitegen"), Map.of())), Map.of()));
        return new Document(document.header(), new Body(children));
    }
}

Supply the renderer

Implement AsciidocRendererFactory, at most one bean, to create the renderer of each document, for example a subclass of AsciidoctorLikeHtmlRenderer rendering the macros of your site. Without one, the extension uses an AsciidoctorLikeHtmlRenderer configured with the attributes of the context. A renderer is not thread-safe, so return a new instance on each call.

@Singleton
public class SiteRendererFactory implements AsciidocRendererFactory {
    @Override
    public Visitor<String> createRenderer(AsciidocRenderingContext context) {
        var configuration = new AsciidoctorLikeHtmlRenderer.Configuration().setAttributes(context.attributes());
        return new AsciidoctorLikeHtmlRenderer(configuration) {
            @Override
            protected void onMissingMacro(Macro element) {
                if ("tooltip".equals(element.name())) { // tooltip:term[definition]
                    builder.append("<span title=\"").append(element.options().get("")).append("\">").append(element.label()).append("</span>");
                    return;
                }
                super.onMissingMacro(element);
            }
        };
    }
}

AsciidocRenderingContext is a record giving both beans the attributes of the document, which the renderer is configured with, and the template attributes of the content, such as its source path.

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.asciidoc.attributes."attributes"

Defines the Asciidoc attributes to be applied during rendering.

Default values:

  • noheader=true

Environment variable: QUARKUS_ASCIIDOC_ATTRIBUTES__ATTRIBUTES_

Map<String,String>