### Install Theme

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/templates/layouts/marketplace-detail.html

Use this command to install a theme from the marketplace. Ensure you have the 'roq' CLI installed.

```bash
$ roq create -x theme:{=page.data.install-name}
```

--------------------------------

### Start the Roq development server

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/posts/2026-02-02-set-it-in-roq-the-editor-that-change-the-game/index.md

Run this command to start the Roq development server.

```bash
roq
```

--------------------------------

### Install All Roq Extensions

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/CONTRIBUTING.md

Clean and install all Roq extensions using Maven. This is a prerequisite for certain development tasks.

```shell
mvn clean install
```

--------------------------------

### Start Roq Blog Dev Server

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/CLAUDE.md

Starts the Roq blog development server on a specified port. Ensure you are in the 'blog' directory. Press 's' for soft restarts.

```bash
cd blog && roq start -p <port>
```

--------------------------------

### Start Roq Development Mode

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/getting-started.html

Start the Roq development server to see your site in action. Access it at http://localhost:8080.

```bash
roq start
```

--------------------------------

### Snippet A Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/roq-plugin/asciidoc-jruby/integration-tests/src/main/resources/content/guides/_includes/foo/tags.adoc

This is snippet a. It serves as an example within the Quarkus Roq project.

```java
snippet a
```

--------------------------------

### Install Roq via JBang

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/templates/partials/llms-skills.html

Installs the Roq static site generator using JBang. Ensure you have JBang installed before running this command.

```bash
curl -Ls https://sh.jbang.dev | bash -s - app install --fresh --force roq@quarkiverse/quarkus-roq
```

--------------------------------

### Install Sitemap Plugin

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/posts/2025-01-08-easily-generate-a-sitemap-xml-for-your-site-with-roq/index.md

Use this command to add the sitemap plugin to your Roq project.

```shell
roq add plugin:sitemap
```

--------------------------------

### Start Roq development mode

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/templates/partials/llms-skills.html

Starts the Roq development server with live reloading. You can specify a custom port or force a soft restart.

```bash
cd my-site && roq start
```

```bash
roq start -p 9090
```

--------------------------------

### Snippet B Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/roq-plugin/asciidoc-jruby/integration-tests/src/main/resources/content/guides/_includes/foo/tags.adoc

This is snippet b. It serves as another example within the Quarkus Roq project.

```java
snippet b
```

--------------------------------

### Install Other Marketplace Item

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/templates/layouts/marketplace-detail.html

Use this command to add other types of marketplace items (not themes) using the 'roq' CLI.

```bash
$ roq add {=page.data.kind}:{=page.data.install-name}
```

--------------------------------

### Initial Tailwind CDN Setup

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/posts/2026-05-06-how-ai-helped-me-rebuild-my-blog-and-move-from-jekyll-to-quarkus-roq/index.md

This HTML snippet shows the initial setup for Tailwind CSS using a CDN, which is suitable for development but not for production.

```html
<script src="https://cdn.tailwindcss.com"></script>
<script>
  tailwind.config = {
    darkMode: "class",
    theme: {
      extend: {
        fontFamily: { ... },
        boxShadow: { ... }
      }
    }
  }
</script>
```

--------------------------------

### Create and Run a New Roq Blog with CLI

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/posts/2026-05-04-roq-2-1-is-here/index.md

Use the standalone Roq CLI to create a new blog project, navigate into it, and start the development server.

```bash
roq create my-blog
cd my-blog
roq
```

--------------------------------

### Starting Roq in Development Mode with Increased Memory

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/migrating.adoc

Starts the Roq development server with JVM arguments to allocate 4GB of memory. This is useful for measuring build performance with larger sites.

```shell
roq start -Djvm.args="-Xmx4g"
```

--------------------------------

### Data Directory Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/docs/modules/ROOT/pages/quarkus-roq-data.adoc

Example of a directory structure within the 'data' folder. Each file is processed individually and also grouped into a parent object.

```text
data/heroes/
  batman.yaml    # { "name": "Batman", "city": "Gotham" }
  superman.yaml  # { "name": "Superman", "city": "Metropolis" }
```

--------------------------------

### Install Roq CLI with JBang

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/getting-started.html

Install the Roq CLI using JBang. This command will also install JBang if it's not already present on your system.

```bash
jbang app install io.quarkiverse.roq:roq-cli@latest
```

--------------------------------

### Create a new Roq site

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/templates/partials/llms-skills.html

Creates a new Roq site with the default theme and example content. Use the -x flag for a minimal HTML structure.

```bash
roq create my-site
```

```bash
roq create my-site -x theme:base
```

--------------------------------

### Create Roq Starter App

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/posts/2024-10-31-roq-with-blogs/index.md

Use the Roq CLI to generate a new Roq Starter App. Navigate into the generated directory and run 'roq' to start the development server.

```shell
roq create
cd blog-with-roq
roq
```

--------------------------------

### Start Roq Blog with Maven

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/CONTRIBUTING.md

Run the blog locally with live reload using Maven's development mode. This is an alternative to using the Roq CLI.

```shell
cd blog && mvn quarkus:dev
```

--------------------------------

### Basic SCSS Card Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/marketplace/web/sass.md

Example of an SCSS file demonstrating the use of variables for color and border-radius, along with nesting for styling card elements.

```scss
// web/style.scss
$primary: #3b82f6;
$radius: 0.5rem;

.card {
  border-radius: $radius;
  background: white;

  &-title {
    color: $primary;
    font-weight: 600;
  }
}
```

--------------------------------

### Open the Roq Editor

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/posts/2026-02-02-set-it-in-roq-the-editor-that-change-the-game/index.md

After starting the Roq server, press 'm' to access the Roq Editor UI for managing content.

```bash
m
```

--------------------------------

### Add Default Theme

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/basics.adoc

Installs the default theme dependency into an existing project.

```shell
roq add theme:default
```

--------------------------------

### Array JSON Data File Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/docs/modules/ROOT/pages/quarkus-roq-data.adoc

Example of a JSON file where the root element is an array. This will be mapped to a list of objects.

```json
[
    {
        "name": "Lhotse",
        "elevation": 8516
    },
    {
        "name": "Everest",
        "elevation": 8849
    }
]
```

--------------------------------

### Java Greeting Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/roq-plugin/asciidoc-jruby/integration-tests/src/main/resources/content/guides/my-doc.adoc

A simple Java class demonstrating a greeting functionality, potentially used as a base for messaging examples.

```java
package org.acme.messaging.amqp;

import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class GreetingService {

    public String greeting(String name) {
        return "hello " + name;
    }

}
```

--------------------------------

### Define YAML Data File

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/basics.adoc

Example of a simple YAML data file placed in the `data/` directory.

```yaml
bar: Roq
```

--------------------------------

### Basic Pagination Setup in Frontmatter

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/posts/2024-09-20-mastering-pagination-in-roq/index.md

Configure pagination for a collection in your page's frontmatter. Set the collection to paginate.

```yaml
layout: main
paginate: posts
```

--------------------------------

### Blog Site Structure

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/CLAUDE.md

Details the directory layout for the example blog site, including content, templates, and static assets.

```text
blog/
├── content/              # Site content
│   ├── docs/            # Documentation pages (AsciiDoc)
│   ├── posts/           # Blog posts (Markdown/AsciiDoc)
│   └── markups/         # Markup testing pages (not indexed)
├── templates/           # Custom templates/layouts
│   ├── layouts/         # Page layouts (flat, no theme subdirs)
│   └── partials/        # Reusable template fragments
├── data/                # Static data files (YAML/JSON)
├── includes/            # AsciiDoc includes
├── public/              # Static assets (images, etc.)
├── web/                 # Frontend assets (JS/CSS)
├── config/              # Configuration files
└── src/                 # Custom Java code (optional)
```

--------------------------------

### YAML Configuration with Callouts

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/markups/asciidoc.adoc

A YAML configuration example with numbered callouts. Each callout points to a specific configuration setting, such as server port, host, or database URL.

```yaml
server:
  port: 8080 // <1>
  host: localhost // <2>
database:
  url: jdbc:postgresql://localhost:5432/mydb // <3>
  username: admin
```

--------------------------------

### Start Roq Blog with Live Reload

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/CONTRIBUTING.md

Run the blog locally with live reload enabled using the Roq CLI. This is ideal for active development and content creation.

```shell
cd blog && roq start
```

--------------------------------

### Blog Post Template with Front Matter

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/basics.adoc

Example of a page template using Qute and front matter for metadata like title, date, and author.

```yaml
---
title: "My First Blog Post"
date: 2025-09-08
author: "Andy"
layout: post
tags: qute, roq, tutorial
---

**Hello World**
```

--------------------------------

### Roq CLI Development and Build Commands

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/roq-cli/src/main/resources/roq-base/README.md

Commands to start Roq in development mode with live reloading, generate the static site, and serve the generated site for preview.

```bash
# Start dev mode with live-reload
roq start

# Build the static site
roq generate

# Preview the generated site
roq serve
```

--------------------------------

### Qute Template Iteration Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/roq-data/deployment/src/main/resources/META-INF/quarkus-skill.md

Demonstrates iterating over a JSON array (contributors) within a Qute template.

```html
{#for contributor in cdi:contributors.contributors}
  <span>{contributor.name} ({contributor.role})</span>
{/for}
```

--------------------------------

### Run Roq Generator Standalone

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/docs/modules/ROOT/pages/quarkus-roq-generator.adoc

After installation, you can run the Roq generator using this command. It will serve the static files from the `target/roq` directory on `http://localhost:8181`.

```shell
$ jbang app install --fresh roq@quarkiverse/quarkus-roq
$ roq                                                                                                                         decks->!+(ia3andy/decks)
Serving: target/roq/
Server started on port http://localhost:8181
```

--------------------------------

### Profile Data Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/marketplace/themes/resume-theme/index.md

Define your basic personal information for the resume. This includes name, job title, location, and a short biography.

```yaml
firstName: Ada
lastName: Lovelace
jobTitle: Computational Pioneer
city: London
country: United Kingdom
bio: |
  Ada Lovelace was a 19th-century mathematician known for her
  visionary work on Charles Babbage's Analytical Engine.
```

--------------------------------

### Root Qute Layout Template Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/roq-frontmatter/deployment/src/main/resources/META-INF/quarkus-skill.md

Demonstrates the root Qute layout template (`default.html`) which sets up the basic HTML structure, including head elements and body content insertion.

```html
{@io.quarkiverse.roq.frontmatter.runtime.model.Page page}
{@io.quarkiverse.roq.frontmatter.runtime.model.Site site}
<!DOCTYPE html>
<html>
<head>
  <title>{page.title}</title>
  {#seo page site /}
  {#rss site /}{! adds the RSS <link> tag !}
  {#insert head /}
</head>
<body>
  {#insert /}
</body>
</html>
```

--------------------------------

### YAML Data File Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/roq-data/deployment/src/main/resources/META-INF/quarkus-skill.md

Defines author data in a YAML file. This data can be accessed directly in Qute templates.

```yaml
ia3andy:
  name: Andy
  url: https://github.com/ia3andy
john:
  name: John Doe
  url: https://example.com
```

--------------------------------

### Java Hello World Program

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/markups/markdown.md

A basic Java program to print 'Hello, World!' to the console. This is a common starting point for Java development.

```java
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}
```

--------------------------------

### Basic Roq Site Generation Test

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/posts/2025-01-28-roq-n-roll-your-tests/index.md

Use the `@QuarkusTest` and `@RoqAndRoll` annotations to verify that all pages are generated without errors during test setup.

```java
@QuarkusTest
@RoqAndRoll
public class RoqSiteTest {
    
    @Test
    public void testGen() {
        // All pages will be generated/validated during test setup
    }
}
```

--------------------------------

### Inject Search Overlay and Button

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/marketplace/plugins/lunr-search.md

Inject the search overlay into the `<body>` and the search button into the navigation. This example uses the 'main' theme layout.

```html
<!-- templates/layouts/main.html -->
---
theme-layout: main
---

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

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

```

--------------------------------

### Social Links Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/marketplace/themes/resume-theme/index.md

List your social media profiles or personal website links. Each entry requires a name and a URL.

```yaml
- name: LinkedIn
  url: https://www.linkedin.com/in/ada-lovelace/
- name: X
  url: https://x.com/ada-lovelace
```

--------------------------------

### Qute Layout Template Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/roq-frontmatter/deployment/src/main/resources/META-INF/quarkus-skill.md

Shows a basic Qute layout template (`main.html`) that includes a main content area and uses page and site objects.

```html
---
layout: default
---
{@io.quarkiverse.roq.frontmatter.runtime.model.Page page}
{@io.quarkiverse.roq.frontmatter.runtime.model.Site site}
<main>
  <h1>{page.title}</h1>
  {#insert /}
</main>
```

--------------------------------

### Qute Template Let Binding Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/roq-data/deployment/src/main/resources/META-INF/quarkus-skill.md

Shows how to use let bindings in Qute templates for cleaner access to nested data, like retrieving an author by ID.

```html
{#let author=cdi:authors.get(page.data.author)}
  <a href="{author.url}">{author.name}</a>
{/let}
```

--------------------------------

### List Roq Maven dependencies

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/templates/partials/llms-skills.html

Lists all installed Roq extensions and their versions in your local Maven repository. This is useful for identifying which skill files to extract.

```bash
mvn dependency:list -DincludeGroupIds=io.quarkiverse.roq -DoutputAbsoluteArtifactFilename=true
```

--------------------------------

### Accessing Page or Document by Source Path

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/basics.adoc

Shows how to get a page or document by its source path using `site.page(String sourcePath)`.

```html
site.page(‘foo.html’).url.absolute
```

--------------------------------

### Use a User Tag

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/basics.adoc

Shows how to use a previously defined user tag in another template. This example includes a post using the 'post-link' tag.

```html
{#post-link post=site.document('posts/2025-09-08-my-article.md')/}
```

--------------------------------

### Install Quarkus Agent MCP

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/CLAUDE.md

Installs the Quarkus Agent MCP using jbang. Use the --fresh and --force flags for a clean installation.

```bash
jbang app install --fresh --force quarkus-agent-mcp@quarkusio
```

--------------------------------

### Accessing Data Files in Roq

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/migrating.adoc

Roq accesses data files as CDI beans, differing from Jekyll's Liquid syntax. This example demonstrates the Qute syntax for accessing a data file.

```qute
+{=cdi:filename.key}+
```

--------------------------------

### Create a new Roq blog

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/posts/2026-02-02-set-it-in-roq-the-editor-that-change-the-game/index.md

Use this command to create a new blog project with Roq.

```bash
roq create my-blog
```

--------------------------------

### Quarkus Roq Testing Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/roq/deployment/src/main/resources/META-INF/quarkus-skill.md

Example of how to test a Quarkus Roq site using `@QuarkusTest`, `@RoqAndRoll`, and REST Assured.

```java
@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";
        }
    }
}

```

--------------------------------

### Generate a new blog with Roq

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/index.html

Use the Roq CLI to generate a new blog project. This command initializes a new site structure.

```bash
$ roq blog
```

--------------------------------

### Build static site with Roq

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/templates/partials/llms-skills.html

Generates the static site output in the target/roq/ directory. Use 'roq serve' to preview the generated site.

```bash
roq generate
```

```bash
roq serve
```

--------------------------------

### JSON Data File Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/docs/modules/ROOT/pages/quarkus-roq-data.adoc

Example of a JSON file that will be registered as a CDI bean. The bean name is derived from the filename.

```json
{
    "name": "Lhotse",
    "elevation": 8516
}
```

--------------------------------

### Create a new Roq project with the base theme

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/migrating.adoc

Initialize a new Roq project using the base theme for more control over design and to build custom layouts from scratch. This theme provides minimal HTML structure with SEO, favicon, and Web Bundler.

```shell
roq create my-site -x theme:base
```

--------------------------------

### Initialize Highlight.js in main.js

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/posts/2024-09-20-how-to-add-syntax-highlighting-to-your-roq-site/index.md

Import Highlight.js and its SCSS theme, then call highlightAll() to enable syntax highlighting for code blocks in your Roq site.

```javascript
import hljs from 'highlight.js';
import 'highlight.js/scss/monokai.scss';

hljs.highlightAll();
```

--------------------------------

### Static Site Generation Command

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/roq/deployment/src/main/resources/META-INF/quarkus-skill.md

Build and export the project as a static site. Output is directed to `target/roq/`.

```bash
roq generate

```

--------------------------------

### Qute Syntax Essentials

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/roq-frontmatter/deployment/src/main/resources/META-INF/quarkus-skill.md

Demonstrates basic Qute templating constructs including expressions, conditionals, loops, includes, layout insertion, URL resolution, CDI bean access, let bindings, and type declarations.

```html
{! Expressions !}
{page.title}
{page.data.customField}
{page.date.format('yyyy, MMM dd')}

{! Conditionals !}
{#if page.image}...{/if}
{#if page.data.author??}...{/if}

{! Loops !}
{#for post in site.collections.posts}...{/for}
{#for tag in page.data.tags.asStrings}...{/for}

{! Include partial !}
{#include partials/header /}

{! Layout insertion point (in layouts) !}
{#insert /}
{#insert head /}
{#insert menu}{#include partials/sidebar-menu /}{/}

{! URL resolution !}
<a href="{site.url('posts/my-post')}">Link</a>
<a href="{site.url('docs', 'getting-started')}">Docs</a>

{! CDI beans (data files) !}
{cdi:authors.ia3andy.name}
{#for item in cdi:contributors.contributors}{item.name}{/for}

{! Let bindings !}
{#let author=cdi:authors.get(page.data.author)}
  {author.name}
{/let}

{! Slugify !}
{#let tagSlug=tag.slugify}
  <a href="{site.url('/posts/tag', tagSlug)}">{tagSlug}</a>
{/let}

{! Type declarations (in layouts) !}
{@io.quarkiverse.roq.frontmatter.runtime.model.Page page}
{@io.quarkiverse.roq.frontmatter.runtime.model.Site site}
{@io.quarkiverse.roq.frontmatter.runtime.model.DocumentPage page}

{! Escaping Qute in content (standard syntax only) !}
\{not-a-qute-expression}
```

--------------------------------

### RSS Feed with Limited Content

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/basics.adoc

Example of limiting the content in the RSS feed to an abstract of 150 words by setting `contentLimit=150`.

```html
{#include fm/rss.html contentLimit=150 /}
```

--------------------------------

### Bio Data Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/marketplace/themes/resume-theme/index.md

Structure your work experience and education history. Supports hierarchical items, collapsible sections, and separators.

```yaml
- title: Experience
  items:
    - header: "1842 - 1843"
      title: "Mathematician · Self-initiated · London"
      content: |
        Translated and annotated Luigi Menabrea's paper on Charles
        Babbage's Analytical Engine. Added extensive original notes, including the first published algorithm designed for a machine.

- title: Education
  items:
    - header: "1830 - 1835"
      title: "Private Tutoring"
      content: |
        Studied mathematics and science under Augustus De Morgan
        and Mary Somerville.
```

--------------------------------

### Generate Roq Site with CLI

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/publishing.adoc

Use the Roq CLI to generate your static site. The site will be created in the `target/roq` directory.

```shell
roq generate
```

--------------------------------

### Generate and Serve Static Blog Site

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/CONTRIBUTING.md

Generate the static version of the blog and serve it locally. This is useful for previewing the site before deployment.

```shell
cd blog && roq generate
roq serve
```

--------------------------------

### Static Site Preview Command

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/roq/deployment/src/main/resources/META-INF/quarkus-skill.md

Preview the generated static site. This command serves the content from the output directory.

```bash
roq serve

```

--------------------------------

### Display Collection Sizes

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/roq-frontmatter/deployment/src/test/collection-site/content/index.html

Use this to display the total number of items in different collections like 'posts', 'guides', and 'list'.

```liquid
{site.collections.posts.size}
{site.collections.guides.size}
{site.collections.list.size}
```

--------------------------------

### Create a New Roq Site

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/getting-started.html

Create a new Roq site. By default, it uses the default theme. To use the base theme for a minimal structure, append '-x theme:base'.

```bash
roq create my-site
```

--------------------------------

### Accessing Current Page Collection ID

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/basics.adoc

Shows how to get the collection ID if the current page is a document using `page.collection`.

```html
{page.collection}
```

--------------------------------

### JSON Array Data File Example

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/roq-data/deployment/src/main/resources/META-INF/quarkus-skill.md

Defines an array of contributor data in a JSON file. This is mapped using ARRAY_FILE type.

```json
[
  { "name": "Alice", "role": "maintainer" },
  { "name": "Bob", "role": "contributor" }
]
```

--------------------------------

### Standard GFM Alert Blocks

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/posts/2026-04-09-gfm-alert-blocks/index.md

Examples of standard alert block types in markdown: NOTE, TIP, IMPORTANT, WARNING, and CAUTION.

```markdown
> [!NOTE]
> Useful information that users should know, even when skimming content.
```

```markdown
> [!TIP]
> Helpful advice for doing things better or more easily.
```

```markdown
> [!IMPORTANT]
> Key information users need to achieve their goal.
```

```markdown
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
```

```markdown
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
```

--------------------------------

### Creating Links to Main Page and Next Page

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/advanced.adoc

Demonstrates how to create links to the main site page and the next page in a document sequence using Roq's site and page variables.

```html
<a href="{site.url}">Back to main page</a>
----
or to get the next page url in a document:
----
<a href="{page.next.url}">{page.next.title}</a>
```

--------------------------------

### Generate Static Site with Maven

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/docs/modules/ROOT/pages/quarkus-roq-generator.adoc

Use this command to package your Quarkus application and generate the static site. The output is by default in the `target/roq` directory.

```shell
QUARKUS_ROQ_GENERATOR_BATCH=true mvn package quarkus:run -DskipTests
```

--------------------------------

### Inject Search Script in Head

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/marketplace/plugins/lunr-search.md

Inject the search script into the `<head>` section of your layout. This example shows integration with the default theme.

```html
<!-- templates/layouts/default.html -->
---
theme-layout: default
---

{#insert /}

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

```

--------------------------------

### Produce RoqSelection for Dynamic Path Generation

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/docs/modules/ROOT/pages/quarkus-roq-generator.adoc

Implement a `RoqSelection` singleton to dynamically define which paths should be generated. Use `.html()` for HTML pages or specify `outputPath` for custom file names.

```java
@Produces
    @Singleton
    RoqSelection produce() {
        return new RoqSelection(List.of(
                SelectedPath.builder().html("/roq?name=foo").build(), // <1>
                SelectedPath.builder().html("/blog/hello-roq").build(), // <2>
                SelectedPath.builder().path("/api/hello?name=foo").outputPath("/hello-foo.json").build()));  // <3>
```

--------------------------------

### Define a User Tag

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/basics.adoc

Example of defining a custom reusable code snippet (tag) in an HTML file. Tags help reduce duplication in templates.

```html
{@io.quarkiverse.roq.frontmatter.runtime.model.DocumentPage post}
<div class="post-link">
    <a href="{post.url}">
      <img src="{post.image}" alt="{post.title}" class="post-image"/>
      <h3>{post.title}</h3>
      <p>{post.description}</p>
    </a>
</div>
```

--------------------------------

### Blog Post Collection Item

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/basics.adoc

Example of a content file for a blog post collection, including front matter for title, description, tags, and image.

```markdown
---

title: Roq bad puns
description: Roq is very good for bad puns 🤭
tags: <1>
  - funny
  - ai
img: 2024/10/roq-solid.jpg

---

```

--------------------------------

### Type-Safe Data Mapping for Records

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/advanced.adoc

Example of using `@DataMapping` on a Java record to create a typed CDI bean from a data file named 'mountain'.

```java
import io.quarkiverse.roq.data.runtime.annotations.DataMapping;

@DataMapping("mountain") // <1>
public record Mountain(String name, Integer elevation) {}
<1> The value must match the data filename (without extension).
```

--------------------------------

### Styling Custom Alert Types (SECURITY)

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/posts/2026-04-09-gfm-alert-blocks/index.md

Example CSS for styling a custom SECURITY alert type, specifying its color, icon, border, and background.

```css
.markdown-alert-security {
  --alert-color: #da3633;
  --alert-icon: url("data:image/svg+xml,..."); /* shield-16 SVG */
  border-color: #da3633;
  background: #da363308;
}
.markdown-alert-security .markdown-alert-title { color: #da3633; }
```

--------------------------------

### Add Roq plugin or theme

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/templates/partials/llms-skills.html

Adds a new plugin or theme to your Roq project. Ensure the plugin/theme name is correct.

```bash
roq add plugin:tagging
```

```bash
roq add theme:default
```

--------------------------------

### Styling Custom Alert Types (BUG)

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/posts/2026-04-09-gfm-alert-blocks/index.md

Example CSS for styling a custom BUG alert type, defining its color, icon, border, and background.

```css
.markdown-alert-bug {
--alert-color: #cf222e;
--alert-icon: url("data:image/svg+xml,..."); /* bug SVG as data URI */
border-color: #cf222e;
background: #cf222e08;
}
.markdown-alert-bug .markdown-alert-title { color: #cf222e; }
```

--------------------------------

### Jekyll Liquid to Roq Qute Syntax Comparison

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/migrating.adoc

A comparison table highlighting key syntax differences between Jekyll's Liquid templating language and Roq's Qute templating language for common concepts.

```asciidoc
| Variable output
| `+{{ page.title }}+`
| `+{=page.title}+`

| Conditional
| `+{% if page.image %}...{% endif %}+`
| `+{#if page.image}...{/if}+`

| Loop
| `+{% for post in site.posts %}...{% endfor %}+`
| `+{#for post in site.collections.get('posts')}...{/for}+`

| Include / partial
| `+{% include header.html %}+`
| `+{#include header.html /}+`

| Layout inheritance
| `layout: default` in front matter
| `layout: default` in front matter (same concept)

| Content insertion
| `+{{ content }}+`
| `+{#insert /}+`

| Date formatting
| `+{{ post.date | date: "%B %d, %Y" }}+`
| `+{=post.date.format('MMMM dd, yyyy')}+`

| Null / empty check
| `+{% if page.image %}+`
| `+{#if page.image}+` (Qute has different null semantics -- test carefully)
```

--------------------------------

### GitLab CI for Roq Site Build and Deploy

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/docs/publishing.adoc

This GitLab CI configuration outlines the stages for building and deploying a Roq site. The `build_roq` job uses Maven to generate the site, and the `deploy_roq` job deploys it to GitLab Pages.

```yaml
stages:
  - build
  - deploy

build_roq:
  # Look for appropriate maven docker images in https://hub.docker.com/_/maven/tags
  image: "maven:3.9.9-eclipse-temurin-23-alpine"
  stage: build
  # Generate the static site on merge request events and on the main branch
  script:
    - QUARKUS_ROQ_GENERATOR_BATCH=true mvn -B -q package quarkus:run
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  artifacts:
    reports:
      junit: target/surefire-reports/*.xml
    paths:
      - target/roq
      - target/surefire-reports

deploy_roq:
  image: alpine
  pages: true
  stage: deploy
  # For main branch take the artifacts from `build_roq` and deploy them.
  needs:
    - build_roq
  script:
    - cp -R target/roq public
    - echo "Quarkus Roq static site deployed to Gitlab Pages at $CI_PAGES_URL"
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  artifacts:
    paths:
      - public
```

--------------------------------

### Configure Fake Post Count

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/marketplace/plugins/faker.md

Set the number of fake documents to generate per collection in `application.properties`. This example generates 20 fake posts.

```properties
quarkus.roq.faker.count.posts=20
```

--------------------------------

### Roq Project Structure Overview

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/CLAUDE.md

Provides a high-level overview of the Roq project's multi-module Maven structure.

```text
quarkus-roq/
├── blog/                    # Example blog site (development/testing)
├── docs/                    # Project documentation
├── roq/                     # Core Roq extension
├── roq-common/              # Common utilities
├── roq-data/                # Data handling
├── roq-editor/              # Live preview editor
├── roq-frontmatter/         # Front matter processing (step-based pipeline, see PIPELINE.md)
├── roq-generator/           # Static site generation engine
├── roq-plugin/              # Plugin modules (see below)
├── roq-testing/             # Testing utilities
└── roq-theme/               # Theme modules (see below)
```

--------------------------------

### Rust Hello World Code Block

Source: https://github.com/quarkiverse/quarkus-roq/blob/main/blog/content/markups/asciidoc.adoc

A simple Rust program that prints 'Hello, world!' to the console. This serves as a basic example of Rust syntax and execution.

```rust
fn main() {
    println!("Hello, world!");
}
```