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 asciidoc to produce content.

There are two implementations of Asciidoc for Roq:

  1. Asciidoc (Java): Provides fast startup and native build compatibility but has limited features and does not support extensions.

  2. Asciidoc JRuby: Offers the full feature set of Asciidoctor but is slower to start and incompatible with native builds.

To install it:

quarkus ext add quarkus-roq-plugin-asciidoc

or

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

Once done, every file with either '.adoc' or '.asciidoc' extension will be processed.

For better security, Asciidoc includes have been disabled, use Qute includes instead.

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.

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 no idenxing
layout: roq-default/default
search: false
---

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.