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.0</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.0</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, and tables Markdown extensions. If you want to disable any of them, you can do so using configuration properties.

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