Configuration

Site config lives in site.toml at the source root. Juicer overlays your file on top of one of three baselines (simple, standard, norme) selected by the -c <name> CLI flag.

Baselines

Keys

Identity

Theme

Directory layout

The walk already skips the active themeDir subfolders, the themeDir parent (so inactive themes vendored alongside don’t render), the configured publicDir, and the build’s output dst. Use excludeDirs for anything else under the source root that isn’t part of the site — vendored tooling, scratch folders, generated assets you produce out-of-band, drafts kept outside content/:

excludeDirs = ["node_modules", "scratch", "assets/raw"]

Layout names

Behavior

headingShift per page

A page may override the site value in its own frontmatter:

---
title: bristle.text
headingShift: 0
---

The site-wide value assumes a layout supplies the <h1>, so an author’s # is a subsection of the page title. A page whose body is generated does not fit that assumption — its ## groups are already meant to be <h2>, and they have to land at the same levels as when the same file is read somewhere with no layout at all.

A cascade cannot set it, deliberately: it is a property of how one file was authored, not of where it sits in the tree. A value that is not a number falls back to the site setting rather than failing the build.

slugStyle, and when to change it

Leave it alone for an ordinary site. Changing it rewrites the anchor of every heading containing punctuation, so every in-page link anyone has shared stops resolving — which is why "juicer" stays the default even though "github" is the more widely compatible algorithm.

Reach for "github" when the same Markdown is read in two places: a site built by juicer and a repository browsed on GitHub. Generated API reference is the case it was added for — those headings are snake_case symbol names, and a symbol index linking to its own headings has to be right in both renderings, or one of them is a page of dead links.

Repeated headings get a numeric suffix under both styles — the first ## buf keeps #buf and a later ## Buf becomes #buf-1, which is what GitHub does. That part is not configurable: two elements sharing an id is invalid HTML and leaves the second unreachable, so it was a defect rather than a behaviour worth preserving.

slugStyle per page

The paragraph above is the reason this override exists. A site of any age cannot turn "github" on wholesale — the anchors it rewrites are links people have already shared — and yet one generated section on that site needs it. So a page may say so for itself:

---
title: sysl.text
slugStyle: github
---

Anchors are a per-page property: nothing outside a page’s own headings is named by them, and a page’s table of contents is built from those same headings. So the override is coherent in a way that a per-page baseURL would not be, and it is what lets generated reference sit beside hand-written prose without moving the prose.

It reads the page’s own frontmatter, exactly as headingShift does — a cascade cannot set it, and a value that is not a string falls back to the site setting rather than failing the build. An unrecognised style falls back to "juicer", so a typo costs the anchors their style and never costs the page its ids.

Navigation — nav

Top-level array that drives .site.toc (the sidebar / topbar nav). When nav is absent, juicer auto-builds the nav by walking the content tree. When nav is set, juicer walks the array entries:

• A string ending in a markdown extension (.md, .markdown, .mkd, .mkdn, .mdown) is a reference to a content file (path relative to contentDir). The page record at that path is pulled into the nav at the array’s position.
• Any other string is a section label — a non-clickable group heading.
• A single-key table maps an explicit label to a content path — useful when the file’s frontmatter title isn’t the right label for the nav.

nav = [
  "Getting Started",                       # label
  "getting-started/_index.md",             # link, title from frontmatter
  "getting-started/installation.md",
  { "Get help" = "getting-started/troubleshooting.md" },   # link, explicit label
  "Reference",                             # label
  "reference/cli.md",
  "reference/config.md",
]

The same array is also walked by themes’ “previous / next” partials when nav is set, so the order you write here is the order readers flip through.

i18n — languages, defaultLanguage

Two opt-in keys that turn on multi-language mode. The engine doesn’t duplicate content for you (one markdown file per language is still the convention) — it surfaces the active language to templates so themes can render language-aware chrome and pull strings from a translation table.

Translation strings live in <src>/i18n/<lang>.toml, one file per declared language, as flat key = "value" tables:

# i18n/en.toml
home          = "Home"
browse_docs   = "Browse the docs"
read_more     = "Read more"

# i18n/fr.toml
home          = "Accueil"
browse_docs   = "Parcourir la documentation"
read_more     = "Lire la suite"

Templates look strings up with the i18n helper, passing the page’s language:

<a href="/">{{ i18n .page.lang 'home' }}</a>
<a href="/docs/">{{ i18n .page.lang 'browse_docs' }}</a>

Lookups fall back to defaultLanguage when a key is missing in the requested language; if the key is missing in both, the literal key is returned (so a missing translation is visible during authoring without crashing the build).

Blog features

These keys turn on the blogging features documented under Concepts → Blogging features. All four are opt-in; a docs site that doesn’t set them renders unchanged.

Calendar / events features

Juicer surfaces a curated events list (.site.events) and a 12-month calendar grid (.site.calendar) for any site that has a section of event pages. See Template data → .site.events and .site.calendar.

Recurring events are theme-and-template territory — the engine recognizes recurring: weekly plus an optional recurringDay: frontmatter on event pages and expands the event onto every matching weekday in .site.calendar. Without recurringDay:, the recurrence defaults to the start date’s day of the week.

[permalinks] — URL templates per section

A TOML sub-table that overrides a section’s URL pattern. Each key is a section name (the first path segment after htmlDir is stripped); each value is a template string with substitution tokens. Tokens are resolved against the page’s frontmatter and parsed date.

[permalinks]
posts = ":year/:month/:slug/"
notes = ":slug/"
articles = ":year/:section/:title/"

Recognized tokens:

Sections without a [permalinks] entry keep juicer’s default physical-path-derived URL (the file tree determines the URL one-to-one). Section index pages (_index.md) are never routed through permalink templates — they always live at the section root.

See Concepts → Blogging features → Permalinks for the narrative version.

[comments] — comments-provider config slot

juicer never ships a comments backend. Sites that want comments declare the provider and provider-specific keys under [comments] in site.toml; theme partials read the config back as .site.comments.* and emit the right embed HTML.

[comments]
provider = "giscus"
repo     = "edadma/juicer"
repoId   = "R_kgDOXXXXXX"
category = "Announcements"
categoryId = "DIC_kwDOXXXXXX"
mapping  = "pathname"
reactions = true
theme    = "preferred_color_scheme"

The only convention the engine cares about is the table name itself — everything inside is opaque to juicer. Conventional keys for the common providers:

Themes typically gate the embed on {{ if .site.comments }} and on a per-page comments: false frontmatter override (so individual posts can opt out of comments without unsetting the site-wide config). See Template data → .site.comments for the template-side contract.

[images] — image variant generation

Opt-in build-time generation of resized + reformatted image variants (webp, avif, etc.) for responsive <picture> / <img srcset> markup. The feature is disabled by default — sites that don’t set this table build byte-identically to pre-[images] juicer.

[images]
enabled  = true
widths   = [320, 640, 960, 1280]
formats  = ["webp", "original"]   # most-modern first; "original" passes through
quality  = 80
cacheDir = ".image-cache"          # under dst; variants land here

Encoder. Juicer shells out to ImageMagick (magick) — install with brew install imagemagick / apt install imagemagick / dnf install ImageMagick. When magick is not on PATH the build still succeeds, but imageVariants returns a passthrough-only set (a single advisory line prints to stderr). The Scala Native and Scala.js targets ship a stub backend; full variant generation is JVM-only today.

Template side: see Template syntax → imageVariants and srcset for the helpers themes call.

[assets] — Sass / esbuild pipeline

Opt-in build-time compilation of theme assets via two widely-available CLIs: sass for SCSS → CSS and esbuild for JS bundling and minification. Plus an optional fingerprinting flag that appends a content-hash to output filenames so deploys can ship cache-busting URLs without giving up long-lived Cache-Control headers. Disabled by default — sites that don’t set this table build byte-identically to pre-[assets] juicer.

[assets]
enabled     = true
fingerprint = false

[[assets.sass]]
input  = "src/site.scss"
output = "/css/site.css"
minify = true

[[assets.esbuild]]
input  = "src/main.js"
output = "/js/main.js"
minify = true

[[assets.copy]]
input  = "src/robots.txt"
output = "/robots.txt"

Entry tables (any number of each; use either inline-table shorthand or [[assets.kind]] array form):

input is resolved under the source root; output is a site-rooted URL path (leading slash optional). logical defaults to the basename of output — /css/site.css becomes the manifest key site.css, which templates look up as {{ asset 'site.css' }}.

Tool installation. Juicer shells out to sass (the dart-sass / npm package; the Ruby sass gem also works for the small flag subset juicer uses) and esbuild. Install with brew install dart-sass esbuild / npm install -g sass esbuild / your platform’s equivalent. When a tool isn’t on PATH the build still succeeds: that entry degrades to a verbatim copy of its source, the URL still resolves so templates don’t break, and a single advisory line goes to stderr. Native and JS targets ship stub backends; full pipeline execution is JVM-only today.

Template side: see Template data → asset builtin.

[[authors]] — author registry

An array of tables describing the people who write posts on the site. Each entry needs at least an id; everything else is optional and flows directly into .page.author / .page.authors records.

[[authors]]
id     = "ed"
name   = "Edward A Maxedon"
email  = "ed@example.com"
bio    = "Writes a lot of code."
avatar = "/img/ed.jpg"

[[authors.links]]
label = "GitHub"
url   = "https://github.com/edadma"

Pages reference an author via author: <id> or authors: [<id>, ...] in their frontmatter. See Concepts → Blogging features → Author registry for the full narrative.

Custom keys

Any key you set in site.toml is available as .site.<key> in templates. Use this for site-wide settings the theme exposes — e.g., editURL, discussionURL, social.twitter. Themes typically document the keys they recognize in their README.