quarkiverse/quarkus-roq/meta-inf

Quarkus Roq

Roq is a static site generator with a Java soul and Quarkus energy. The full quarkus-roq extension includes quarkus-roq-frontmatter (template engine) plus the static site generator, CLI, themes, LLMs.txt, and testing support.

For FrontMatter pages, layouts, collections, pagination, template variables, Qute syntax, built-in tags, data files, template extensions, configuration, and common pitfalls, see the quarkus-roq-frontmatter skill. Everything below is additional to what that skill provides.

Directory Structure

With the full quarkus-roq extension, directories are at the project root (not src/main/resources/ as in standalone FrontMatter):

content/                    # Pages and collections
  index.html                # Site index page (required)
  about.md                  # Standalone page
  posts/                    # Collection directory
    2024-08-29-my-post.md   # Date-based document
  rss.xml                   # RSS feed page
data/                       # JSON/YAML data files
  authors.yaml
  menu.json
templates/                  # Qute layout templates
  layouts/                  # Layout files
    main.html
  partials/                 # Reusable template fragments
    header.html
public/                     # Static assets served as-is
  images/                   # Default image directory
  static/                   # Static files
src/main/resources/
  web/app/                  # Web Bundler assets (CSS/JS/TS)

Themes

Theme layout resolution: layout: page resolves local first (templates/layouts/page.html), then falls back to the theme layout (theme-layouts/<theme-name>/page) when site.theme is configured. Use theme-layout: page to explicitly target the theme layout. The base theme (roq-base, the default) provides: default, page, post. The full default theme (roq-default, installed via roq create) provides: default, main, post, page, index, blog, home, tag, 404. Override any theme layout by placing a file at templates/layouts/<layout>.html with theme-layout: <layout> in frontmatter to inherit from the theme version.

RSS Feed

Create content/rss.xml:

---
---
{#include fm/rss.html /}

{#rss site /} is automatically included in the base theme layout and all built-in themes. If you use a custom layout that overrides {#head-meta}, add it to your <head>.

Use contentLimit to control <content:encoded>: omit for description only (default), contentLimit=0 for full rendered content, contentLimit=N for a word-limited content abstract (e.g. {#include fm/rss.html contentLimit=150 /}).

LLMs.txt

Generate /llms.txt and /llms-full.txt for AI discoverability. Create content/llms.qute.txt:

{#include fm/llms.html}

And content/llms-full.qute.txt:

{#include fm/llms-full.html}

Exclude pages with llmstxt: false in frontmatter, or with no-index-all: true to exclude them from every index at once (llms.txt, sitemap, search) and default their robots meta tag to noindex.

Static Generation

Build and export as a static site:

roq generate

Output goes to target/roq/. Preview with:

roq serve

Key configuration (application.properties):

quarkus.roq.generator.batch=true
quarkus.roq.generator.output-dir=roq
quarkus.roq.generator.paths=/,/static/**
quarkus.roq.generator.timeout=60

For GitHub Pages deployment, use the Roq GitHub Action or configure your CI to build with quarkus.roq.generator.batch=true and deploy the target/roq/ directory.

Testing

@QuarkusTest
@RoqAndRoll
@TestProfile(MyProfile.class)
public class MySiteTest {
 
    @Test
    public void testHomePage() {
        RestAssured.when().get("/")
            .then().statusCode(200)
            .body(containsString("Welcome"));
    }
 
    @Test
    public void testBlogPost() {
        RestAssured.when().get("/posts/my-post")
            .then().statusCode(200)
            .body("html.head.title", containsString("My Post"));
    }
 
    public static class MyProfile implements QuarkusTestProfile {
        @Override
        public String getConfigProfile() { return "roq-and-roll"; }
    }
}

Uses @RoqAndRoll(port=8082) from the roq-testing module with REST Assured for HTTP assertions.

CLI Commands (complete list, there is NO roq dev command)

• roq create my-site — create a new site with the default theme. Options: -x theme:base for minimal theme, -x plugin:tagging,plugin:series to add plugins, --no-code to skip example content, --gradle for Gradle, -g io.myorg to set group ID
• roq start — start dev mode with live-reload on http://localhost:8080. Most changes are automatically picked up by hot reload. Use -p 9090 to set a custom port. Press s to force a soft restart if hot reload doesn't detect a change
• roq generate — build static site to target/roq/
• roq serve — preview generated site (default port 8181, use -p to change)
• roq add plugin:tagging — add a plugin or theme
• roq update — update the Roq/Quarkus project to latest versions
• roq blog — list blog posts from a Roq site RSS feed

AI Agent Integration

AI coding agents should use Quarkus Agent MCP to manage Roq dev servers. Install: jbang app install --fresh --force quarkus-agent-mcp@quarkusio. Configure as an MCP server in your AI tool (e.g. claude mcp add quarkus-agent -- jbang quarkus-agent-mcp@quarkusio). The agent uses quarkus_start to launch the dev server, quarkus_restart for soft restart, quarkus_logs to read output, and quarkus_searchTools / quarkus_callTool to interact with the running app. The roq start CLI command is for interactive user sessions.