Quarkus Roq Generator

It provides a command to run any Quarkus web application and extract it in a directory as purely static files (html and assets).

Roq Generator is already included as part of the Roq Static Site Generator extension io.quarkiverse.roq:quarkus-roq, Follow Standalone installation section to use it standalone.

Generating your static site

You can generate your static site using:

QUARKUS_ROQ_GENERATOR_BATCH=true mvn package quarkus:run -DskipTests

By default, it will generate the static site in the target/roq directory.

When used within the Roq Static Site Generator extension, it is already pre-configured to generate the whole site (which can be disabled with site.generator=false). In standalone mode, by default, only the / (index.html) and static/** will be generated. Follow the next section to configure the selection.

You can now try or deploy your static website with any static file server. We provide a small tool to try it:

$ jbang app install --verbose --fresh --force roq@quarkiverse/quarkus-roq
$ roq                                                                                                                         decks->!+(ia3andy/decks)
Serving: target/roq/
Server started on port http://localhost:8181
at any time you can open the dev-ui to see the Roq Generator selection.

Github Pages configuration

You can configure Roq to deploy Github Pages, Netlify, or any static website server.

Check how the Roq blog is deployed on GitHub pages here.

Advanced Usage

Configure the static selection

You can configure application paths which should be generated as static files from the Quarkus configuration:

application.properties
quarkus.roq.generator.paths=/,/static/**,/bar/
By convention paths ending with / such as /bar/ are considered as html pages and with generate html pages such as /bar/index.html.
The glob syntax is only working with fixed paths. Paths which uses query params or path params should be either manually entered or provided at runtime from the Java code.

You can also manually specify the generated output path:

application.properties
quarkus.roq.generator.custom-paths."/api/foo"=/foo.json

Configure the dynamic selection

You need to produce a RoqSelection singleton from your application:

    @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)
    }
1 Using .html() means we want to generate an html page from roq?name=foo content, when unspecified we generate the output path automatically, in that case it would be /roq-name-foo/index.html.
2 in that case it will generate /blog/hello-roq/index.html.
3 It is also possible to manually specify the output path. In that case it will generate /hello-foo.json from /api/hello?name=foo content.
Use @Transactional if you need to iterate through database entities to prepare your selection. For example if the blog post ids are stored in a database.

Deploy to GitHub Pages

To create your GitHub Page with Roq:

  1. Open your GitHub repository page

  2. Go to Settings→Page

  3. Pick: Source: GitHub Actions

  4. Click on Static Html "Configure" button

  5. Paste this content (to adapt with Gradle):

.github/workflows/static.yml
## Deploy to GH-Pages for your Quarkus Roq blog.
name: Quarkus Roq Deploy CI

on:
  push:
    branches: [ main ]
  workflow_dispatch:

env:
  QUARKUS_ROQ_GENERATOR_BATCH: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: 21
          distribution: 'temurin'
          cache: 'maven'
      - name: Get GitHub Pages URL
        id: get_url
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          url=$(gh api "repos/$GITHUB_REPOSITORY/pages" --jq '.html_url');echo "ghp-url=$url";
          path=$(echo "$url" | sed -E 's|https?://[^/]+(/.*)?|\1|')
          url=$(echo "$url" | sed -E 's|(https?://[^/]+).*|\1|')
          if [ -z "$path" ]; then
            path="/"
          fi
          echo "SITE_URL=$url"; echo "SITE_URL=$url" >> $GITHUB_ENV;
          echo "SITE_PATH=$path"; echo "SITE_PATH=$path" >> $GITHUB_ENV;
      - name: Build & Generate Blog
        run: mvn -B package quarkus:run -DskipTests -Dquarkus.http.root-path=$SITE_PATH -Dsite.url=$SITE_URL
      - name: Upload site as artifact
        uses: actions/upload-artifact@v4
        with:
          name: site
          path: target/roq
          retention-days: 1
  deploy:
    runs-on: ubuntu-latest
    needs: build
    permissions:
      pages: write      # to deploy to Pages
      id-token: write   # to verify the deployment originates from an appropriate source
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Download Built site
        uses: actions/download-artifact@v4
        with:
          name: site
          path: _site
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
This is process will be improved in the near future (follow progress).

Standalone installation

It is included and pre-configured as part of the Roq Static Site Generator extension io.quarkiverse.roq:quarkus-roq.

You can also use it standalone on any Quarkus application. If you want to use this extension standalone, you need to add the io.quarkiverse.roq:quarkus-roq-generator extension first to your build file.

For instance, with Maven, add the following dependency to your POM file:

<dependency>
    <groupId>io.quarkiverse.roq</groupId>
    <artifactId>quarkus-roq-generator</artifactId>
    <version>1.0.5</version>
</dependency>

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.roq.generator.paths

The selected paths to include in the static website Glob syntax is authorized for non-dynamic resources (without query or path params)

For dynamic paths selection, produce a RoqSelection in you app.

`&++#++64;Produces
&++#++64;Singleton
&++#++64;Transactional
RoqSelection produce() ++{++
    return new RoqSelection(List.of(
            SelectedPath.builder().html("/roq?name=foo").build(),
            SelectedPath.builder().html("/blog/hello/").build(),
            SelectedPath.builder().path("/api/hello?name=foo").outputPath("/hello-foo.json").build()));`
}

Environment variable: QUARKUS_ROQ_GENERATOR_PATHS

list of string

/,/static/**

quarkus.roq.generator.custom-paths."custom-paths"

You can configure the path to get content from and the output path that will be generated.

Environment variable: QUARKUS_ROQ_GENERATOR_CUSTOM_PATHS__CUSTOM_PATHS_

Map<String,String>

quarkus.roq.generator.output-dir

Output directory for the static website relative to the target directory

Environment variable: QUARKUS_ROQ_GENERATOR_OUTPUT_DIR

string

roq

quarkus.roq.generator.batch

Build as a CLI to export the static website

Environment variable: QUARKUS_ROQ_GENERATOR_BATCH

boolean

false

quarkus.roq.generator.timeout

Timeout for generation in seconds

Environment variable: QUARKUS_ROQ_GENERATOR_TIMEOUT

long

30