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>2.2.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` Patterns of files that Roq ignores, in addition to the `site.default-ignored-files` list. An ignored file is not published: it is neither a page, nor an attached file, nor a site static file. Roq matches each pattern against the whole path of each file relative to the content, public or static directory (`content/`, `public/` and `static/` by default), and applies each pattern to all of these directories; the layouts, and the other templates of a site in the project directory, are filtered the same way, relative to `templates/`. So `wip/*` ignores the files of `wip/` but not those of `notes/wip/`, and `wip` ignores nothing. Patterns are Java `PathMatcher` globs, where `` stops at a `/`, or regular expressions with the `regex:` prefix, which lose their backslashes in the configuration. The value is a comma-separated list, so write `.tmp,.bak` rather than `**.{tmp,bak}`. A `!` at the start of a pattern is an ordinary character, so it does not publish an ignored file; to publish files that the default list ignores, set `site.default-ignored-files` instead. Environment variable: `SITE_IGNORED_FILES`	list of string
`site.default-ignored-files` Patterns of files that Roq ignores by default: all files and directories whose name starts with an underscore (`_`). Setting this property replaces the default list, for example to publish `public/_redirects` while the other files whose name starts with an underscore stay ignored, as the Ignored files section of the basics guide shows. The value cannot be empty: to ignore no file by default, give a pattern that matches nothing, such as `nomatch`. To add patterns to the default list, use `site.ignored-files`. These patterns are additional to the scanner’s own OS-level defaults (e.g. `.DS_Store`, `Thumbs.db`, `*~`, `.class`). Environment variable: `SITE_DEFAULT_IGNORED_FILES`	list of string	`/_`, `_**`
`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. Resolves local layout first, then theme layout as fallback. Environment variable: `SITE_PAGE_LAYOUT`	string	`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` This property is deprecated: Use `site.public-dir` instead (use 'public/static/…' to reproduce the same behaviour). 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` The theme name. Used to resolve theme layouts when using `theme-layout:` in front matter. With a theme, `layout: foo` resolves local first, then theme layout as fallback. Environment variable: `SITE_THEME`	string	`roq-base`
`site.draft` Show draft pages Environment variable: `SITE_DRAFT`	boolean	`false`
`site.draft-directory` Directory name used to mark collection documents as draft when frontmatter does not define attribute `draft`. Frontmatter `draft` takes precedence over this directory-based fallback. Environment variable: `SITE_DRAFT_DIRECTORY`	string	`drafts`
`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.default-locale` The default language to use when no language is specified in the frontmatter. This language will be used as a fallback for articles that don’t have a 'locale' property. Environment variable: `SITE_DEFAULT_LOCALE`	string	`en`
`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. Resolves local layout first, then theme layout as fallback. Environment variable: `SITE_COLLECTIONS__COLLECTIONS_MAP__LAYOUT`	string
`site.collections."collections-map".link` Default link template for documents in this collection. Can be overridden per-page using the frontmatter `link` key. Supports placeholders: `:collection`, `:slug`, `:name`, `:ext`, etc. Environment variable: `SITE_COLLECTIONS__COLLECTIONS_MAP__LINK`	string	`/:collection/:slug/`
`site.collections."collections-map".from-data.id-key` The data attribute to use as the page identifier. The value is slugified. Environment variable: `SITE_COLLECTIONS__COLLECTIONS_MAP__FROM_DATA_ID_KEY`	string	required
`site.collections."collections-map".from-data.name` The name of the data source (file or directory in data/). Defaults to the collection id. Environment variable: `SITE_COLLECTIONS__COLLECTIONS_MAP__FROM_DATA_NAME`	string
`site.generated-templates-output-dir` The directory where the generated templates should be created inside the output directory. Environment variable: `SITE_GENERATED_TEMPLATES_OUTPUT_DIR`	string	`roq-templates`
`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
`site.page-link` Default link template for non-collection pages. Can be overridden per-page using the frontmatter `link` key. Supports placeholders: `:path`, `:slug`, `:name`, `:ext`, etc. Environment variable: `SITE_PAGE_LINK`	string	`/:path:ext`

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

Patterns of files that Roq ignores, in addition to the site.default-ignored-files list.

An ignored file is not published: it is neither a page, nor an attached file, nor a site static file. Roq matches each pattern against the whole path of each file relative to the content, public or static directory (content/, public/ and static/ by default), and applies each pattern to all of these directories; the layouts, and the other templates of a site in the project directory, are filtered the same way, relative to templates/. So wip/** ignores the files of wip/ but not those of notes/wip/, and wip ignores nothing. Patterns are Java PathMatcher globs, where * stops at a /, or regular expressions with the regex: prefix, which lose their backslashes in the configuration. The value is a comma-separated list, so write **.tmp,**.bak rather than **.{tmp,bak}. A ! at the start of a pattern is an ordinary character, so it does not publish an ignored file; to publish files that the default list ignores, set site.default-ignored-files instead.

Environment variable: SITE_IGNORED_FILES

list of string

site.default-ignored-files

Patterns of files that Roq ignores by default: all files and directories whose name starts with an underscore (_).

Setting this property replaces the default list, for example to publish public/_redirects while the other files whose name starts with an underscore stay ignored, as the Ignored files section of the basics guide shows. The value cannot be empty: to ignore no file by default, give a pattern that matches nothing, such as nomatch. To add patterns to the default list, use site.ignored-files.

These patterns are additional to the scanner’s own OS-level defaults (e.g. .DS_Store, Thumbs.db, *~, .class).

Environment variable: SITE_DEFAULT_IGNORED_FILES

list of string

**/_**, _**

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.

Resolves local layout first, then theme layout as fallback.

Environment variable: SITE_PAGE_LAYOUT

string

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

This property is deprecated: Use site.public-dir instead (use 'public/static/…' to reproduce the same behaviour).

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

The theme name. Used to resolve theme layouts when using theme-layout: in front matter. With a theme, layout: foo resolves local first, then theme layout as fallback.

Environment variable: SITE_THEME

string

roq-base

site.draft

Show draft pages

Environment variable: SITE_DRAFT

boolean

false

site.draft-directory

Directory name used to mark collection documents as draft when frontmatter does not define attribute draft. Frontmatter draft takes precedence over this directory-based fallback.

Environment variable: SITE_DRAFT_DIRECTORY

string

drafts

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.default-locale

The default language to use when no language is specified in the frontmatter. This language will be used as a fallback for articles that don’t have a 'locale' property.

Environment variable: SITE_DEFAULT_LOCALE

string

en

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.

Resolves local layout first, then theme layout as fallback.

Environment variable: SITE_COLLECTIONS__COLLECTIONS_MAP__LAYOUT

string

site.collections."collections-map".link

Default link template for documents in this collection. Can be overridden per-page using the frontmatter link key. Supports placeholders: :collection, :slug, :name, :ext, etc.

Environment variable: SITE_COLLECTIONS__COLLECTIONS_MAP__LINK

string

/:collection/:slug/

site.collections."collections-map".from-data.id-key

The data attribute to use as the page identifier. The value is slugified.

Environment variable: SITE_COLLECTIONS__COLLECTIONS_MAP__FROM_DATA_ID_KEY

string

required

site.collections."collections-map".from-data.name

The name of the data source (file or directory in data/). Defaults to the collection id.

Environment variable: SITE_COLLECTIONS__COLLECTIONS_MAP__FROM_DATA_NAME

string

site.generated-templates-output-dir

The directory where the generated templates should be created inside the output directory.

Environment variable: SITE_GENERATED_TEMPLATES_OUTPUT_DIR

string

roq-templates

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

site.page-link

Default link template for non-collection pages. Can be overridden per-page using the frontmatter link key. Supports placeholders: :path, :slug, :name, :ext, etc.

Environment variable: SITE_PAGE_LINK

string

/:path:ext