Quarkus Qute Markdown

The goal of this extension is to provide a simple way to render Markdown templates using Qute. It adds a new Qute section named markdown or md that can be used to convert the content of the section to HTML using a Markdown processor.

Installation

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

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

Usage

This extension can be used to render Markdown templates inside a Qute template or in a web application using the quarkus-qute-web extension.

Standalone Usage

Create a new Qute template named foo.txt:

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

Create a new resource class and inject the template using the @Inject annotation. Then, use the render method to display the template.

package com.foo;

import io.quarkus.qute.Template;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/hello")
public class GreetingResource {

    @Inject
    Template foo;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return foo.render();
    }
}

Start your application and open the following URL in your browser: http://localhost:8080/hello.

The output should be:

<h1>Hello World</h1>

Integration with Qute Web

This extension can be combined with the quarkus-qute-web extension to render Markdown templates in a web application. Add the quarkus-qute-web extension to your project inside the pom.xml file:

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

Then, create a new Qute template with the .txt or .html extension:

<!-- src/resources/templates/pub/markdown.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>My Qute Page with Markdown</title>
</head>
<body>
    <h1>Hello World!</h1>
    {#md}
        # This is a Markdown section
        It will be converted to HTML using a Markdown processor.
    {/md}
</body>
</html>

Start your application and open the following URL in your browser: http://localhost:8080/markdown.

CommonMark Extensions

The io.quarkiverse.qute-markdown:quarkus-qute-web-markdown module in Quarkus uses the CommonMark implementation through the commonmark-java project.

You can extend the parsing and rendering behavior of Markdown using additional libraries.

By default, this extension enables the heading-anchor, autolink, tables, and alerts Markdown extensions. If you want to disable any of them, you can do so using configuration properties.

Customization

Two CDI beans customize the conversion: a CommonMark Extension bean is added to the parser and the renderer, and an MdConverter bean replaces the converter.

Add a CommonMark extension

Declare a bean implementing org.commonmark.Extension to add it to the built-in extensions. Implement HtmlRenderer.HtmlRendererExtension to customize the HTML rendering, for example with an AttributeProvider adding attributes to the elements of a node type, or with a NodeRenderer rendering a node type differently, and Parser.ParserExtension to customize the parsing. See Customize HTML rendering in the commonmark-java documentation. The order of the extensions is undefined, so an extension that changes what a built-in extension does, such as the id of the headings, needs that built-in extension disabled with its configuration property.

@Singleton
public class LeadParagraphExtension implements Extension, HtmlRenderer.HtmlRendererExtension {
    @Override
    public void extend(HtmlRenderer.Builder rendererBuilder) {
        rendererBuilder.attributeProviderFactory(context -> (node, tagName, attributes) -> {
            if (node instanceof Paragraph) {
                attributes.put("class", "lead");
            }
        });
    }
}

Replace the converter

Declare a bean implementing MdConverter, which receives the Markdown text and returns the HTML, to replace the CommonMark converter. The section and the markdownify and mdToHtml template extension methods then use your bean, and the CommonMark extensions and their configuration properties no longer apply.

@Singleton
public class SiteConverter implements MdConverter {
    @Override
    public String html(String text) {
        return mySiteRenderer.render(text);
    }
}

Extension Configuration Reference

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

Configuration property

Type

Default

quarkus.qute.web.markdown.plugin.tables.enabled

Whether the plugin is enabled or not.

Environment variable: QUARKUS_QUTE_WEB_MARKDOWN_PLUGIN_TABLES_ENABLED

boolean

true

quarkus.qute.web.markdown.plugin.autolink.enabled

Whether the plugin is enabled or not.

Environment variable: QUARKUS_QUTE_WEB_MARKDOWN_PLUGIN_AUTOLINK_ENABLED

boolean

true

quarkus.qute.web.markdown.plugin.heading-anchor.enabled

Whether the plugin is enabled or not.

Environment variable: QUARKUS_QUTE_WEB_MARKDOWN_PLUGIN_HEADING_ANCHOR_ENABLED

boolean

true

quarkus.qute.web.markdown.plugin.alerts.enabled

Whether the plugin is enabled or not.

Environment variable: QUARKUS_QUTE_WEB_MARKDOWN_PLUGIN_ALERTS_ENABLED

boolean

true

quarkus.qute.web.markdown.plugin.alerts.custom-types."custom-types"

Custom alert types beyond the standard GFM types (NOTE, TIP, IMPORTANT, WARNING, CAUTION).

Key is the alert type (must be uppercase), value is the display title.

Example configuration:

quarkus.qute.web.markdown.plugin.alerts.custom-types.INFO=Information
quarkus.qute.web.markdown.plugin.alerts.custom-types.BUG=Known Bug

Environment variable: QUARKUS_QUTE_WEB_MARKDOWN_PLUGIN_ALERTS_CUSTOM_TYPES__CUSTOM_TYPES_

Map<String,String>

{}