Configuration
brrrty.config.rhai is a Rhai script at the project root. It calls methods on a config object shaped like 11ty's eleventyConfig, in snake_case, and ends with the object 11ty's config function returns.
config.add_passthrough_copy("src/images");
config.add_passthrough_copy(#{ "src/favicon.svg": "favicon.svg" });
config.ignores.add("src/drafts/**");
config.add_global_data("build", #{ year: year(now()) });
config.add_filter("shout", |s| s.to_upper() + "!");
config.add_collection("posts", |api|
api.get_filtered_by_tag("post").reverse());
config.add_plugin("rss", #{
type: "atom",
output_path: "/feed.xml",
collection: #{ name: "posts", limit: 10 },
metadata: #{
language: "en",
title: "My blog",
base: "https://example.com/",
author: #{ name: "Me", email: "" },
},
});
#{ dir: #{ input: "src", output: "_site" } }
Nothing runs until the whole script has. An error in the script stops the build before any page is written, with the line and column.
The config object
| Call | What it does |
|---|---|
config.add_passthrough_copy(path) |
addPassthroughCopy. Copies a file or folder as is. The path is from the project root. |
config.add_passthrough_copy(#{ from: to }) |
addPassthroughCopy({...}). Copies each source to the given output path. |
config.ignores.add(glob) |
ignores.add. Leaves matching files out of the build. |
config.ignores.delete(glob) |
ignores.delete. Removes a glob added earlier. |
config.add_global_data(name, value) |
addGlobalData. Adds global data. Two objects under one name merge deeply, as in 11ty. A function is called once, when the config loads. |
config.add_filter(name, fn) |
addFilter. Adds a filter to Liquid and Nunjucks. |
config.add_nondeterministic_filter(name) |
Stands in for a filter that uses Math.random in your JavaScript config. Its output can never match 11ty's, so pages that use it are refused. |
config.add_collection(name, fn) |
addCollection. Adds a collection. |
config.add_plugin(name, options) |
addPlugin, for the plugins Brrrty has its own version of: rss and syntaxhighlight. options is optional. |
Passthrough copy takes a file or folder, not a glob; a glob is refused with passthrough-unsupported.
What the script returns
The script's last expression is a map with these keys, all optional. A script can also end with a statement, which is the same as returning nothing.
| Key | Values |
|---|---|
dir |
input and output folders. includes, data and layouts are accepted only with their defaults, _includes, _data and _includes. |
markdownTemplateEngine |
"liquid" (the default), "njk" or false |
htmlTemplateEngine |
"liquid" (the default), "njk" or false |
dataTemplateEngine is ignored with a warning, since 11ty 3 doesn't read it. Any other key is refused, so a setting Brrrty doesn't support never goes unnoticed.
Filters
A filter gets the value, then the arguments in the order the template wrote them. A missing argument is (), so n ?? 40 gives a default. A keyword argument arrives in place as a two-item array, [name, value].
config.add_filter("money", |n, symbol| (symbol ?? "$") + js_string(n));
{{ price | money: "€" }}
A filter that throws, returns something that isn't data, or runs too long refuses the page that called it, with the template's position and the script's. The rest of the site builds. (11ty stops the whole build there.)
Nothing carries over from one filter call to the next. Brrrty renders pages in parallel, so a counter or cache in a JavaScript filter could never give 11ty's output. To make that impossible rather than check for it, a function can't see variables outside itself, and every argument is a copy. To use a value set up at the top of the script, curry it into a named function:
let rates = #{ a: 2, b: 3 };
fn rate(rates, value, key) { rates[key] * value }
config.add_filter("rate", Fn("rate").curry(rates)); // {{ 5 | rate: "b" }}
Collections
config.add_collection(name, |api| ...) runs where 11ty runs it, and api has 11ty's collection API in snake_case:
| Rhai | 11ty |
|---|---|
api.get_all() |
getAll(), in the order pages were added |
api.get_all_sorted() |
getAllSorted(), by date, then input path |
api.get_filtered_by_tag("t") |
getFilteredByTag("t") |
api.get_filtered_by_tags("a", "b") |
getFilteredByTags("a", "b"), up to four tags |
api.get_filtered_by_glob("./src/posts/**/*.md") |
getFilteredByGlob(...), one glob or an array of them |
Globs are read from the project root, as 11ty reads them. Brrrty supports *, ?, ** as a whole folder name, and literal text; braces, [ab], ! and extglobs are an error rather than a guess.
Items are the pages themselves, and read-only: setting a property on one is an error, and so is changing an array read through one, like post.data.tags (to_array() copies it). Return any mix of arrays, maps and object()s holding items, and templates still read their url, data and templateContent. Reading an item's content or templateContent inside the collection refuses the pages that read the collection, because 11ty hasn't rendered it yet at that point.
Arrays have JavaScript's sort(), sort(|a, b| ...), reverse() and slice(start, end), and map, filter and reduce take a function:
config.add_collection("byOrder", |api|
api.get_filtered_by_tag("docs").sort(|a, b| a.data.order - b.data.order));
This site's own sidebar is built with that collection.
Data files
Global data in _data/name.rhai, and template and folder data in page.11tydata.rhai and folder/folder.11tydata.rhai, are Rhai scripts. The last expression is the data. Folders nest keys as JSON files do: _data/a/b.rhai is a.b.
// _data/site.rhai
#{ name: "Mine", url: "https://example.com", year: year(now()) }
If the script defines fn data() or fn data(global), Brrrty calls it the way 11ty calls a function a data file exports, with the config's global data and 11ty's eleventy data as the argument, and the rest of the script doesn't run.
Each file runs once per build, on its own, and can't see config or read files. A .rhai file and a .json file for the same key merge, the .rhai one winning, and a .js file next to a .rhai port is ignored. An error refuses only the pages that read that key.
Plugins
config.add_plugin(name, #{ ... }) adds Brrrty's version of an 11ty plugin, with 11ty's options in snake_case. Any other name is an error. Port every addPlugin call: Brrrty only reads the Rhai config, so it can't tell when one is missing, and the pages that plugin would have changed come out as if it weren't there.
rssis@11ty/eleventy-plugin-rss's feed plugin, one feed per call. Options:type("atom","rss"or"json"),output_path,input_path,collection(name,limit,sort),metadata,template_data,stylesheetandscript. Its filters work in Liquid and Nunjucks as they do in 11ty.syntaxhighlightis@11ty/eleventy-plugin-syntaxhighlightwith Prism 1.30.0, for Markdown fences and the Liquid{% highlight %}tag. Options:line_separator,error_on_invalid_language,always_wrap_line_highlights,trim,languages,template_formats,pre_attributesandcode_attributes. It has 28 of Prism's 297 languages, includingbash,css,go,javascript,json,liquid,markdown,markup(HTML),php,python,ruby,rust,sql,toml,typescriptandyaml. A page in a Prism language Brrrty doesn't have yet is refused.
The full lists, and the cases each plugin refuses, are in PORTING.md.
Rhai is not JavaScript
Values cross into the script as 11ty would give them to a JavaScript filter, and come back out as data. Numbers are floats, undefined is (), null is null_value(), and dates are dates. Rhai's own operators aren't changed, so where they differ from JavaScript's, use a helper:
| JavaScript | In Rhai | Use |
|---|---|---|
7 / 2 is 3.5 |
7 / 2 is 3 |
js_div(7, 2), or 7.0 / 2. Numbers from data are floats already. |
a + b |
strings join, numbers add, a mix is an error | js_concat(a, b) |
String(v), `${v}` |
to_string() prints arrays and maps Rhai's way |
js_string(v) |
if (x), x || y |
only a bool is allowed |
truthy(x) |
Math.round(x) |
round() rounds halves away from zero |
js_round(x) |
JSON.stringify(v) |
json_stringify(v) |
|
{} built up key by key |
#{ } maps sort their keys |
object(), which keeps insertion order |
arr.sort(), arr.sort(fn) |
replaced with JavaScript's | arr.sort(), arr.sort(|a, b| ...), or js_sort(arr) and js_sort_by(arr, fn) for a sorted copy |
new Date(ms) |
date(ms) |
|
Date.now() |
get_time(now()) |
|
new Date().getFullYear() |
year(now()) |
|
d.toUTCString() |
date_to_utc_string(d) |
|
d.toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric" }) |
to_locale_date_string(d) |
|
new URL(u).hostname |
url_hostname(u), or () when u isn't a full URL |
|
s.replace(/re/g, r), s.split(/re/), /re/.test(s) |
regex_replace(s, pattern, r, "g"), regex_split(s, pattern), regex_test(s, pattern) |
|
DateTime.fromJSDate(d, { zone }).toFormat(fmt) (Luxon) |
luxon_format(d, fmt, zone) |
|
markdownIt().render(s), .renderInline(s) |
markdown(s), markdown_inline(s) |
|
execSync("git rev-parse HEAD") |
scripts can't run commands | git_head() |
Sorting runs V8's own TimSort, so even a comparator that isn't a consistent ordering gives the order Node gives. Regular expressions accept only syntax that means the same in JavaScript and in Rust: no lookaround and no backreferences, among a few others, and a pattern outside that is an error naming it.
object() has keys(), values(), entries(), len(), contains(k) and remove(k), and for k in o walks its keys in order. object(map) copies a map in. Objects that come from Brrrty, such as page data, are object()s already, so returning one as it came keeps its order.
Time
now() reads the system clock. Set SOURCE_DATE_EPOCH to a whole number of seconds since 1970, and now(), Liquid's 'now' and 'today', and the RSS feeds' dates all use that time instead, so two builds of the same source give the same files. Rhai's own timestamp() is an error that points to now().
Printing
print(x) writes to standard output, and debug(x) writes the script's file, line and x to standard error. Pages render in parallel, so lines from different pages can come out in any order. Neither changes what is built.
Limits
A script may run 50 million operations and 10 seconds, nest 64 calls deep, and hold strings up to 16 MB and arrays and maps up to 100,000 items. Past a limit it stops with a problem that points at the file, so a script can't hang the build. There is no import, no eval and no file access.
The full porting guide, with every edge case, is PORTING.md.