Quarkus Roq FrontMatter

Quarkus Roq FrontMatter is a Quarkus extension that create a website from your Markdown/Asciidoc/Html pages using FrontMatter headers (url, layout, seo, data).

The documentation is available in the Roq website.

Roq FrontMatter 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.

Standalone installation

It is included as part of the Roq Static Site Generator extension io.quarkiverse.roq:quarkus-roq. You can also use it standalone.

If you want to use this extension standalone, you need to add the io.quarkiverse.roq:quarkus-roq-frontmatter 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-frontmatter</artifactId>
    <version>1.8.0</version>
</dependency>

Extension Configuration Reference

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

Configuration property	Type	Default
`site.url` the base hostname & protocol for your site, e.g. http://example.com Environment variable: `SITE_URL`	string
`site.route-order` The order of the route which handles the templates. <p> By default, the route is executed before the default routes (static resources, etc.). Environment variable: `SITE_ROUTE_ORDER`	int	`1100`
`site.ignored-files` Add new ignored files to the default list. The ignored files (relative to the site directory). Only the `content/`, `public/`, and `static/` directories are scanned. Environment variable: `SITE_IGNORED_FILES`	list of string
`site.default-ignored-files` The default ignored files (relative to the site directory) include: `.DS_Store` `Thumbs.db` All files or directories starting with an underscore (`_`) Only the `content/`, `public/`, and `static/` directories are scanned. Environment variable: `SITE_DEFAULT_IGNORED_FILES`	list of string	`.DS_Store,Thumbs.db,/,**`
`site.escaped-pages` Pages whose content should be escaped— i.e., included in Qute rendering but not parsed for Qute expressions. This is based on the page’s relative path from the content directory. This applies only to pages (not layouts or partials). Supports glob expressions. Environment variable: `SITE_ESCAPED_PAGES`	list of string
`site.page-layout` The layout to use for normal html pages if not specified in FM. When empty, the page will not use a layout when it doesn’t specify it in FM. ":theme/" is removed if no theme is defined. Environment variable: `SITE_PAGE_LAYOUT`	string	`:theme/page`
`site.content-dir` The directory which contains content (pages and collections) in the Roq site directory. Environment variable: `SITE_CONTENT_DIR`	string	`content`
`site.static-dir` The directory (dir name) which contains static files to be served (with 'static/' prefix). Environment variable: `SITE_STATIC_DIR`	string	`static`
`site.public-dir` The directory which contains public static files to be served without processing (dir name) Environment variable: `SITE_PUBLIC_DIR`	string	`public`
`site.images-path` The path containing static images (in the public directory) Environment variable: `SITE_IMAGES_PATH`	string	`images/`
`site.generator` When enabled it will select all FrontMatter pages in Roq Generator Environment variable: `SITE_GENERATOR`	boolean	`true`
`site.future` Show future documents Environment variable: `SITE_FUTURE`	boolean	`false`
`site.theme` This will be used to replace `:theme` when resolving layouts (e.g. `layout: :theme/main.html`) Environment variable: `SITE_THEME`	string
`site.draft` Show draft pages Environment variable: `SITE_DRAFT`	boolean	`false`
`site.date-format` Format for dates Environment variable: `SITE_DATE_FORMAT`	string	`yyyy-MM-dd[ HH:mm][:ss][ Z]`
`site.time-zone` The default timezone Environment variable: `SITE_TIME_ZONE`	string	`document timezone if provided or system timezone`
`site.slugify-files` Indicates whether file names in the public directory and files attached to pages should be slugified (converted to a URL-friendly format). When enabled, file names will automatically be transformed into a URL-safe format. Additionally, `page.file` and `site.file` references can use the original file names, as they will also be slugified during the process. Environment variable: `SITE_SLUGIFY_FILES`	boolean	`true`
`site.collections."collections-map"` If this collection is enabled Environment variable: `SITE_COLLECTIONS__COLLECTIONS_MAP_`	boolean	`true`
`site.collections."collections-map".future` Show future documents (overrides global future for this collection) Environment variable: `SITE_COLLECTIONS__COLLECTIONS_MAP__FUTURE`	boolean	`false`
`site.collections."collections-map".hidden` If true, the collection won’t be available on path but consumable as data. Environment variable: `SITE_COLLECTIONS__COLLECTIONS_MAP__HIDDEN`	boolean	`false`
`site.collections."collections-map".layout` The layout to use if not specified in FM data. When empty, the document will not use a layout when it doesn’t specify it in FM. ":theme/" is removed if no theme defined. Environment variable: `SITE_COLLECTIONS__COLLECTIONS_MAP__LAYOUT`	string
`site.path-prefix` READ CAREFULLY: The root path of your site (e.g. `/blog`) should be set using `quarkus.http.root-path`. This path prefix should be relative to the Quarkus HTTP root path and is meant to be used only when the Roq site is served alongside a Quarkus application on a separate path. Environment variable: `SITE_PATH_PREFIX`	string

Configuration property

Type

Default

site.url

the base hostname & protocol for your site, e.g. http://example.com

Environment variable: SITE_URL

string

site.route-order

The order of the route which handles the templates. <p> By default, the route is executed before the default routes (static resources, etc.).

Environment variable: SITE_ROUTE_ORDER

int

1100

site.ignored-files

Add new ignored files to the default list. The ignored files (relative to the site directory).

Only the content/, public/, and static/ directories are scanned.

Environment variable: SITE_IGNORED_FILES

list of string

site.default-ignored-files

The default ignored files (relative to the site directory) include:

.DS_Store
Thumbs.db
All files or directories starting with an underscore (_)

Only the content/, public/, and static/ directories are scanned.

Environment variable: SITE_DEFAULT_IGNORED_FILES

list of string

.DS_Store,Thumbs.db,/,**

site.escaped-pages

Pages whose content should be escaped— i.e., included in Qute rendering but not parsed for Qute expressions.

This is based on the page’s relative path from the content directory.

This applies only to pages (not layouts or partials).

Supports glob expressions.

Environment variable: SITE_ESCAPED_PAGES

list of string

site.page-layout

The layout to use for normal html pages if not specified in FM. When empty, the page will not use a layout when it doesn’t specify it in FM. ":theme/" is removed if no theme is defined.

Environment variable: SITE_PAGE_LAYOUT

string

:theme/page

site.content-dir

The directory which contains content (pages and collections) in the Roq site directory.

Environment variable: SITE_CONTENT_DIR

string

content

site.static-dir

The directory (dir name) which contains static files to be served (with 'static/' prefix).

Environment variable: SITE_STATIC_DIR

string

static

site.public-dir

The directory which contains public static files to be served without processing (dir name)

Environment variable: SITE_PUBLIC_DIR

string

public

site.images-path

The path containing static images (in the public directory)

Environment variable: SITE_IMAGES_PATH

string

images/

site.generator

When enabled it will select all FrontMatter pages in Roq Generator

Environment variable: SITE_GENERATOR

boolean

true

site.future

Show future documents

Environment variable: SITE_FUTURE

boolean

false

site.theme

This will be used to replace :theme when resolving layouts (e.g. layout: :theme/main.html)

Environment variable: SITE_THEME

string

site.draft

Show draft pages

Environment variable: SITE_DRAFT

boolean

false

site.date-format

Format for dates

Environment variable: SITE_DATE_FORMAT

string

yyyy-MM-dd[ HH:mm][:ss][ Z]

site.time-zone

The default timezone

Environment variable: SITE_TIME_ZONE

string

document timezone if provided or system timezone

site.slugify-files

Indicates whether file names in the public directory and files attached to pages should be slugified (converted to a URL-friendly format). When enabled, file names will automatically be transformed into a URL-safe format. Additionally, page.file and site.file references can use the original file names, as they will also be slugified during the process.

Environment variable: SITE_SLUGIFY_FILES

boolean

true

site.collections."collections-map"

If this collection is enabled

Environment variable: SITE_COLLECTIONS__COLLECTIONS_MAP_

boolean

true

site.collections."collections-map".future

Show future documents (overrides global future for this collection)

Environment variable: SITE_COLLECTIONS__COLLECTIONS_MAP__FUTURE

boolean

false

site.collections."collections-map".hidden

If true, the collection won’t be available on path but consumable as data.

Environment variable: SITE_COLLECTIONS__COLLECTIONS_MAP__HIDDEN

boolean

false

site.collections."collections-map".layout

The layout to use if not specified in FM data. When empty, the document will not use a layout when it doesn’t specify it in FM. ":theme/" is removed if no theme defined.

Environment variable: SITE_COLLECTIONS__COLLECTIONS_MAP__LAYOUT

string

site.path-prefix

READ CAREFULLY:
The root path of your site (e.g. /blog) should be set using quarkus.http.root-path.
This path prefix should be relative to the Quarkus HTTP root path and is meant to be used only when the Roq site is served alongside a Quarkus application on a separate path.

Environment variable: SITE_PATH_PREFIX

string