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

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# label
  "getting-started/_index.md",             # link, title from frontmatter# link, title from frontmatter
  "getting-started/installation.md",
  { "Get help" = "getting-started/troubleshooting.md" },   # link, explicit label# link, explicit label
  "Reference",                             # label# 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# i18n/en.toml
home          = "Home"
browse_docs   = "Browse the docs"
read_more     = "Read more"

# i18n/fr.toml# 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# most-modern first; "original" passes through
quality  = 80
cacheDir = ".image-cache"          # under dst; variants land here# 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 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.