Roq Release Notes

Want to follow Roq’s progress and update your project safely? You’re in the right place.

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

We aim to keep the API stable, but since Roq is still young, breaking changes may happen. The good news: almost all breakage will be caught during build or site generation tests.

Want to follow Roq’s progress and update your project safely? You’re in the right place.

Roq 2.1

  • ✏️ Built-in Block Editor: a powerful block editor right in your browser during dev mode, with live preview, front matter editing, and image management. No IDE needed to write your next post!

  • 🎨 Simplified layout resolution: layout: page now resolves local layouts first, then falls back to the theme. No more :theme/ prefix needed

  • 🎨 Default theme rewritten with TailwindCSS instead of SCSS for better maintainability and modern styling

  • 🌙 Built-in dark mode with automatic system preference detection

  • 🎨 Color palette system: three customizable palettes (accent, pop, neutral) via CSS variables

  • 🖼️ Favicon auto-discovery: automatically detects favicon.svg, favicon.ico, favicon.png, apple-touch-icon.png in public/

  • 🛒 Marketplace: new collection type for discovering plugins, themes, and web extensions

  • 🤖 llms.txt: automatic generation of llms.txt for AI-friendly site indexing

  • 🖥️ CLI: new roq add command for adding plugins, themes, and web extensions

  • 🔧 Internal refactoring: the frontmatter pipeline is now split into clear numbered steps (Step0-Step6) for better maintainability

  • 🔧 Migrated to ProjectScanner API and StringPaths library for file scanning

  • ⚠️ page.date now returns null for normal pages without a date. Collection documents (posts) still default to the current date.

→ Guide for migrating to 2.1

Roq 2.0

  • 🕵️ Added lightning filesystem watcher for live reload

  • 📂 Allow web directory at the root of the Roq site

  • 🧩 Simplified default app structure: supports web/app.js and web/app.scss (or web/app/app.js like before …​)

  • ⚡️ TailwindCSS support without any config

  • 💫 Directory support for data and allow iterating on nested data files using the directory name

→ Guide for migrating to 2.0

Roq 1.8

Sorry for the breaking releases back to back but this includes a refactor to allow safely including files from the whole site directory when using AsciidocJ (requested by a user).

This mostly change internal api, but can eventually break really specific usage.

→ Guide for migrating to 1.8

Roq 1.7

The Asciidoc support was already available, but with this new release, we made it a Roq top level citizen:

  • Support for Asciidoc headers to control the Roq data

  • Includes

  • Roq page and site attributes (urls, …​)

  • xref are working out of the box for structured content such as docs

  • Fine grained Asciidoc attributes (config, layout, page)

  • Harmonization between Ruby and Java implementation

  • Dynamic TOC support

👉 The Roq Asciidoc plugin doc

A few weeks ago, we added support for search as a plugin to Roq. I wasn’t fully happy with the style and the fact that it was targetting the full page instead of the nearest fragment for the actual keyword.

I spend a bit of time on this and came up with a new way of indexing the content which slice the content based on fragments. Currently, it supports both Asciidoc and Markdown output.

Give it a try, it is enabled on this site. If you want this for your site:

👉 The Roq Search plugin doc

→ Guide for migrating to 1.7

Migration guide

  1. Make sure you update using Quarkus CLI

  2. Make sure you implemented generation tests

to 2.1

Applies to Before After Action

All users

layout: :theme/foo

layout: foo or theme-layout: foo

⚠ Update layout references in front matter

All users

Layouts in templates/layouts/{theme-name}/

templates/layouts/

⚠ Move custom layouts

All users

page.date returns current date for all pages

Returns null for non-collection pages

⚠ Wrap with {#if page.date}…​{/if}

Theme users

SCSS (app.scss)

CSS with TailwindCSS

⚠ Migrate custom styles

Theme users

{#author-card …​} (kebab-case)

{#roq/authorCard …​} (namespaced camelCase)

⚠ Update tag references

Plugin authors

RoqFrontMatterScanProcessor

Step-based build items

⚠ Update plugin code

Plugin authors

deployment.scan.\*

deployment.items.scan.* (same for data, publish)

⚠ Update imports

Plugin authors

PAGINATE_KEY in scan package

RoqFrontMatterKeys (runtime)

⚠ Update imports

Theme users

Custom SCSS/CSS overrides

Theme CSS completely rewritten

⚠ Review your overrides — some may be unnecessary now, others may need updating

Theme users

Custom color variables

Three customizable color palettes: accent, pop, neutral

ℹ See Color Palettes

Theme users

Custom CSS classes for prose

not-prose class to exclude from prose styling

ℹ Good to know

Theme users

No dark mode

Built-in with dark: variants

ℹ Good to know

to 2.0

Applies to Before After Action

All users

Nested data mapped with _ (e.g. dir_bar)

Mapped with / (e.g. dir/bar)

⚠ Update data references

to 1.8

Applies to Before After Action

All users

page.info()

page.source() and page.source().template()

⚠ Update page info calls

Plugin authors

Previous BuildItems API

Restructured BuildItems

⚠ Update plugin code

to 1.7

Applies to Before After Action

AsciiDoc users

Qute parsing enabled by default

Disabled by default

⚠ Use :qute: per page or quarkus.asciidoc.qute=false

AsciiDoc users

quarkus.asciidoctorj

quarkus.asciidoc

⚠ Rename config

AsciiDoc users

quarkus.asciidoctorj.templates-dir

Removed (TOC handled by script)

⚠ Remove config

Search users

Previous search result DOM

Updated DOM structure

⚠ Verify custom search styles

All users

site.ignored-files replaces defaults

Now extends site.default-ignored-files

⚠ Check ignore config