Plugins

If you find any issue or missing info, be awesome and edit this document to help others Roqers.

Roq Plugin Tagging (Tags)

This plugin allows to generate a dynamic (derived) collection based on a given collection tags. For example, let’s consider the posts collection, if multiple posts have tags: guide, then we would generate a /posts/tag/guide page for all the posts containing the guide tag. This works for any collection.

To install it:

quarkus ext add quarkus-roq-plugin-tagging

If you are using a theme that supports it (includes a tagging layout), you should now have tags pages available for all the tags in your posts!

You can use theme override to customize the theme tagging layout.

To enable tagging without a theme, create a layout template and add tagging: [collection id] in FM. As a result you will have access to a new derived collection named tagCollection. It is available through site.collections.get(page.data.tagCollection):

templates/layouts/tag.html
---
layout: main
tagging: posts
---

{#for post in site.collections.get(page.data.tagCollection)}
  <div>{post.title}</div>
{/for}

This also support pagination like any other collection, as tagging is already specifying the target collection, pagination can be enabled just with in FM paginate: true:

templates/layouts/tag.html
---
layout: main
tagging: posts
paginate: true
---

{#for post in site.collections.get(page.data.tagCollection).paginated(page.paginator)}
  <div>{post.title}</div>
{/for}

Roq Plugin Aliases (Redirections)

This plugin allows creating one or many aliases (redirections) for a page.

To install it:

quarkus ext add quarkus-roq-plugin-aliases

For example, consider that you want to create a shortened link for your post.

To create an alias, create a page and add aliases: [your-alias-here, another-alias-here] in the Front Matter (FM). As a result, you will have the possibility to access the page using a customized URL as alias.

content/posts/2024-08-29-welcome-to-roq.md
---
layout: :theme/post
title: "Welcome to Roq!"
date: 2024-08-29 13:32:20 +0200
description: This is the first article ever made with Quarkus Roq
img: posts/2024/08/blogging.jpg
tags: blogging
author: ia3andy
aliases: [first-roq-article-ever]
---

Now, when you access the URL http://localhost:8081/first-roq-article-ever, you will be redirected to the 2024-08-29-welcome-to-roq blog post.

you can use link templating in aliases

Roq Plugin AsciiDoc

This plugin allows to use Asciidoctor as a markup language to produce content.

There are two implementations of Asciidoc for Roq:

  1. Asciidoc JRuby: Offers the full feature set of Asciidoctor but is a bit slower to start (based on asciidoctorj

    quarkus ext add quarkus-roq-plugin-asciidoc-jruby

  2. Asciidoc (Java): Provides fast startup but does not support all Asciidoc options yet (based on asciidoc-java which is actively maintained).

    quarkus ext add quarkus-roq-plugin-asciidoc

Then, add the '.adoc' or '.asciidoc' file extension on page or document 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 files from all the site directory. Just make sure the included file is ignored by Roq by prefixing the file or the 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.name 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 use as page description.

  • attributes starting with page- will be used as page data (:page-image: → image in the data)

  • all other header attributes are also available in page.data.attributes.

You can also use FrontMatter header 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 site url (e.g. https://my-site.com/blog/about/)

{page-path}

The site path (e.g. /blog/about)

Asciidoc Attributes

Attributes can be configured:

  • Globally in the configuration:

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

  • As an include file in the Asciidoc headers:

    = Hello
include::_includes/attributes.adoc[]

  • As part of the Frontmatter data asciidoc-attributes in a page or in a layout:

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

Table of Content (TOC)

To add a Table of Content, you can either use the Asciidoc solution and make it part of the content or add this script to your site (source: Antora).

This will add a dynamic TOC in the <aside class="toc sidebar"></aside> of your layout. You can specify the title and content using data-title and data-levels attributes.

Roq Plugin Markdown

This plugin allows to use markdown to produce content.

Markdown plugin is already included in Quarkus Roq extension.

To install it run:

quarkus ext add quarkus-roq-plugin-markdown

Once done, every file with either '.md' or '.markdown' extension will be processed.

Roq Plugin QR Code

This plugin allows you to add a QR Code to your website.

To install it run:

quarkus ext add quarkus-roq-plugin-qrcode

Then create a template and add the \{#qrcode …​} tag to it and style and size it as you want.

By default, the plugin produces HTML output compatible with both HTML and MarkDown templates. To use the plugin with asciidoc, set the asciidoc attribute to true (the default is false).

{#qrcode value="https://luigis.com/menu/" alt="Luigi's Menu" foreground="#000066" background="#FFFFFF" width=300 height=300 /} // Will generate HTML code
{#qrcode value="https://luigis.com/menu/" alt="Luigi's Menu" foreground="#000066" background="#FFFFFF" width=300 height=300 asciidoc=true/} // Will save the file in the static folder and generate an asciidoc image macro pointing to it

Roq Plugin Series

This plugin allows you to join multiple posts in a series.

To install it run:

quarkus ext add quarkus-roq-plugin-series

Edit the layout for your posts, for example when using roq-default theme:

templates/layouts/roq-default/post-series.html
---
layout: theme-layouts/roq-default/post
---

{#include partials/roq-series /} (1)

{#insert /} (2)
1 This will add the series partial before the post content, if it’s declared.
2 This is the post content

And finally, use this layout and add the series attribute in the Front Matter of the posts you want to join.

---
layout: series-post
title: Assemble you blog post in a series
description: Automatically series header for your posts
tags: plugin, frontmatter, guide, series
author: John Doe
series: My series Title (1)
---
1 You should use the exact same title for all documents in the series.

Roq Plugin Sitemap

This plugin allows you to easily create a sitemap.xml for your site.

To install it run:

quarkus ext add quarkus-roq-plugin-sitemap

Then create a new sitemap file:

content/sitemap.xml
{#include fm/sitemap.xml}

You are all set!

To remove pages from the sitemap, use sitemap: false in the FM data.

Browse http://localhost:8080/sitemap.xml.

Roq Plugin Lunr (Search)

This plugin enables search for your site without the need for external, server-side, search services.

Search

To install it you will to do the following:

  1. Add the plugin:

    quarkus ext add quarkus-roq-plugin-lunr

  2. Add the search index json:

    content/search-index.json
    {#include fm/search-index.json}

  3. Inject the search script in the <head> of your layout. For example with the default theme:

    templates/layouts/roq-default/default.html
    ---
layout: theme-layouts/roq-default/default
---

{#insert /}

{#head}
{#search-script /}
{/}

...

  4. Inject the search result overlay in the <body> and search button in the navigation. For example with the default theme:

    templates/layouts/roq-default/main.html
    ---
layout: theme-layouts/roq-default/main
---

{#search-overlay /}
{#insert /}

{#menu}
{#search-button /}
{#include partials/roq-default/sidebar-menu menu=cdi:menu.items /}
{/}

...

You can prevent content from being indexed using Frontmatter data:

---
title: I don't want to be indexed
search: false
---

You can also boost specific pages or layouts in the results:

---
title: I want to be first in the result
search-boost: 30
---

Roq Plugin Diagram

If you’re using ROQ you already know that documentation-as-code will soon rule the world, and you probably also know diagram-as-code is its little brother.

The diagram as code helps you use almost every diagram-as-code language by leveraging Kroki.io.

It delegates image rendering to Kroki either by using a provided server or by popping a dev service.

Please take a look at the full reference documentation.

To install it, you will to do the following:

  1. Add the plugin:

    quarkus ext add quarkus-roq-plugin-diagram

  2. Use it in your content:

    {#diagram asciidoc=true language="pikchr" alt="Impossible trident" width=500 height=500 diagramOutputFormat="svg"}

scale = 1.0
eh = 0.5cm
ew = 0.2cm
ed = 2 * eh
er = 0.4cm
lws = 4.0cm
lwm = lws + er
lwl = lwm + er

ellipse height eh width ew
L1: line width lwl from last ellipse.n
line width lwm from last ellipse.s
LV: line height eh down

move right er down ed from last ellipse.n
ellipse height eh width ew
L3: line width lws right from last ellipse.n to LV.end then down eh right ew
line width lwm right from last ellipse.s then to LV.start

move right er down ed from last ellipse.n
ellipse height eh width ew
line width lwl right from last ellipse.n then to L1.end
line width lwl right from last ellipse.s then up eh
{/}

You can either use a deployed server or let the dev services provide one for you, but in this case you won’t have all languages available.

Just try it, you’ll see what it does.