Juicer

Troubleshooting

2026-05-27T20:59:11.669095985Z

This page is organized by symptom, not by feature. If something isn’t working, scan the headings for what you’re seeing on screen, then read the cause + fix below.

Build / install

`sbt 'juicerJVM/run --help'` errors out before printing the help banner

Cause. Either sbt itself can’t start (Java version too old; sbt couldn’t fetch its plugins) or the juicer build is broken (uncommitted edits to build.sbt, missing dependency).

Fix. Confirm java -version reports JDK 17 or newer; confirm sbt sbtVersion reports 1.12.x. Then from the repo root:

sbt clean compile

If compile succeeds but run doesn’t, the issue is dependency resolution — try sbt update to re-fetch from Maven Central.

`not a readable directory: <src>`

Cause. The -s <src> path doesn’t exist, isn’t a directory, or you don’t have read permission. Often a typo or running from the wrong cwd.

Fix. Use an absolute path or pwd && ls <src> to confirm the directory exists from where you’re running sbt. Most juicer commands run relative to the cwd, so sbt 'juicerJVM/run build -s docs/demos/juicerblog' only works from the repo root.

`unknown base configuration: <name>`

Cause. The --config flag references a baseline that doesn’t exist. Valid values are simple, standard (default), and norme.

Fix. Drop the flag — standard is what 99% of sites want. If you need a different shape, see Configuration.

`compile` errors after a `git pull`

Cause. A dependency bumped to a version that needs ~/.ivy2/cache to refresh, or a Scala source file changed in a way sbt’s incremental compile didn’t catch.

Fix. sbt clean then re-run. If a dep change is the issue, sbt update first picks up the new artifacts before compile rebuilds.

Layouts

`layout '<X>' not found for rendering '<page>'` in verbose output

Cause. Either the theme doesn’t ship a layout with that name, or the layout: frontmatter on a page references one that isn’t there. Most often it’s a typo (layout: hime instead of layout: home).

Fix. Check the theme’s layouts/_default/ directory for the file you’re naming. Themes can opt out of certain layouts (juicerblog ships home.html and archive.html; juicerdocs doesn’t). The build doesn’t fail — it falls back to file.html / folder.html — but the page renders with default chrome instead of your intended layout.

A page renders with the wrong layout

Cause. Frontmatter layout: foo is being honored when you didn’t mean to set it, or vice versa.

Fix. Inspect the page’s frontmatter — layout: is the override; remove it to fall back to the theme default. See Content files for the layout-selection rules.

A `_index.md` renders as a single post instead of a section

Cause. The file isn’t named _index.md (note the underscore) or sits in the wrong directory. Section pages MUST be named exactly _index.md and live at the top of their section directory.

Fix. Rename index.md → _index.md and confirm it’s in the section root, not nested in a subdirectory.

Themes

Theme renders with no styling at all

Cause. The theme’s CSS file isn’t being copied to the output, OR the <link rel=stylesheet> references a path that doesn’t resolve.

Fix. First check that the theme’s static/<theme>.css was copied — ls <dst>/<theme>.css. If it’s not there, your themeDir / theme keys in site.toml aren’t pointing at the right directory. Run with -v and look for a theme: … line; the path it logs is what juicer is actually using.

`theme add <git-url>` fails with “could not derive theme name”

Cause. The git URL doesn’t end in something useful (.git, repo-name). Common with custom git hosts or odd URL forms.

Fix. Pass -n <name> explicitly: juicer theme add https://example.com/weird-url -n my-theme.

A new theme doesn’t show up after `theme add`

Cause. You forgot to update site.toml — theme add only clones the directory; it doesn’t change the active theme.

Fix. Add theme = "<name>" to site.toml. Verify with juicer config -s <src> — the active theme value prints near the top.

Site assets (logo, favicon) override theme assets but they don’t appear

Cause. Site files DO win over theme files, but only when the file lives at the SAME relative path. A site <src>/static/logo.png overrides a theme themes/X/static/logo.png — but <src>/img/logo.png doesn’t, because the theme expects static/.

Fix. Mirror the theme’s directory structure exactly. See Themes for the overlay rules.

Blog features

Code blocks aren’t highlighted

Cause. No <src>/grammars/ directory exists, or the *.tmLanguage.json file inside it doesn’t match the language tag on your fence. A block opened with ```scala looks for grammars/scala.tmLanguage.json exactly — case-sensitive.

Fix. Create <src>/grammars/, drop in the grammar JSON for each language you use. See juicerblog → Configuration for the full setup. Run with -v and look for the highlighter: N grammar(s) loaded line — if you don’t see it, the directory is missing or empty.

Highlighted code has no colors

Cause. The grammar loaded successfully but your theme has no CSS for the .hl-* classes the highlighter emits.

Fix. Themes that ship a palette (juicerblog, juicerdocs) handle this automatically. For a hand-rolled theme, copy the .hl-keyword / .hl-string / .hl-comment / etc. block from docs/themes/juicerblog/static/juicerblog.css and adapt the colors.

Date archives `/2024/` etc. aren’t being emitted

Cause. Either dateArchives = true isn’t set in site.toml, OR the theme doesn’t ship _default/date-year.html and date-month.html (missing layout = silent skip), OR no posts have parseable explicit date: frontmatter.

Fix. Confirm all three:

grep dateArchives <src>/site.toml returns dateArchives = true.
The theme has the layouts: ls <theme>/layouts/_default/date-*.html.
At least one post has date: 2024-MM-DD (or similar) in its frontmatter — pages whose date came from the filesystem mtime fallback are intentionally excluded.

Tag pages don’t include a post that has the tag

Cause. Either the post has static: true frontmatter (filtered out of all post listings), or the tag’s slug doesn’t match what you typed in the URL. Tags are slugified (lowercased, ASCII-folded, runs of non-alphanumeric collapsed to -).

Fix. Visit /tags/ to see the canonical slug juicer derived. If your post has static: true, that’s why — see juicerblog → Configuration.

Author archive page is empty even though the author has posts

Cause. The frontmatter author: (or authors:) value doesn’t match any id in the [[authors]] registry. juicer falls back to a stub {id: <typo>} so templates don’t NPE, but the archive is empty.

Fix. Compare grep "^author:" content/*.md output against the id = values in your site.toml [[authors]] blocks — typos are the usual culprit.

Permalinks `[permalinks]` aren’t applying

Cause. The section name in [permalinks] doesn’t match the content directory. [permalinks] posts = ":year/:slug/" only applies to pages under content/posts/ — posts at the root of content/ are unaffected.

Fix. Either move posts under content/posts/ (recommended for blogs) or list the actual section names you have in [permalinks].

Aliases redirect to the wrong place

Cause. The aliases: frontmatter list contains the wrong shape — usually missing the leading / or trailing /.

Fix. Each alias is a URL path with both leading and trailing slash: aliases: [/old-name/, /even-older/]. Check the rendered alias HTML at <dst>/<alias>/index.html to see what redirect URL got baked in.

Serve / live reload

`juicer serve` fails with “address already in use”

Cause. Another process (often a previous juicer serve you forgot to stop) holds the port.

Fix. Pass a different port: -p 8089. juicer’s bind-with-retry loop also scans 20 ports upward from the default, so -p 8088 will find the next free one if 8088 is taken — watch for the actual port in the startup banner.

Live-reload doesn’t fire when I save a markdown file

Cause. The -L (or --live-reload) flag wasn’t passed, OR your browser stopped polling the live-reload endpoint, OR the file you saved is outside the watched directory.

Fix. Confirm the startup banner says live reload: enabled. Open browser devtools → Network and reload the page; you should see a long-lived fetch to /__juicer/wait?since=N (the live-reload script is injected before </body> in every HTML response). Saves are debounced 150ms — don’t expect saves faster than that to coalesce, but anything slower should reload within a second. If the page hasn’t been opened with the dev server (e.g., a file:// URL or a stale cached tab), the script never loaded and reloads never fire — open the page through http://localhost:<port>/.

Browser shows old content even after a save

Cause. Browser cache holds the page even though juicer rebuilt it. juicer’s serve sends Cache-Control: no-cache headers when -L is on, but a stale service worker or aggressive CDN proxy can override.

Fix. Hard reload (Cmd-Shift-R / Ctrl-Shift-R). If that doesn’t fix it, devtools → Application → Service Workers → unregister.

Templates

`unknown variable: X` at build time

Cause. A {{ X }} reference points at a variable that isn’t in scope at that point in rendering.

Fix. Most variables come from one of three sources: .page.<...> (per-page frontmatter + computed fields), .site.<...> (site config + global indexes), or local := assignments. Check Template data for the available shapes. A common gotcha inside for loops: .foo resolves against the current iterated element, not the outer scope — use $.foo to escape back to the root data.

`not a number: <X> (java.lang.Y)` in template comparisons

Cause. Squiggly’s relational ops (< > <= >= = !=) need both sides to be numeric. A boxed Java type can fail to convert if it’s an unusual shape.

Fix. Bumped to squiggly 0.2.4? That release added boxed-Number coercion. Earlier versions tripped on for x, i <- coll indices. cd <repo>; grep squiggly build.sbt should show 0.2.4 or newer.

Markdown body content doesn’t render its `{{ for ... }}` loops

Cause. Intentional, not a bug. Squiggly templates inside a markdown body are HTML-escaped before rendering — they get treated as literal text. Only files in layouts/ and partials/ execute templates.

Fix. Move the loop into a layout or partial, and have the markdown call it via shortcode or by being short enough to live inside the layout directly.

When all else fails

Run with -v (verbose) to see every step of the build — file walks, layout selection, what’s being written where:

sbt 'juicerJVM/run build -s <src> -v'

If something’s silently being skipped (missing layout, filtered page, etc.) the verbose output usually shows the line where it bailed. Paste the relevant slice into a GitHub issue along with the smallest reproducer that surfaces it.

Theming

2026-05-27T20:59:11.669095985Z

The bundled themes (juicerdocs, juicerblog, juicerchurch, juicercafe, juicerlanding, juicerportfolio) are designed so a site can rebrand and retune them without touching theme source. There are three layers of override — use whichever fits the change you want to make.

Layer 1 — palette and token overrides via `[juicerXxx]`

Each theme reads a [juicerXxx] table from site.toml (where Xxx is the theme’s name) and emits an inline <style> block in <head>. CSS custom properties get overridden on :root (light) or [data-theme="dark"] (dark). The bundled CSS file is unchanged across every site that uses the theme — only the small inline block differs.

This is the cheapest, fastest theming layer — use it for colour adjustments, font swaps, prose-column widening.

Palette tokens (all four themes)

Key	CSS variable	What
`brand`	`--brand`	Primary brand colour. Hero accents, link underlines, focus rings.
`brandStrong`	`--brand-strong`	Darker variant for emphasised text + headings on light bg.
`brandSoft`	`--brand-soft`	Tinted background for active states, badges, pull quotes.
`accent`	`--accent`	Secondary accent colour (often warm) for CTAs and highlights.
`leaf`	`--leaf`	Tertiary “alive / fresh” colour — recurring-event chips, success states.

For each light token there is a dark variant: brandDark, brandStrongDark, brandSoftDark, accentDark, leafDark. Set them to override the theme’s hardcoded dark palette without leaking into light mode.

Typography tokens

Key	CSS variable	What
`fontSans`	`--font-sans`	Body / UI sans stack
`fontSerif`	`--font-serif`	Serif stack (cafe / church / blog / portfolio — juicerdocs and juicerlanding are sans-only)
`fontMono`	`--font-mono`	Code / monospace stack

Pass a full CSS font stack including fallbacks — e.g. fontSans = "'Inter', system-ui, sans-serif".

Sizing tokens

The chrome-sizing surface differs by theme — each exposes the tokens it actually uses.

For juicercafe, juicerchurch, juicerblog, juicerlanding, juicerportfolio:

Key	CSS variable	What
`measure`	`--measure`	Prose column max-width (default `38rem`; juicerlanding `65ch`; juicerportfolio `62ch`)
`gutter`	`--gutter`	Outer padding around content blocks
`radiusLg`	`--radius-lg`	Large border-radius (cards, hero panels)

For juicerdocs:

Key	CSS variable	What
`contentMax`	`--content-max`	Prose column max-width (default `48rem`)
`sidebarW`	`--sidebar-w`	Left sidebar width (default `16rem`)
`railW`	`--rail-w`	Right TOC rail width (default `18rem`)
`radiusLg`	`--radius-lg`	Large border-radius

Example — quietly retune juicercafe to a teal palette

[juicercafe]
brand           = "#0f766e"   # teal-700# teal-700
brandStrong     = "#134e4a"   # teal-900# teal-900
brandSoft       = "#ccfbf1"   # teal-100# teal-100
accent          = "#7c3aed"   # violet-600# violet-600
brandDark       = "#5eead4"   # teal-300 — lifted for dark bg# teal-300 — lifted for dark bg
brandStrongDark = "#99f6e4"   # teal-200# teal-200
brandSoftDark   = "rgba(94, 234, 212, 0.18)"
accentDark      = "#a78bfa"   # violet-400# violet-400
fontSerif       = "'Source Serif 4', Georgia, serif"
measure         = "42rem"

Layer 2 — `customCSS`: drop your own stylesheet alongside the theme

For overrides that don’t fit a CSS variable (custom selectors, new animations, third-party widgets), drop a stylesheet under static/site.css (or any name) and list it in site.toml:

customCSS = ["site.css"]

The theme’s <head> partial emits each entry as a <link rel="stylesheet"> after the bundled theme CSS, so anything in your file overrides anything in the theme. Multiple entries load in the order listed:

customCSS = ["fonts.css", "branding.css", "site.css"]

This is the right layer for:

Loading a @font-face block for a custom font (then point [juicerXxx] fontSerif at it).
Adding entire new widgets that the theme doesn’t ship.
Vendor / third-party CSS (Mermaid, KaTeX skin, etc.) that has to load on every page.

Files referenced by customCSS are still site static/ content; they’re copied verbatim during build.

Layer 3 — replace a theme file outright

When a site puts a file in static/ with the same path as one the theme ships, the site copy wins during the build. So a site can ship its own static/juicercafe.css to fully replace the theme’s stylesheet (verified by the should ship theme static/ files; site static/ overwrites on path collision build test).

Use this layer sparingly — you lose theme updates for any file you replace. Layers 1 and 2 cover almost every customisation need; reach for Layer 3 only when you need to fork.

Site-wide chrome keys

Top-level site.toml keys, distinct from the per-theme [juicerXxx] tables. Every theme reads them.

Key	Type	Default	What
`favicon`	`String`	unset	Path used in `<link rel="icon">`. Browser infers MIME from extension.
`hideJuicerCredit`	`Boolean`	`false`	Set `true` to omit the “Built with juicer” footer line.
`repoURL`	`String`	unset	Git host URL. juicerdocs surfaces a topbar GitHub icon and a homepage “Star on GitHub” button when set; other themes ignore.
`customCSS`	`[String]`	unset	List of stylesheet paths to load after the bundled theme CSS — see Layer 2 above.
`authorsPath`	`String`	`/authors/`	URL prefix for the team listing + per-author archives. See Template data → authorsPath.

Themes

2026-05-27T20:59:11.669095985Z

A juicer theme is a directory under themes/<name>/ with the same shape as a site:

themes/juicerdocs/
├── layouts/
│   └── _default/
│       ├── baseof.html
│       ├── file.html
│       └── folder.html
├── partials/
│   └── ...
├── shortcodes/
│   └── ...
└── static/
    └── ...

Activate it from site.toml:

theme = "juicerdocs"

That’s it. Juicer scans the theme directory before the site directory and merges the two — site files win on key collisions, so you can override any individual layout, partial, shortcode, or static asset without forking the theme.

Theme chains

The theme key also accepts an array, in which case earlier entries override later ones:

theme = ["my-overrides", "juicerdocs"]

Now my-overrides/ wins over juicerdocs/, which wins over the site itself? No — site always wins. Order is site > my-overrides > juicerdocs. This is useful when you want to reuse most of juicerdocs but customize, say, the topbar with a tiny overlay theme of your own.

A theme can also pull in other themes itself, by declaring them in its own theme.toml — that’s how every bundled theme inherits juicercommon. The site-level theme list and each theme’s declared inherits are resolved together into one lookup chain, first-wins throughout. Theme inheritance covers the resolution rules.

Tip

Theme directories live under themes/ because that’s the themeDir config key’s default. Set themeDir = "" if you want themes to live at the site root, or any other path that fits your repo layout.

What a theme can ship

Subdirectory	What
`layouts/`	Templates for the various page kinds (`_default/file.html`, etc.)
`partials/`	Reusable template fragments — called via `{{ partial 'name' . }}`
`shortcodes/`	Markdown-callable templates — invoked via `[= name =]…[= /name =]`
`static/`	Files copied verbatim into the output tree

Themes do not ship content (no content/ directory inside a theme is ever read), nor do they get top-level “other templates” rendered (HTML templates outside of those directories are always relative to the user’s site).

Picking the right primitive

A partial is a reusable HTML fragment called from another template. It receives whatever data context you pass in.

{{ partial 'topbar' . }}
{{ partial 'topbar' .page }}

Use partials for: page chrome, repeated UI elements, anything you’d factor out of HTML.

A shortcode is a partial called from inside markdown content, via the [= name =] syntax. Authors write content with shortcodes inline:

[= note =]
This is a note callout.
[= /note =]

Use shortcodes for: callouts, tabbed examples, embedded media, anything that’s content but needs richer HTML than markdown alone provides.

A layout is the top-level template for a page kind. Juicer picks the right one by name and folder lookup.

Use layouts for: the actual <html> skeleton and the per-page-kind structural rules.

Bundled themes

Eleven themes ship in the juicer repo, each tuned for a different shape of site. Pick the closest match and override individual files from your own layouts/ or static/:

Theme	Where it lives	What it’s for
`juicerdocs`	`docs/themes/juicerdocs/`	Documentation sites — sidebar nav, “On this page” rail, callout shortcodes. Powers this site.
`juicerblog`	`docs/themes/juicerblog/`	Blogs — post lists with pagination, tag/category/year archives, series nav, author bylines, server-side syntax highlighting.
`juicerstudy`	`docs/themes/juicerstudy/`	Long-form prose — essays, study notes, reading journals, lecture notes. Serif reading column, optional KaTeX math, undated by default.
`juicerlanding`	`docs/themes/juicerlanding/`	Product / SaaS landing pages — single-page section stack (hero, features, pricing, testimonials, FAQ) driven entirely from `site.toml`.
`juicerportfolio`	`docs/themes/juicerportfolio/`	Designer / studio portfolios — image-first project grid, per-project hero + meta sidebar + gallery.
`juicergallery`	`docs/themes/juicergallery/`	Photo galleries — masonry/grid albums, lightbox-ready photo cards, EXIF-light captions.
`juicercafe`	`docs/themes/juicercafe/`	Cafés, small businesses, restaurants — hours widget, menu sections, photo albums, events list.
`juicercook`	`docs/themes/juicercook/`	Recipe sites — Recipe JSON-LD, recipe cards, ingredient/step layout, print-friendly stylesheet.
`juicerchurch`	`docs/themes/juicerchurch/`	Churches, ministries — sermon archive, recurring-event calendar grid, ministries section, photo albums.
`juicerpodcast`	`docs/themes/juicerpodcast/`	Podcasts — episode list, per-episode player + show notes, RSS subscribe links.
`juicerwiki`	`docs/themes/juicerwiki/`	Personal wikis / digital gardens — backlinks, tag cloud, wiki-style search.

These eleven all inherit a twelfth, hidden theme: juicercommon, the shared base that holds the partials, shortcodes, and scripts every theme has in common (the seo block, the dark-mode init/toggle scripts, and the note/tip/warning/tabs/github/… shortcodes). You never select juicercommon directly — each theme’s theme.toml lists it under inherits. See Theme inheritance for how that resolution works.

Each theme has its own section under Themes (linked from the sidebar) with a “what’s in the box” overview and a configuration page that catalogues every [juicerXxx] token, top-level chrome key, and per-page frontmatter convention.

A working demo site lives under docs/demos/ for every bundled theme — for instance, docs/demos/juicerblog/ mirrors juicerblog‘s feature matrix, and docs/demos/juicerlanding/ exercises every section block in juicerlanding. The deploy pipeline builds each demo into /themes/<theme>/demo/ so the sidebar’s “Demo site” leaf for each theme serves it live. Start from the closest demo and edit downward:

sbt 'juicerJVM/run serve -s docs/demos/juicerblog -L'
sbt 'juicerJVM/run serve -s docs/demos/juicerportfolio -L'

Building your own

Reading through any bundled theme end-to-end is a quick tour of the conventions. juicerdocs is the most complete demo of every theme primitive (layouts, partials, shortcodes, static); juicerblog is the smallest theme that touches the blog-specific engine features; juicerlanding is the cleanest demo of a frontmatter-driven page that assembles itself from site.toml blocks.

edadma/juicer GitHub repository

Theme inheritance

2026-05-27T20:59:11.669095985Z

A theme can build on other themes. It declares them in a theme.toml file at its own root:

themes/juicerdocs/
├── theme.toml          ← inherits = ["juicercommon"]
├── layouts/
├── partials/
└── static/

# themes/juicerdocs/theme.toml# themes/juicerdocs/theme.toml
inherits = ["juicercommon"]

When a site activates juicerdocs, juicer doesn’t just look in juicerdocs/ — it walks the inherits list too, splicing each named theme into the lookup chain right after the theme that named it. Partials, shortcodes, layouts, and static files all resolve against this expanded chain.

This is how the bundled themes share code: each one inherits juicercommon, the hidden base theme that holds the seo block, the dark-mode init/toggle scripts, and the common shortcodes (note, tip, warning, tabs, github, …). No theme duplicates them.

The lookup chain

Start from the site’s theme setting — a single name or an array — and walk each theme’s inherits depth-first. The result is one ordered chain. Resolution is first-wins: the earliest place a file is found is the one that’s used.

# site.toml# site.toml
theme = "juicerdocs"

# themes/juicerdocs/theme.toml# themes/juicerdocs/theme.toml
inherits = ["juicercommon"]

resolves to the chain:

site  >  juicerdocs  >  juicercommon

So a partials/seo.html in your site beats juicerdocs‘s, which beats juicercommon‘s. Drop your own partials/note.html into juicerdocs/ and it overrides the shared shortcode without touching juicercommon.

Inheritance composes with the site-level theme array. Both are resolved into the same chain — the array first, then each entry’s inherits:

# site.toml# site.toml
theme = ["my-overrides", "juicerdocs"]

site  >  my-overrides  >  juicerdocs  >  juicercommon

inherits is transitive: if juicercommon itself declared inherits = ["base"], base would land at the end of the chain.

Note

Precedence never changes: site files always win, then themes in chain order. Inheritance only makes the chain longer — it never lets a theme override the site.

Deduplication

A theme reached more than once — a diamond, where two themes both inherit a common base — appears in the chain once, at its earliest position:

# site.toml# site.toml
theme = ["themeA", "themeB"]   # both inherit "shared"# both inherit "shared"

site  >  themeA  >  shared  >  themeB

shared resolves once, kept at its first occurrence. A file defined in themeA, themeB, and shared is won by themeA (earliest in the chain).

Errors

Warning

A theme that lists a non-existent theme in inherits fails the build with a clear message:

theme 'juicerdocs' inherits unknown theme 'typo' — no directory at …

A cycle — A inherits B inherits A — also fails, with the path traced so you can see where it closes:

theme cycle: themeA → themeB → themeA

A missing theme named at the site level (in site.toml‘s theme) is treated leniently — it’s simply skipped — matching juicer’s long-standing behavior. Only inherits links are validated strictly, because a theme author controls its own dependencies.

No theme.toml?

A theme with no theme.toml inherits nothing — it’s exactly equivalent to inherits = []. Themes written before this feature existed keep working byte-for-byte; inheritance is purely additive.

Tip

theme.toml currently understands a single key, inherits. It’s the one place themes declare their dependencies, so a theme is self-describing — you can read its theme.toml and know the whole chain it expects.

Templates

2026-05-27T20:59:11.669095985Z

Templates live under layouts/ and are written in squiggly, a Go-template-style language. Every template is plain HTML with {{ ... }} interpolation.

Template kinds

Kind	Filename pattern	When it’s used
`baseof`	`_default/baseof.html`	Outer shell — wraps every page
`file`	`_default/file.html`	Single-page template
`folder`	`_default/folder.html`	Section-index template
Partial	`partials/<name>.html`	Called via `{{ partial 'name' . }}`
Shortcode	`shortcodes/<name>.html`	Called from markdown via `[= name =]`

The _default/ folder name comes from the defaultLayout config key. You can also place per-section overrides in layouts/<section>/ — juicer falls back to _default/ when a section-specific layout is missing.

The two-pass render

When both a particular template (file.html or folder.html) AND a baseof.html exist:

First pass — the particular template runs

Its output is discarded. What matters are the {{ define <name> }}…{{ end }} blocks it populates.

Second pass — `baseof.html` runs

Its {{ block <name> . }}…{{ end }} calls pull the previously-defined content into place.

This pattern lets a single baseof.html provide the entire page chrome (head, header, sidebar, footer) while file.html and folder.html only describe what goes in the main column.

<!DOCTYPE html>
<html>
<head><title>{{ .page.title }}</title></head>
<body>
  {{ partial 'topbar' . }}
  <main>
    {{ block main . }}{{ .content }}{{ end }}
  </main>
</body>
</html>

{{ define main }}
  <article class="prose">
    <h1>{{ .page.title }}</h1>
    {{ .content }}
  </article>
{{ end }}

{{ define main }}
  <article class="prose">
    <h1>{{ .page.title }}</h1>
    {{ .content }}
  </article>
<ul>
{{ for p <- .section.pages }}
<li><a href=“{{ p.url }}“>{{ p.title }}</a></li>
{{ end }}
</ul>
{{ end }}

The data context

Every page renders against a fixed data context:

Variable	What it holds
`.site`	Site config + `pages`, `pagesByPath`, `root`
`.page`	The current page record (frontmatter + url + summary + nav fields)
`.section`	Enclosing section’s pages + subsections + index
`.content`	Rendered markdown body
`.toc`	Heading tree
`.sub`	First heading’s children, flattened

Inside .page:

.page.title, .page.summary — from frontmatter (summary is auto-derived if absent)
.page.url, .page.relPermalink, .page.permalink — three URL flavors
.page.parent, .page.ancestors — section navigation (parent’s _index record, then the root → parent chain)
.page.next, .page.prev — sibling navigation (by section page order)
.page.isSection — true for _index.md pages
.page.pages, .page.subsections — children — populated only on _index.md pages
.page.date, .page.dateISO, .page.dateLong, .page.dateShort — set when frontmatter date: is present (or mtime fallback)
.page.tags, .page.categories — always lists (a single string in frontmatter is wrapped)
.page.author, .page.authors — resolved author registry records
.page.wordCount, .page.readingTime — auto-computed from the rendered body
Plus any custom frontmatter key

See Reference / Template data for the full set.

Template syntax

2026-05-27T20:59:11.669095985Z

Squiggly is the template language juicer uses. It’s Go-template-like. This page is the practical cheatsheet; the full squiggly reference covers everything else.

Substitution

{{ .name }}              value at .name in the data context
{{ .page.title }}        nested
{{ .args[0] }}           list element by index (in shortcodes)

Built-in functions

Juicer adds a few project-specific functions to squiggly’s defaults. Call them as expressions:

Function	What
`{{ relURL '/path' }}`	Site-relative URL (`baseURL.path` prefix added if non-trivial)
`{{ absURL '/path' }}`	Absolute URL (`baseURL.base + relURL`)
`{{ relLangURL lang '/path' }}`	Like `relURL`, but prefixed with `lang`‘s URL segment (Hugo’s `relLangURL`) — see i18n
`{{ absLangURL lang '/path' }}`	Like `absURL`, but prefixed with `lang`‘s URL segment
`{{ markdownify s }}`	Render a markdown string to HTML
`{{ emojify s }}`	Replace `:smile:` etc. with Unicode emoji
`{{ i18n lang 'key' }}`	Look up an i18n string (falls back to default lang then literal key)
`{{ ogTags .page }}`	Emit OpenGraph + Twitter card `<meta>` tags for a page record
`{{ imageDims '/path' }}`	Read pixel dimensions of an on-disk image; returns `{width, height}` or empty map (see below)
`{{ imageVariants '/path' }}`	Generate resized + reformatted variants of an image; returns `{original, originalWidth, originalHeight, variants}` (see below)
`{{ srcset '/path' 'fmt' }}`	One-liner: build the comma-separated `srcset` body for one variant format (see below)

`imageDims`

Reads the header of an image on disk and returns a map with width and height (pixel ints). Useful for emitting <img width=... height=...> so the browser can reserve space before the bytes arrive — eliminates cumulative layout shift.

{{ d := imageDims '/img/hero.jpg' }}
{{ if d.width }}
  <img src="/img/hero.jpg" width="{{ d.width }}" height="{{ d.height }}" alt="" />
{{ else }}
  <img src="/img/hero.jpg" alt="" />
{{ end }}

Resolution order: the path is looked up first under the built output directory (so theme + site static/ files and any generated images work), then under the source root. Paths can be site-absolute (/img/x.png) or relative; absolute URLs (http://…) are not fetched.

Returns an empty map when the file is missing, unreadable, or in a format the header parser does not understand. Recognized formats: PNG, JPEG (baseline + progressive), GIF87a/89a, WebP (VP8 / VP8L / VP8X). Pure Scala — no javax.imageio, no FFI, works on every target.

Per-build cache: each unique path is read once even if a shortcode fires across hundreds of pages.

`imageVariants` and `srcset`

Opt-in build-time image-variant generation. With an [images] block in site.toml and ImageMagick (magick) on PATH, juicer will resize and reformat source images into a <picture>-ready variant set:

[images]
enabled  = true
widths   = [320, 640, 960, 1280]
formats  = ["webp", "original"]   # most-modern first; original is a passthrough# most-modern first; original is a passthrough
quality  = 80
cacheDir = ".image-cache"

imageVariants returns the full structured shape — useful when a theme emits its own <picture> markup:

{{ v := imageVariants '/img/hero.jpg' }}
{{ if v.variants }}
  <picture>
    {{ for src <- v.variants }}
      {{ if src.mime and src.format != 'original' }}
        <source srcset="{{ src.url }} {{ src.width }}w" type="{{ src.mime }}" />
      {{ end }}
    {{ end }}
    <img src="{{ v.original }}" width="{{ v.originalWidth }}" height="{{ v.originalHeight }}" alt="" />
  </picture>
{{ else }}
  <img src="{{ v.original }}" alt="" />
{{ end }}

Returned map:

Key	Type	What
`original`	string	URL of the passthrough original (site-absolute)
`originalWidth`	int	Pixel width of the source (`0` if unknown)
`originalHeight`	int	Pixel height of the source (`0` if unknown)
`variants`	list	One `{width, format, url, mime}` per generated variant

srcset is a one-liner shorthand for the common case where a layout wants to drop the variant list straight into an <img srcset=...> attribute for a single format:

<img src="/img/hero.jpg"
     srcset="{{ srcset '/img/hero.jpg' 'webp' }}"
     sizes="(min-width: 800px) 50vw, 100vw"
     alt="" />

Returns "" when the requested format isn’t in [images].formats, the source can’t be resolved, or variants weren’t generated (feature off, encoder missing, etc.).

Cache & encoder. Every generated filename embeds a 64-bit FNV-1a hash of the source bytes (hero-640w.<hash>.webp), so re-running the build on an unchanged image skips the encoder shell-out and editing the image invalidates every variant in one shot. The encoder backend (magick) is probed once per build; if it’s not on PATH a single advisory prints to stderr and the feature degrades cleanly to a passthrough-only VariantSet (variants is empty). Same behaviour on the Scala Native and Scala.js targets until process-spawn lands in cross_platform.

Widths above the source’s own width are dropped (no upscaling); the source’s exact width is always included so the fallback <img> can point at a same-size variant. The original slot at the source width is a 1:1 byte copy rather than an encoder round-trip — keeps build time sane on photo-heavy sites and preserves source bytes exactly.

Conditionals

{{ if .page.summary }}
  <p class="lead">{{ .page.summary }}</p>
{{ end }}

{{ if .page.draft }}
  <span class="badge">Draft</span>
{{ else }}
  <span class="badge">Published</span>
{{ end }}

if is truthy on non-empty strings, non-zero numbers, non-empty lists/maps, and true. null / empty / false / 0 are falsy.

Logical operators: and, or, prefix not.

{{ if .page.prev or .page.next }}
  <nav>...</nav>
{{ end }}

Loops

{{ for p <- .section.pages }}
  <li><a href="{{ p.url }}">{{ p.title }}</a></li>
{{ end }}

{{ for k, v <- .page }}
  {{ k }}: {{ v }}
{{ end }}

Partials

{{ partial 'topbar' . }}              call partials/topbar.html with the current data
{{ partial 'page-toc' .page }}        with a different data context

Defines & blocks

{{ define main }}
  <article>{{ .content }}</article>
{{ end }}

{{ block main . }}{{ .content }}{{ end }}    fallback content if main isn't defined

define is statement-level (no output). block <name> <data> looks up the named block, calls it with <data> as the context, falls back to its inner template if the block isn’t defined.

Builtin filters

Most squiggly builtins work as either a function or a pipe target:

{{ trim .page.summary }}
{{ .page.summary | trim }}
{{ .name | upper }}
{{ .x | replace 'foo' 'bar' }}

Useful ones:

Builtin	What
`len`	Length of a list / string
`head`	First element of a list
`tail`	All but the first
`trim`	Trim whitespace
`upper` / `lower`	Case
`replace 'a' 'b'`	String substitution
`split 'sep'`	String split
`join 'sep'`	List join

Comments

{{ // squiggly's not too noisy in templates }}

Scope inside loops

Inside a {{ for x <- coll }} block, .foo resolves against the current iterated element, not the outer page context. Use $.foo to reach back up to the top-level data root:

{{ for p <- .section.pages }}
  <li>
    <a href="{{ p.url }}">{{ p.title }}</a>
    {{ if eq p.url $.page.url }}<span>(this page)</span>{{ end }}
  </li>
{{ end }}

A common pitfall: writing {{ .site.title }} inside a loop and getting nothing. Use {{ $.site.title }} — .site doesn’t exist on the iterated element.

Template data

2026-05-27T20:59:11.669095985Z

Every template renders against a single map. The top-level keys are documented below; nested fields follow.

`.site`

The merged site config (site.toml overlaid on the baseline) plus a few computed extras:

Key	Type	What
`.site.<config>`	varies	Every key from `site.toml`
`.site.toc`	`List[TOCItem]`	Site-wide auto-nav (only if no `nav` is set)
`.site.start`	`String?`	URL of the conventional landing page
`.site.pages`	`List[Map]`	Every page’s enriched record
`.site.pagesByPath`	`Map[String, Map]`	Same records, keyed by `relPermalink`
`.site.posts`	`List[Map]`	Dated, non-section, non-`static` pages, newest first (see below)
`.site.pagesByYear`	`List[Map]`	Same posts grouped by year, year descending (see below)
`.site.root`	`Map?`	The root section’s `_index` record (or `null`)
`.site.tags`	`List[Term]`	Every distinct tag used in the site (see below)
`.site.categories`	`List[Term]`	Same shape as `.site.tags`, for the categories axis
`.site.authors`	`List[Map]`	Every author with at least one referencing page — registry record + `id`, `url`, `count`, `pages`
`.site.authorRegistry`	`List[Map]`	The raw `[[authors]]` table from `site.toml` in declaration order — includes authors with zero referencing pages, useful for staff-directory layouts (see below)
`.site.authorsPath`	`String`	URL prefix under which the team listing and per-author archives are emitted. Configured by `authorsPath` in `site.toml`; defaults to `/authors/`. See below
`.site.now`	`Map`	Build-time “now” timestamp in four shapes (see below)
`.site.events`	`List[Map]`	Pages in the configured `eventsSection` with explicit `date:` frontmatter, sorted ascending. Includes future-dated events (see below)
`.site.calendar`	`List[Map]`	Pre-computed N months of calendar grid starting at the current month, with weekly recurring events expanded onto every matching weekday (see below)
`.site.photos`	`List[Map]`	Aggregated `photos:` frontmatter entries from every page, sorted by parent-page date descending (see below)
`.site.data`	`Map[String, Any]`	Nested namespace of structured data loaded from `data/` files (see below)
`.site.comments`	`Map[String, Any]?`	The `[comments]` config block from `site.toml` (provider + provider-specific keys), or absent if no `[comments]` table is set (see below)

`Term` shape

Every entry in .site.tags and .site.categories (and on tag-archive templates, the elements of .terms) has these fields:

Key	Type	What
`name`	`String`	The original tag name as it appeared in frontmatter
`slug`	`String`	URL-safe form (lowercased, ASCII-folded, non-alnum runs collapsed to `-`)
`url`	`String`	Site-relative archive URL — `/tags/<slug>/` or `/categories/<slug>/`
`count`	`Int`	How many pages reference this term
`pages`	`List[Map]`	The pages themselves, each in the same shape as a `.site.pages` entry

`.site.posts` and `.site.pagesByYear`

Curated views of the post stream — the same data, sliced two ways.

.site.posts is the flat list, newest first. A page is included if it has an explicit parsed date: in frontmatter, is not a section index (_index.md), and is not flagged static: true. Filesystem-mtime fallback dates do not count — only authored dates make it in. The result is exactly the set of pages a blog or news site would call “the posts.”

.site.pagesByYear groups the same list by calendar year, with years descending and pages within each year still newest-first:

Key	Type	What
`year`	`Int`	The 4-digit year
`count`	`Int`	Posts in this year
`pages`	`List[Map]`	The posts themselves, each shaped like a `.site.pages` entry

Useful for chronological archive pages (<h2>2024</h2> then a list).

`.site.authorRegistry`

The raw [[authors]] table from site.toml, preserved in declaration order. Each entry is the verbatim TOML table — id, name, role, bio, avatar, email, plus any custom fields you’ve added.

Distinct from .site.authors, which is filtered to authors who have at least one referencing page and is augmented with count, url, and pages. Use .site.authorRegistry for staff-directory layouts that should show every team member regardless of how many sermons or posts they’ve authored; use .site.authors for “browse by author” archives.

When `/authors/` and `/authors/<id>/` get rendered

The two layouts have different gates so themes can ship a “team page” that shows everyone, even on a fresh site with no posts:

layouts/_default/author-list.html → /authors/index.html is rendered whenever a registry exists at all ([[authors]] non-empty in site.toml). The layout typically iterates .site.authorRegistry.
layouts/_default/author-page.html → /authors/<id>/index.html is only rendered for authors with at least one referencing page. An empty per-author archive page would be misleading.

Either layout is opt-in — missing the file means the corresponding output is silently skipped.

Renaming the URL prefix — `authorsPath`

By default both the team listing and the per-author archives live under /authors/. Sites using a non-blog theme often want a different label — a cafe wants /team/, a doc site wants /people/. Set authorsPath in site.toml:

authorsPath = "/team/"

The engine pivots three things in lockstep: the on-disk output directory, the url field on every .site.authors term, and the .site.authorsPath string surfaced for templates. Themes should read {{ .site.authorsPath }} rather than hard-coding /authors/ so a site-level override propagates without a layout edit.

Forgiving normalization: team, /team, team/, and /team/ all become /team/. Path traversal segments (., ..) are rejected with a warning and the default is used.

`.site.now`

Build-time timestamp captured once per build, in four shapes so the right one is always at hand:

Key	Type	What
`iso`	`String`	Full ISO offset — `2026-05-09T14:00:00Z`
`date`	`String`	`YYYY-MM-DD`, lex-comparable with `.page.dateShort` for past/future filters
`long`	`String`	`May 9, 2026`, same formatter as `.page.dateLong`
`year`	`Int`	Useful for footer copyright

The static-site model means “now” is legitimately frozen at build time. Live-reload re-runs the build on every change, so the value stays fresh during local preview.

`.site.events`

Pages in the configured events section (eventsSection in site.toml, default "events") with an explicit date: frontmatter, sorted ascending. Each entry is shaped like a .site.pages record — title, url, date, dateShort, summary, plus any frontmatter the event page declares (eventTime, eventLocation, recurring, etc.).

Includes future-dated events: events are announced before they happen, and the engine’s site-wide future-post filter is exempted for pages in the events section so both .site.events entries and the corresponding event detail pages survive the build. Future-dated posts (anything outside the events section) continue to be future-skipped — see the --future CLI flag to override per build.

Recurring events appear once each (the canonical page record); use .site.calendar for occurrence-by-occurrence expansion.

`.site.calendar`

Pre-computed N months (default 12, override via calendarMonths in site.toml) starting at the current month. Each month is:

Key	Type	What
`year`	`Int`	4-digit year
`month`	`Int`	1–12
`monthName`	`String`	`"May"`
`label`	`String`	`"May 2026"`
`weeks`	`List[List[Cell]]`	Always six 7-day rows, Sunday-first

Each cell:

Key	Type	What
`day`	`Int?`	1–31, or `null` for out-of-month padding cells
`isToday`	`Boolean`	`true` for the cell whose year/month/day matches `.site.now`
`events`	`List[Map]`	Basic page records for events on this day (empty list when none)

Recurring weekly events (recurring: weekly + optional recurringDay:) are expanded onto every matching weekday from their start date forward. A recurring event with no recurringDay: defaults to its start-date’s day of the week. Non-recurring events appear once on their date.

The grid is always 6×7 = 42 cells per month so calendar templates don’t have to special-case month boundaries; out-of-month cells render as day=null padding.

`.site.photos`

Aggregated photos: frontmatter entries from every page on the site, sorted by the parent page’s date descending. Each entry:

Key	Type	What
`src`	`String`	Image URL (absolute or site-relative)
`caption`	`String`	Display caption — empty string when not provided
`alt`	`String`	Accessibility text — falls back to `caption` when absent
`page`	`Map`	Basic page record of the parent page (lets templates link the photo back to its event/album/sermon)

Frontmatter shape — either a list of strings (URLs only) or a list of maps with src / caption / alt keys:

photos:
  - "/img/picnic-01.jpg"
  - { src: "/img/picnic-02.jpg", caption: "The pie table" }

Pages without a photos: frontmatter contribute nothing.

`.site.data`

Structured data the theme or site author wants templates to reach for without forcing it into every page’s frontmatter. juicer scans the dataDir (default data/) under the site root and under each active theme:

data/team.toml              → .site.data.team
data/menu/lunch.yaml        → .site.data.menu.lunch
data/menu/dinner.toml       → .site.data.menu.dinner

The file’s basename (sans extension) becomes the leaf key; each directory under data/ becomes a nesting level. Both .toml and .yaml / .yml are accepted — pick whichever shape fits the data better. JSON is not parsed natively, but since it’s a strict subset of YAML you can rename .json → .yaml and it works.

A typical use:

# data/team.toml# data/team.toml
[[members]]
name = "Alice"
role = "Lead"

[[members]]
name = "Bob"
role = "Eng"

{{ for m <- .site.data.team.members }}
  <li>{{ m.name }} — {{ m.role }}</li>
{{ end }}

Theme overlay. Themes can ship their own data/ directory; site entries win at the file-leaf granularity. If a theme provides data/site.toml and the site provides data/site.toml, the site’s file replaces the theme’s at the .site.data.site key path. The site does not deep-merge fields — to support partial overrides as a theme author, namespace into a subdirectory (data/colors/default.toml + data/colors/dark.toml).

Format notes. TOML at a file root always parses to a map; YAML can parse to a list (data/sponsors.yaml starting with - name: ...) or a scalar, but a map is by far the most useful shape because nested-field access (.site.data.sponsors[0].name) is more readable than positional indexing in most templates.

`.site.comments`

A pass-through of the [comments] table from site.toml (see Config → [comments]). juicer never ships a comments backend — the config block is opaque to the engine, and theme partials are responsible for reading it and emitting the embed HTML.

provider is the only convention; everything else is provider-specific and theme-defined. A theme that supports several providers typically branches on it:

{{ if .site.comments }}
  {{ if eq .site.comments.provider 'giscus' }}
    {{ partial 'comments/giscus.html' . }}
  {{ end }}
  {{ if eq .site.comments.provider 'utterances' }}
    {{ partial 'comments/utterances.html' . }}
  {{ end }}
  {{ if eq .site.comments.provider 'disqus' }}
    {{ partial 'comments/disqus.html' . }}
  {{ end }}
{{ end }}

The outer {{ if .site.comments }} is the right gate for “comments on or off site-wide” — when no [comments] table is set in site.toml, .site.comments is absent and the conditional evaluates falsy. Themes that allow per-page opt-out also check {{ if .page.comments }} (or similar) so individual posts can override the site-wide setting.

Alias pages

Frontmatter aliases: [...] makes juicer emit a redirect page at each listed URL. The alias layout (or built-in fallback) sees a separate data context:

Key	Type	What
`.target`	`String`	Site-relative canonical URL
`.absTarget`	`String`	Absolute canonical URL (`baseURL` + `.target`)
`.page.<...>`	varies	Every field of the canonical page’s record
`.site.<...>`	varies	The full site context

If layouts/_default/alias.html exists, it’s rendered with the data above. Otherwise juicer writes a minimal built-in HTML page with a <meta http-equiv="refresh"> to .target.

`.page`

The current page’s enriched record:

Key	Type	What
`.page.title`	`String`	Frontmatter title
`.page.summary`	`String`	Resolved summary (frontmatter / `<!--more-->` / fallback)
`.page.url`	`String`	Site-relative URL
`.page.relPermalink`	`String`	Same as `url`, named for Hugo parity
`.page.permalink`	`String`	Absolute URL (baseURL + url)
`.page.slug`	`String`	URL stem (last path segment, no slashes) — useful for in-page anchors when a layout walks `.section.pages` and wants a stable per-section HTML id. `""` for the root index.
`.page.isSection`	`Boolean`	`true` for `_index.md` pages
`.page.parent`	`Map?`	Enclosing section’s `_index` record
`.page.ancestors`	`List[Map]`	Root → parent chain (excluding self)
`.page.next`	`Map?`	Next page in section by `pageOrder`
`.page.prev`	`Map?`	Previous page in section
`.page.tags`	`List[String]`	Frontmatter `tags` (always a list, even when authored as a single string)
`.page.categories`	`List[String]`	Frontmatter `categories`, normalized the same way
`.page.date`	`OffsetDateTime`	Parsed publication date (frontmatter `date` or filesystem mtime fallback)
`.page.dateISO`	`String`	`2024-03-12T00:00:00Z` — for `<time datetime=...>`
`.page.dateLong`	`String`	`March 12, 2024` — for body copy
`.page.dateShort`	`String`	`2024-03-12` — for compact lists
`.page.wordCount`	`Int`	Word count of the rendered HTML body
`.page.readingTime`	`Int`	Estimated minutes (`ceil(wordCount / 200)`, floor 1 for non-empty pages)
`.page.series`	`Map?`	Series block — `null` when the page is not in a series (see below)
`.page.author`	`Map?`	First (or only) resolved author registry record, or `null`
`.page.authors`	`List[Map]`	All resolved author records — empty list when none
`.page.backlinks`	`List[Map]`	Thin `{title, url, summary}` records for every page that links to this one — empty list when nothing points here (see below)
`.page.assets`	`List[Map]`	Page-bundle assets at this page’s section level — `{name, url, ext}` per file. Empty list when the bundle has no assets (see Page bundles)
`.page.<custom>`	varies	Any frontmatter key

`.page.series` shape

Set when the page declares series: in frontmatter:

Key	Type	What
`name`	`String`	Series name as it appeared in frontmatter
`pages`	`List[Map]`	Every page in the series, ordered (see ordering rules below)
`prev`	`Map?`	Previous page’s record, or `null` on the first
`next`	`Map?`	Next page’s record, or `null` on the last
`index`	`Int`	1-based position of this page within the series
`total`	`Int`	Number of pages in the series

Ordering: explicit seriesOrder ascending first, then .page.date ascending, then filename as a stable tiebreaker.

For section index pages (where .page.isSection is true), additionally:

Key	Type	What
`.page.pages`	`List[Map]`	Non-`_index` siblings, sorted
`.page.subsections`	`List[Map]`	Direct child sections, sorted

`.page.backlinks` shape

A list of thin records — one per page that contains an internal link pointing at the current page’s permalink. Sorted by referrer title for deterministic rendering.

Key	Type	What
`title`	`String`	Referrer’s frontmatter title (or URL if title absent)
`url`	`String`	Referrer’s site-relative URL
`summary`	`String`	Referrer’s resolved summary

Templates that need a richer referrer record (tags, date, author, etc.) look it up via .site.pagesByPath[bl.url] — keeping the embedded records thin avoids cycles when two pages link each other.

The inverted index is built during the markdown pass from each page’s AST link destinations. Filtered out at collection time: absolute URLs (https://…, mailto:, tel:), fragment-only anchors (#section), and self-links. Query strings and fragments are stripped before matching, so [X](/target/#section) and [X](/target/?q=1) both count as a link to /target/. Lists, tables, definition lists, footnote definitions, blockquotes, and list items are all walked — anywhere an author can drop a [text](url) in markdown, it counts.

Wiki-style “Linked from” footer in a layout:

{{ if .page.backlinks }}
  <aside class="backlinks">
    <h2>Linked from</h2>
    <ul>
      {{ for bl <- .page.backlinks }}
        <li><a href="{{ bl.url }}">{{ bl.title }}</a>{{ if bl.summary }} — {{ bl.summary }}{{ end }}</li>
      {{ end }}
    </ul>
  </aside>
{{ end }}

`.section`

Always available (for non-_index pages it describes the enclosing section):

Key	Type	What
`.section.pages`	`List[Map]`	Non-`_index` siblings, sorted
`.section.subsections`	`List[Map]`	Direct child sections, sorted
`.section.index`	`Map?`	Section’s `_index` record
`.section.assets`	`List[Map]`	Page-bundle assets for the enclosing section (see Page bundles)
`.section.paginator`	`Map`	Pagination state for the current slice (always present — see below)

`.section.paginator`

Section index pages render once per slice when paginate is set. Non-section pages get a paginator with total = 1 so the same template can read it unconditionally.

Key	Type	What
`current`	`Int`	1-based index of the current slice
`total`	`Int`	Slice count
`pages`	`List[Map]`	The pages on this slice (already sliced — don’t slice again)
`first`	`String`	URL of slice 1
`last`	`String`	URL of the last slice
`prevURL`	`String`	URL of the previous slice; empty string on slice 1
`nextURL`	`String`	URL of the next slice; empty string on the last slice

Slice 2+ lives at <section>/page/<N>/index.html — directory-style URLs that work on any static host without rewrite rules.

Page bundles

A page bundle is a content directory whose non-markdown files (images, attachments, anything that isn’t .md / .toml / .yaml / .yml / .html / .sq) are co-located with the page and get copied to the section’s output URL.

Drop assets next to the markdown:

content/iceland-2024/
  _index.md
  hero.jpg
  skogafoss.jpg
  notes.md

At build time juicer copies the assets to the section’s outdir and exposes them on the page record:

hero.jpg → dst/html/iceland-2024/hero.jpg → URL /iceland-2024/hero.jpg.
{{ .page.assets }} on the section index OR on notes.md is the same list — assets are per-directory, not per-page. .section.assets is an alias for templates that prefer to read them off the section.

Each asset record:

Key	Type	What
`name`	`String`	On-disk filename, preserved verbatim (case, dot) — assets are NOT slugified
`url`	`String`	Site-relative URL — `<section-permalink>/<name>`
`ext`	`String`	Lowercase extension without the dot, or `""` for extensionless files

Iterate in a layout to render a gallery, an attachments list, etc.:

{{ if .page.assets }}
  <ul class="bundle-files">
    {{ for a <- .page.assets }}
      <li><a href="{{ a.url }}">{{ a.name }}</a></li>
    {{ end }}
  </ul>
{{ end }}

Bundle-relative image paths

Inside a bundle, imageVariants, srcset, and imageDims resolve bare (no-leading-/) paths against the page’s source bundle before falling back to static/. That means a hero image lives at the page and the template doesn’t need to know where:

{{ with vs = imageVariants 'hero.jpg' }}
  <picture>
    <source type="image/webp" srcset="{{ srcset 'hero.jpg' 'webp' }}">
    <img src="{{ vs.original }}" width="{{ vs.originalWidth }}" height="{{ vs.originalHeight }}" alt="">
  </picture>
{{ end }}

Move the bundle to a different URL, the layout still works. Absolute paths (/static/hero.jpg) continue to resolve from the source root — the bundle preference only kicks in for bare paths.

When NOT to use a bundle

Site-wide chrome (logo, favicon, fonts): keep these in static/ so every page can reach them via an absolute URL.
Shared assets used from many pages: same — bundles are for page-specific files. Putting a logo in every bundle would duplicate bytes and break a logo swap.
Files in a directory with no markdown content. Bundles need a page to anchor them; orphan assets are silently skipped.

`asset` builtin

The asset template function resolves a logical name into the URL of its compiled (and optionally fingerprinted) output. The manifest comes from the [assets] pipeline.

<link rel="stylesheet" href="{{ asset 'site.css' }}">
<script src="{{ asset 'main.js' }}" defer></script>

Resolution case	What `asset 'foo.css'` returns
`[assets]` disabled or no pipeline run	`foo.css` (the input unchanged)
Pipeline ran, `fingerprint = false`	The configured `output` URL (e.g. `/css/foo.css`)
Pipeline ran, `fingerprint = true`	The fingerprinted URL (e.g. `/css/foo.<16-hex>.css`)
Name not in manifest (typo / never built)	`foo.css` (the input unchanged) — visible as a broken `<link href>` in the rendered HTML

The “input unchanged on miss” rule is deliberate: a typo’s effect shows up in the rendered HTML rather than disappearing into an empty string, which is faster to spot in a build output or a browser devtools panel.

Site-wide chrome keys

Top-level site.toml keys that the bundled themes read from .site.* to drive shared chrome — favicon, footer attribution, repo link, custom stylesheets — are catalogued in Theming along with the per-theme [juicerXxx] palette / typography / sizing tables.

Other top-level

Key	Type	What
`.content`	`String`	Rendered markdown body, HTML
`.toc`	`Map`	`{ headings: [TocEntry] }` — full heading tree
`.sub`	`List`	Children of the first heading, flattened

Page ordering

pageOrder is weight ascending, then name ascending. Pages with no weight frontmatter sort after weighted pages but before any sentinel value.

Note

You’ll almost always want to set explicit weight values on pages that need a particular order — installation before quickstart, etc. Anything that ships a weight lower than the default (9223372036854775807 = Long.MaxValue / 2) wins.

Shortcodes

2026-05-27T20:59:11.669095985Z

Shortcodes are templates invoked from inside markdown using [= name =] syntax. The juicerdocs theme ships 16 of them, covering callouts, structured docs blocks, embeds, and inline atoms. This page is the catalogue — one entry per shortcode with the exact syntax, the rendered look, and any arguments it accepts.

Note

These are juicerdocs shortcodes. They live under docs/themes/juicerdocs/shortcodes/. If you’re using a different theme, you won’t get this set — bring your own, copy individual ones into <src>/shortcodes/, or include juicerdocs in your theme chain. See Concepts → Shortcodes for the calling conventions and how to author your own.

Tip

Escaping in this page. The code-fence examples below use [= (backslash-prefixed) so the preprocessor leaves the literal shortcode syntax in place rather than expanding it. When you write shortcodes in your own content, drop the backslash.

Callouts

Five admonition flavours, each a paired shortcode that wraps a markdown body. They share styling: a tinted background, a small icon, generous padding.

`[= note =]`

Neutral information. Use for “by the way” asides that the reader can skip without missing anything load-bearing.

[= note =]
The frontmatter format is YAML. JSON and TOML frontmatter are
**not** supported.
[= /note =]

Note

The frontmatter format is YAML. JSON and TOML frontmatter are not supported.

`[= tip =]`

A suggestion or shortcut. Use for “you can also …” content where the alternative path is sometimes the better one.

[= tip =]
The `juicer config` subcommand prints the merged config — it's
the fastest way to debug "why is this key not doing what I expect?"
[= /tip =]

Tip

The juicer config subcommand prints the merged config — it’s the fastest way to debug “why is this key not doing what I expect?”

`[= warning =]`

Something worth slowing down for. Use when ignoring this information will produce a confusing failure later.

[= warning =]
Permalink templates change both the URL and the on-disk write
location. Juicer doesn't keep both copies.
[= /warning =]

Warning

Permalink templates change both the URL and the on-disk write location. Juicer doesn’t keep both copies.

`[= danger =]`

A serious caveat. Use for “this will break things” — destructive operations, security caveats, irreversible flags.

[= danger =]
Never expose a shortcode that takes user input straight into HTML.
Run it through `markdownify` or escape it explicitly.
[= /danger =]

Danger

Never expose a shortcode that takes user input straight into HTML. Run it through markdownify or escape it explicitly.

Picking the right callout

A rule of thumb: note for information, tip for a better path, warning for a foot-gun, danger for something that will actively break.

Structured blocks

`[= steps =]`

Numbered, vertically-laid-out steps. Headings inside (## Step name) are auto-numbered; the body of each step is regular markdown.

[= steps =]
## Install Juicer

Clone the repo and verify with `sbt 'juicerJVM/run --help'`.

## Make a site directory

Create `site.toml`, a `content/` folder, and `layouts/_default/`.

## Build & serve

Run `sbt 'juicerJVM/run serve -s .'` and open <http://localhost:8080>.
[= /steps =]

Install Juicer

Clone the repo and verify with sbt 'juicerJVM/run --help'.

Make a site directory

Create site.toml, a content/ folder, and layouts/_default/.

Build & serve

Run sbt 'juicerJVM/run serve -s .' and open http://localhost:8080.

`[= tabs =]` / `[= tab "Label" =]`

Tabbed content panes. The outer tabs is a container; each tab takes a label as a positional arg and a markdown body.

[= tabs =]
[= tab "JVM" =]
sbt 'juicerJVM/run build -s docs'
[= /tab =]
[= tab "Native" =]
juicer build -s docs
[= /tab =]
[= /tabs =]

sbt 'juicerJVM/run build -s docs'

juicer build -s docs

node ./juicer-cli.js build -s docs

`[= filetree =]`

Renders the inner content in a monospace box. Use it for tree-style directory listings — box-drawing characters paste in as-is.

[= filetree =]
my-site/
├── content/
│   ├── _index.md
│   └── about.md
└── site.toml
[= /filetree =]

my-site/
├── content/
│   ├── _index.md
│   └── about.md
├── layouts/
│   └── _default/
│       ├── file.html
│       └── folder.html
└── site.toml

`[= collapse "Summary" =]`

Native <details> / <summary> with juicerdocs styling. The positional argument is the summary text; the body is the collapsed content (markdown is rendered inside).

[= collapse "Why no JSON frontmatter?" =]
YAML covers the use case fluently, and supporting three formats
triples the surface area to keep correct.
[= /collapse =]

Why no JSON frontmatter?

YAML covers the use case fluently, and supporting three formats triples the surface area to keep correct.

Inline atoms

Self-closing shortcodes for short, in-line UI flourishes.

`[= kbd "Ctrl+K" /=]`

Renders a <kbd> element styled to look like a keycap. One positional argument: the key combo to display.

Press [= kbd "Ctrl+K" /=] to focus search.
Press [= kbd "Cmd+Shift+R" /=] to hard-reload.

Press Ctrl+K to focus search. Press Cmd+Shift+R to hard-reload.

`[= badge "alpha" /=]`

A small pill-shaped tag. One positional argument: the text inside.

Tag your alpha pages with [= badge "alpha" /=] so readers know.
[= badge "v0.2" /=] [= badge "beta" /=] [= badge "experimental" /=]

Tag your alpha pages with alpha so readers know. v0.2 beta experimental

Buttons & calls-to-action

`[= button "Label" href="..." /=]` / `[= buttons =]`

A styled link that looks like a button. The first positional argument is the label; href is the URL; setting primary="true" swaps to the filled primary variant. Wrap one or more in [= buttons =] for an inline group.

[= buttons =]
[= button "Get started" href="/getting-started/" primary="true" /=]
[= button "Browse on GitHub" href="https://github.com/edadma/juicer" /=]
[= /buttons =]

Get started Browse on GitHub

Media

`[= figure "/img/foo.png" alt="..." caption="..." /=]`

A <figure> with an image and optional caption. First positional argument is the image URL. Named arguments: alt (accessibility text), caption (visible caption beneath the image).

[= figure "/img/diagram.svg" alt="Build pipeline diagram" caption="The juicer build pipeline" /=]

`[= github "owner/repo" /=]`

A clickable GitHub-repo card. One positional argument: the owner/repo slug. Renders the GitHub octocat icon plus the slug and the subtitle “GitHub repository”, linked to the repo.

[= github "edadma/juicer" /=]

edadma/juicer GitHub repository

`[= youtube "<video-id>" /=]`

A privacy-respecting iframe embed (youtube-nocookie.com). One positional argument: the YouTube video ID (the part after ?v= in the URL).

[= youtube "dQw4w9WgXcQ" /=]

Reference table

For quick lookup:

Shortcode	Pair / self	Args	Use for
`note`	pair	body	Aside, non-critical info
`tip`	pair	body	Suggestion, shortcut
`warning`	pair	body	Slow-down, foot-gun
`danger`	pair	body	Destructive / serious caveat
`steps`	pair	body w/ `## name` headings	Numbered steps
`tabs`	pair	one or more `tab` children	Tabbed content groups
`tab`	pair	`args[0]` = label	One tab inside `tabs`
`filetree`	pair	opaque body	Tree-style listings
`collapse`	pair	`args[0]` = summary text, body = content	`<details>` accordion
`kbd`	self-close	`args[0]` = key text	Keycap styling
`badge`	self-close	`args[0]` = label text	Pill / tag
`button`	self-close	`args[0]` = label, `href`, `primary`, `icon`	Styled link
`buttons`	pair	one or more `button` children	Button group
`figure`	self-close	`args[0]` = src, `alt`, `caption`	Image with caption
`github`	self-close	`args[0]` = `owner/repo`	GitHub repo card
`youtube`	self-close	`args[0]` = video ID	Privacy-friendly embed

Writing your own

Drop a template at <src>/shortcodes/<name>.html (or, in a theme, at <theme>/shortcodes/<name>.html). Inside it you have access to:

Variable	What
`.args`	Positional arguments — a list of strings
`.<name>`	Each named argument by its key
`.content`	The body, if the shortcode is invoked as a pair (else absent)

A minimal callout — template at <src>/shortcodes/callout.html:

<aside class="callout callout-{{ if .kind }}{{ .kind }}{{ else }}note{{ end }}">
  {{ markdownify .content }}
</aside>

Invoke it from markdown:

[= callout kind="success" =]
The build passed.
[= /callout =]

See Concepts → Shortcodes for the full syntax (quoting rules, escaping, paired vs self-closing).

Deferred shortcodes — the `[~ … ~]` delimiter

The classic [= … =] syntax runs before markdown parsing. That’s the right phase for shortcodes that emit markdown — a note callout producing <aside>…</aside> flows through the markdown parser correctly because the parser sees plain HTML in the input.

What that phase can’t do is reach .page.pages, .page.subsections, .section.*, or any field of .site.* — those records don’t exist yet during the markdown pass. Trying to render a shortcode template that says {{ for p <- .page.pages }} from [= … =] silently produces an empty list.

Juicer provides a second shortcode delimiter pair, [~ … ~], that runs after the page + section + site pipeline has finished. Inside a [~ shortcode the template sees:

Namespace	What’s available
`.page.*`	Full page record — title, summary, tags, pages, subsections, permalink, ancestors, prev / next, series, authors, …
`.site.*`	Full sitedata — `.site.posts`, `.site.pages`, `.site.tags`, `.site.authors`, `.site.now`, `.site.data`, …
`.args` / `.<key>` / `.content`	Same as the immediate pass

\[~ section-list /~]

{{ // shortcodes/section-list.html — must be invoked from the deferred
   // pass because it depends on .page.pages and .page.subsections.   }}
{{ if .page.pages }}
  <ul>{{ for p <- .page.pages }}<li><a href="{{ p.url }}">{{ p.title }}</a></li>{{ end }}</ul>
{{ end }}

Warning

Deferred shortcodes emit HTML, not markdown. They run on the already-rendered HTML body. If your template wants to render markdown output, pipe it through \{\{ markdownify ... \}\} explicitly.

Note

Same template registry. Both delimiter pairs look up templates in shortcodes/; the difference is purely when the shortcode runs and what context it sees. A template that uses neither .page nor .site works identically from either pass.

Shortcodes

2026-05-27T20:59:11.669095985Z

Shortcodes let authors invoke HTML templates from inside markdown without writing raw HTML. They use a bracket-equals syntax to avoid collisions with both markdown and squiggly:

[= shortcode-name positional "another arg" key="value" =]
optional body content
[= /shortcode-name =]

The body content is captured raw and exposed to the template as .content; positional args become .args (a list); named args become .<name>.

What juicerdocs ships

This very theme provides a useful set out of the box. Some examples:

Note

Note callouts like this one are written with [= note =] ... [= /note =]. We have tip, warning, and danger variants for different colors and icons.

Tip

Tip: if you author a lot of structured docs, the steps, tabs, and filetree shortcodes save you a lot of HTML.

Warning

Watch out: shortcodes are processed before markdown is parsed, so you can’t put a shortcode inside an indented code block.

Danger

Don’t do this: never expose a shortcode that takes user input straight into HTML. Run it through markdownify or escape it explicitly.

Tabs

The tabs / tab pair gives tabbed content. Useful for showing the same operation across platforms:

sbt 'juicerJVM/run build -s docs'

juicer build -s docs

node ./juicer-cli.js build -s docs

Steps

Use [= steps =] and write ## Step name headings inside; they’re auto-numbered:

Install Juicer

Clone the repo and verify with sbt 'juicerJVM/run --help'.

Make a site directory

Create site.toml, a content/ folder, and layouts/_default/.

Build & serve

Run sbt 'juicerJVM/run serve -s .' and open http://localhost:8080.

File trees

[= filetree =] is just monospace + indent guides — paste a tree-style listing inside:

my-site/
├── content/
│   ├── _index.md
│   └── about.md
├── layouts/
│   └── _default/
│       ├── file.html
│       └── folder.html
└── site.toml

Inline pieces

Press Ctrl+K to focus search. Tag your alpha pages with alpha so readers know.

Collapsible sections

Great for FAQs and “show me the long version”:

Why no JSON frontmatter?

The frontmatter format is YAML because YAML covers the use case fluently and supporting three formats (YAML, TOML, JSON) triples the surface area to keep correct. JSON inside markdown is also visually noisy.

What about TOML frontmatter?

Same answer. Site config is TOML; per-page metadata is YAML; it’s two formats but they live in different files, and the line is easy to remember.

Buttons

For landing pages and CTAs:

Get started Browse on GitHub

GitHub repo cards

[= github "owner/repo" /=] renders a clickable card:

edadma/juicer GitHub repository

YouTube embeds

[= youtube "<video-id>" /=] embeds a privacy-respecting iframe (youtube-nocookie.com).

Writing your own

Drop a template at <theme>/shortcodes/<name>.html (or <site>/shortcodes/<name>.html). Inside, you have access to:

Var	What
`.args`	Positional arguments — a list of strings
`.<name>`	Each named argument by its key
`.content`	The body, if the shortcode is delimited

Use the markdownify builtin to render the body as markdown:

<div class="my-callout">
  {{ markdownify .content }}
</div>

Two passes: immediate vs. deferred

Juicer runs shortcodes in two passes:

Immediate — the classic [= name =] delimiter. Runs before markdown parsing, so the shortcode’s output flows through the markdown parser. Best for shortcodes whose body is markdown (callouts, tabs, collapsible sections, …). The trade-off: this pass happens before the page + section + site pipeline assembles its data, so the shortcode template sees only .args, named keys, and .content — no .page or .site.
Deferred — the [~ name ~] delimiter. Runs after the pipeline finishes, on the already-rendered HTML body. The shortcode template can reach .page.title, .page.pages, .page.subsections, .section.*, and the full .site.*. Trade-off: the shortcode emits HTML directly (the markdown parser has already run), so pipe markdown through markdownify explicitly if you need it.

[= note =]Immediate — emits markdown that the parser then renders.[= /note =]

\[~ pagebadge /~]

{{ // shortcodes/pagebadge.html — accesses .page.title, so must be
   //  invoked from the deferred pass.                              }}
<span class="badge">{{ .page.title }}</span>

Both passes look up templates in the same shortcodes/ directory; the delimiter chooses which pass runs the template. A template that references neither .page nor .site can be invoked from either.

Démarrage rapide

2026-05-27T20:59:11.669095985Z

Ce guide construit le plus petit site juicer possible — une page, un gabarit — pour que vous voyiez les rouages avant d’ajouter quoi que ce soit de sophistiqué.

1. Créer un répertoire

mkdir my-site
cd my-site

2. Écrire `site.toml`

title   = "My Site"
author  = "You"
baseURL = "http://localhost:8080"

C’est le minimum. Juicer superpose ceci par-dessus la configuration de référence standard (les thèmes vont dans themes/, le contenu dans content/, etc.) — voir Configuration pour l’ensemble complet.

3. Écrire un gabarit

Juicer a besoin d’au moins un gabarit file (pour les pages individuelles) et d’un gabarit folder (pour les index de section). Ils vivent sous layouts/_default/ :

mkdir -p layouts/_default

layouts/_default/folder.html :

<!DOCTYPE html>
<html>
<head><title>{{ .page.title }} – {{ .site.title }}</title></head>
<body>
  <h1>{{ .page.title }}</h1>
  {{ .content }}
</body>
</html>

layouts/_default/file.html :

{{ partial 'folder' . }}

(Ce second gabarit délègue simplement à folder.html — pour un site d’une seule page, les deux gabarits peuvent produire le même rendu.)

4. Écrire du contenu

mkdir content

content/_index.md :

---
title: Hello
---

# It works!

This is **juicer**, rendering markdown.

5. Construire et servir

sbt 'juicerJVM/run serve -s . -d public'

Ouvrez http://localhost:8080. Vous devriez voir votre page.

Que s’est-il passé ?

Juicer a parcouru l’arborescence content/, repérant les fichiers markdown et analysant leur frontmatter YAML.
Pour chaque fichier de contenu, il a choisi un gabarit (folder.html pour _index.md, file.html pour le reste) et l’a rendu.
La sortie est allée dans public/ — _index.md est devenu public/index.html.
Un sitemap.xml et un search.json ont aussi été produits automatiquement.

Passez aux Concepts pour voir le rôle de chacune de ces pièces.

Quickstart

2026-05-27T20:59:11.669095985Z

This walkthrough builds the smallest possible juicer site — one page, one layout — so you can see the moving parts before adding anything fancy.

1. Make a directory

mkdir my-site
cd my-site

2. Write `site.toml`

title   = "My Site"
author  = "You"
baseURL = "http://localhost:8080"

That’s the minimum. Juicer overlays this on top of the standard baseline config (themes go in themes/, content in content/, etc.) — see Configuration for the full set.

3. Write a layout

Juicer needs at least a file layout (for individual pages) and a folder layout (for section indexes). They live under layouts/_default/:

mkdir -p layouts/_default

layouts/_default/folder.html:

<!DOCTYPE html>
<html>
<head><title>{{ .page.title }} – {{ .site.title }}</title></head>
<body>
  <h1>{{ .page.title }}</h1>
  {{ .content }}
</body>
</html>

layouts/_default/file.html:

{{ partial 'folder' . }}

(That second template just delegates to folder.html — for a one-page site, both layouts can render the same way.)

4. Write content

mkdir content

content/_index.md:

---
title: Hello
---

# It works!

This is **juicer**, rendering markdown.

5. Build & serve

sbt 'juicerJVM/run serve -s . -d public'

Open http://localhost:8080. You should see your page.

What just happened?

Juicer walked the content/ tree, finding markdown files and parsing their YAML frontmatter.
For each content file it picked a template (folder.html for _index.md, file.html for everything else) and rendered it.
The output went to public/ — _index.md became public/index.html.
A sitemap.xml and search.json were also emitted automatically.

Move on to Concepts to see what each of those pieces does.

Markdown

2026-05-27T20:59:11.669095985Z

Juicer is built on io.github.edadma/markdown — a full CommonMark 0.31.2 parser. Every page gets the same defaults; this section walks through what’s enabled and how each piece looks rendered.

CommonMark — the basics

The whole CommonMark spec works without any opt-in. Headings, paragraphs, lists, blockquotes, code spans, fenced code blocks, links, images.

# Heading 1
## Heading 2
### Heading 3

A *paragraph* with **strong** emphasis and `inline code`.

> A blockquote.
> Lazy continuation works too.

1. Ordered list
2. With items
   1. Nested
3. Continues

[Link text](https://juicer.build/) and ![alt](https://placehold.co/40x40 ""title"").

GFM extras

The juicer config opts into every GitHub-Flavored-Markdown extension the parser supports:

Tables

| Tier | What's in it |
|------|--------------|
| 1 | site.pages, page URLs, drafts, sitemap, summary |
| 2 | live reload, render hooks, RSS, sections, i18n, themes |

renders as

Tier	What’s in it
1	site.pages, page URLs, drafts, sitemap, summary
2	live reload, render hooks, RSS, sections, i18n, themes

Strikethrough

~~old behavior~~ renders as ~~old behavior~~.

Task lists

- [x] Tier 1 — done
- [x] Section list pages
- [ ] i18n
- [ ] Render hooks

renders as

Tier 1 — done
Section list pages
i18n
Render hooks

Footnotes

You can drop a footnote reference¹ mid-paragraph and define it elsewhere.

Auto-linking

Bare URLs like https://juicer.build/ are recognized and turned into clickable links without explicit […](…) syntax.

Smart punctuation

Straight quotes get curly: “hello” becomes “hello”, and -- / --- become en/em dashes — like that.

Callouts (admonitions)

GFM-style callouts — > [!NOTE] / > [!TIP] / > [!WARNING] / > [!IMPORTANT] / > [!CAUTION] — render as styled blocks. Markdown source:

> [!NOTE]
> This is the parser's built-in callout. It produces a styled `<div>` with
> the type baked into a class name.

Note

This is the parser’s built-in callout. It produces a styled <div> with the type baked into a class name.

Warning

The shortcode-based callouts ([= note =]…[= /note =]) and the markdown-native callouts above produce different HTML. The shortcodes are themed by juicerdocs directly; the native ones are styled by Tailwind’s typography defaults.

Auto heading IDs

Every <hN> gets an id derived from its plain-text content. The TOC reads this back; deep links work out of the box.

## Hello, world!

becomes <h2 id="hello-world">Hello, world!</h2> — see your URL bar’s hash if you click any heading on this page.

Definition lists

Apple
: A round fruit, typically red or green.

Orange
: A citrus fruit. Also a color.

renders as

Apple: A round fruit, typically red or green.
Orange: A citrus fruit. Also a color.

Emoji

:smile: becomes 😄, :rocket: becomes 🚀, :tada: becomes 🎉 — the unicode codepoints, not images.

Code blocks with language

<!DOCTYPE html>
<html>
<head><title>{{ .page.title }}</title></head>
<body>
  <main class="prose">{{ .content }}</main>
</body>
</html>

// Squiggly's Go-template-style syntax compiles down to a small AST.
case class TemplateRenderer(
  partials:   TemplateLoader = _ => None,
  data:       Map[String, Any] = Map.empty,
  functions:  Map[String, TemplateFunction] = Map.empty,
)

# A code block tagged `bash` gets a "BASH" badge and copy button.# A code block tagged `bash` gets a "BASH" badge and copy button.
sbt 'juicerJVM/run serve -s docs -L'

The juicerdocs theme adds a copy-to-clipboard button on every <pre> — hover to see it.

This is the footnote body. Multiple paragraphs supported. ↩

Installation

2026-05-27T20:59:11.669095985Z

Depuis les sources (recommandé pour l’instant)

Juicer est publié depuis un dépôt unique à l’adresse https://github.com/edadma/juicer. En attendant la mise en place des distributions binaires, le plus simple est de cloner le dépôt et de l’exécuter avec sbt.

git clone https://github.com/edadma/juicer.git
cd juicer
sbt 'juicerJVM/run --help'

Vous verrez la bannière d’aide. Si sbt affiche autre chose que cette aide, consultez la page Dépannage.

Dépendance sbt (utilisation comme bibliothèque)

Juicer est surtout une application — l’interface en ligne de commande couvre les besoins de la plupart des utilisateurs — mais le pipeline de construction est aussi exposé comme bibliothèque. Ajoutez-le à votre build.sbt :

libraryDependencies += "io.github.edadma" %%% "juicer" % "0.2.0"

La forme %%% choisit le bon artefact selon la plateforme Scala que vous utilisez (juicerJVM, juicerJS, juicerNative).

Prérequis

Scala 3.8.3 — juicer est exclusivement en Scala 3. Aucun rétroportage vers Scala 2 n’est prévu.
sbt 1.12.x — les versions antérieures peuvent fonctionner ; non testées.
JVM 17+ — pour la cible JVM. Scala.js requiert Node 20+ ; Scala Native requiert Clang.

Vérifier l’installation

Le test de fumée consiste à lancer juicer build sur le répertoire docs/demos/minimal du dépôt :

sbt 'juicerJVM/run build -s docs/demos/minimal'
ls docs/demos/minimal/public

Vous devriez voir un index.html et une copie de static/.

Installation

2026-05-27T20:59:11.669095985Z

From source (recommended for now)

Juicer is published from a single repo at https://github.com/edadma/juicer. Until binary releases are wired up, the simplest path is to clone and run with sbt.

git clone https://github.com/edadma/juicer.git
cd juicer
sbt 'juicerJVM/run --help'

You’ll see the usage banner. If sbt prints anything other than the help output, see Troubleshooting.

sbt dependency (library use)

Juicer is mostly an application — the CLI does what most users need — but the build pipeline is exposed as a library too. Add it to your build.sbt:

libraryDependencies += "io.github.edadma" %%% "juicer" % "0.2.0"

The %%% form picks the right artifact for whichever Scala platform you’re on (juicerJVM, juicerJS, juicerNative).

Requirements

Scala 3.8.3 — juicer is Scala-3 only. No Scala 2 backport planned.
sbt 1.12.x — earlier versions might work; not tested.
JVM 17+ — for the JVM target. Scala.js needs Node 20+; Scala Native needs Clang.

Verifying the install

The smoke test is juicer build against the docs/demos/minimal directory in the repo:

sbt 'juicerJVM/run build -s docs/demos/minimal'
ls docs/demos/minimal/public

You should see an index.html and a static/ mirror.

Internationalization (i18n)

2026-05-27T20:59:11.669095985Z

A juicer site can ship the same content in several languages. Each language gets its own content tree, its own URL space, and its own navigation; pages that exist in more than one language cross-link automatically, and the UI chrome (button labels, “Previous”/”Next”, search placeholder, …) is translated through dictionaries. Single-language sites pay nothing for any of this — none of it activates until you declare a languages list.

This page documents every moving part. The juicer.build docs you’re reading are themselves bilingual (English + French), so it’s all dogfooded.

Turning it on

Declare the languages and the default in site.toml:

languages             = ["en", "fr"]
defaultLanguage       = "en"
defaultLanguageInRoot = true

languages — the list of language codes you publish. An empty or absent list means a single-language site (no behavior change at all).
defaultLanguage — the fallback language. A missing translation (of a page or of a UI string) falls back to this language. Defaults to the first entry of languages; on a site with no languages it defaults to "en".
defaultLanguageInRoot — when true, the default language is served at the site root with no /<code>/ prefix, and only the other languages get a prefix. When false (the default), every language is prefixed, including the default.

Content layout

Once languages is set, content lives one directory deeper — under content/<lang>/:

content/
├── en/
│   ├── _index.md
│   └── getting-started/
│       ├── _index.md
│       └── installation.md
└── fr/
    ├── _index.md
    └── getting-started/
        ├── _index.md
        └── installation.md

A page’s language is the first path segment under content/. Two pages that share the same path after the language segment — en/getting-started/installation.md and fr/getting-started/installation.md — are translations of each other. You don’t have to translate everything: a page that exists in only one language simply has no translations, and nothing links to a missing one.

URLs

defaultLanguageInRoot decides the shape of the URL space. With the config above (en default, in root):

Page	URL
`content/en/getting-started/installation.md`	`/getting-started/installation/`
`content/fr/getting-started/installation.md`	`/fr/getting-started/installation/`

The default language keeps the clean, prefix-free URLs — important when you add a second language to an existing site and don’t want to break inbound links. Set defaultLanguageInRoot = false to prefix every language symmetrically (/en/… and /fr/…).

Tip

Building language-prefixed links by hand is error-prone. Use the relLangURL / absLangURL helpers — they apply the right prefix for you.

Per-page language data

Every page exposes its language and its translations on the rendering context:

.page.lang — the page’s language code ("" on a single-language site).
.page.translations — the list of the other-language versions of this page. Each entry carries lang, title, and url. Empty when the page has no translation.
.page.languages — every configured language (in declared order), each with lang, a url to switch to, and a current flag. The url is the page’s own URL for the current language, its translation where one exists, and that language’s home otherwise — so the entry is never missing, even on an untranslated page. Empty for single-language sites.

.page.languages is what a full language switcher iterates — it always offers every language, the way Starlight or Docusaurus do:

{{ if .page.languages }}
<details aria-label="{{ i18n .page.lang 'aria_language' }}">
  <summary>{{ i18n .page.lang 'langname' }}</summary>
  {{ for l <- .page.languages }}
  <a href="{{ l.url }}" hreflang="{{ l.lang }}"{{ if l.current }} aria-current="true"{{ end }}>
    {{ i18n l.lang 'langname' }}
  </a>
  {{ end }}
</details>
{{ end }}

The juicerdocs theme ships this as a dropdown in its topbar. (Use .page.translations instead when you want a switcher that lists only the translations that exist — handy for an inline two-language toggle.)

UI strings: the `i18n` helper

Chrome text — button labels, pager arrows, the search placeholder — is looked up by key instead of hard-coded, so it can be translated:

{{ i18n .page.lang 'nav_prev' }}

i18n takes a language code and a key. Lookup falls back in this order:

the requested language’s dictionary,
the defaultLanguage‘s dictionary,
the literal key (so a missing string is visible, not blank).

Because the language is the first argument, {{ i18n t.lang 'langname' }} looks up a key in another language’s table — which is how the switcher above shows each language’s own name.

Dictionaries

Strings come from i18n/<lang>.toml files — flat key = "value" tables:

# i18n/fr.toml# i18n/fr.toml
nav_prev = "Précédent"
nav_next = "Suivant"

Dictionaries are collected from two places and merged:

the active theme(s) — <theme>/i18n/<lang>.toml
your site — <src>/i18n/<lang>.toml

with the same precedence as every other themed resource: your site wins over a theme, and an earlier theme in the lookup chain wins over a later (inherited) one. The merge is per-language and per-key, so a theme can ship a complete English chrome dictionary while your site adds only the handful of keys it overrides — or the extra languages it publishes.

Note

This is why a theme like juicerdocs renders English chrome with zero configuration: it ships its own i18n/en.toml. To translate the chrome, drop an i18n/fr.toml into your site (or override individual keys); you never have to fork the theme.

The sidebar walks .site.root.subsections. On a multilingual site, .site.root is scoped to the current page’s language — it resolves to that language’s <lang>/_index.md. So a French page gets the French section tree, an English page the English one, with no per-theme work. A section that hasn’t been translated yet simply doesn’t appear in that language’s navigation.

.page.prev / .page.next — the sequential pager — are scoped the same way: navigation walks the current language’s reading order only, so the last English page never points “next” into French.

Language-aware URLs

relLangURL and absLangURL are the language-aware companions of relURL / absURL. They take the language as the first argument and prefix the path with that language’s URL segment:

<a href="{{ relLangURL .page.lang '/getting-started/' }}">…</a>

On an English page (default, in root) this yields /getting-started/; on a French page, /fr/getting-started/. Use these for fixed links in shared layouts — like a hero call-to-action — so they stay within the reader’s language. (.page.url and .page.translations[].url are already language-correct; you only need relLangURL for paths you write by hand.)

Sitemap & hreflang

When a site is multilingual, sitemap.xml automatically gains <xhtml:link rel="alternate" hreflang="…"> entries linking each page to its translations, so search engines serve the right language. Single-language sites get a plain sitemap with no hreflang noise. No configuration required either way.

What stays zero-config

Warning

Everything on this page is dormant until languages is set. A site with no languages list builds byte-for-byte as it did before i18n existed: .page.lang is "", .page.translations is empty, the sitemap has no hreflang, content stays at content/ (not content/<lang>/), and the i18n helper still resolves theme dictionaries through the default-language fallback so themed chrome renders in English.

Frontmatter

2026-05-27T20:59:11.669095985Z

The YAML block at the top of every content file. Juicer reads a fixed set of keys; everything else passes through to templates as .page.<key>. This page catalogues the engine-level keys (read by juicer itself) and points at the theme-specific keys (read by one bundled theme each, documented under that theme’s section).

---
title: Hello, World
date: 2024-03-12
tags: [intro, meta]
summary: A short description used in list pages and OpenGraph tags.
draft: false
---

The body of the page goes here.

Engine-level keys

These are read by juicer itself. Every bundled theme can rely on them being present (or normalized to a sensible default) on every page record in templates.

Page identity

Key	Type	What
`title`	`String`	Page title. Falls back to the first heading in the body, then to the filename when both are absent.
`summary`	`String`	Explicit page summary. Auto-derived from a `<!--more-->` marker or the first paragraph (capped at 30 words) when absent.
`layout`	`String`	Override the default layout. For a single page, `file` is the default; for `_index.md`, `folder`. Setting `layout: home` (etc.) renders the page through `_default/home.html` instead.

Publishing & visibility

Key	Type	What
`date`	ISO-8601 string or YAML date	Publication date. Three input shapes recognized: `2024-03-12T10:30:00Z` (with offset), `2024-03-12T10:30:00` (local, assumed UTC), `2024-03-12` (date only, midnight UTC).
`draft`	`Boolean`	When `true`, the page is excluded from the build unless `--drafts` is passed. Drafts are invisible to TOC, sitemap, search index, and section listings.
`static`	`Boolean`	Mark a page as non-post even though it lives in a posts-style section. Excluded from `.site.posts`, `.site.pagesByYear`, and tag/author archive listings. Used for about/colophon/contact pages on a blog.

---
title: Big announcement
date: 2024-12-25T09:00:00Z
draft: false
---

---
title: About this site
static: true
---

Note

The date rule: only pages with explicit date: frontmatter are included in .site.posts, .site.pagesByYear, and dateArchives output. When date: is absent, juicer falls back to the source file’s filesystem mtime for sort order — it’s a deliberate split: silently sorting by mtime is convenient; silently treating every page as a dated post is not.

Taxonomy

Key	Type	What
`tags`	`String` or `[String]`	Tags for the post. A single string is auto-wrapped to a one-element list. Generates `/tags/<slug>/` archive pages (gated on a `tag-page.html` layout existing).
`categories`	`String` or `[String]`	A second taxonomy axis. Same slugification and archive pattern but at `/categories/<slug>/`. Use one, the other, or both.

---
title: Functional programming in Scala 3
tags: [scala, functional, language]
categories: tutorials
---

Slugification: lowercase → ASCII-fold (café → cafe) → runs of non-alphanumerics → -. So "Functional Programming" becomes functional-programming.

Ordering

Key	Type	What
`weight`	`Int`	Explicit sort position within a section. Lower weights sort first. Pages without a weight come after weighted pages.
`sortBy`	`String`	(on section `_index.md`) Override the site-wide `sortBy`. One of `"date"`, `"title"`, `"weight"`.
`paginate`	`Int`	(on section `_index.md`) Override the site-wide `paginate` slice size.

Authors

Key	Type	What
`author`	`String`	Single author ID — references an `id` in `[[authors]]` in `site.toml`. Singular shorthand for `authors: [<id>]`.
`authors`	`[String]`	Multiple author IDs. When both `author:` and `authors:` are absent, `.page.author` is `null` and `.page.authors` is the empty list.

---
title: A co-authored post
authors: [ed, alice]
---

Author IDs that don’t match any [[authors]].id fall through to a stub {id: "<typo>"} record so templates don’t fail; the per-author archive is empty in that case.

Series

Key	Type	What
`series`	`String`	Series name. Pages with the same `series:` value (case-sensitive) form an ordered group.
`seriesOrder`	`Int`	Position within the series. Pages without `seriesOrder` sort by `date` ascending after the ordered pages.

---
title: OS Internals, Part 1
series: OS Internals
seriesOrder: 1
---

Aliases (redirects)

Key	Type	What
`aliases`	`String` or `[String]`	Old URLs that should redirect to this page. Each generates a static HTML stub at the old URL with a `<meta http-equiv="refresh">` to the canonical URL.

---
title: Setting up a Scala 3 project
aliases:
  - /old-blog-name/setting-up-scala/
  - /2023/setting-up/
---

Each alias must include both leading and trailing slashes: /old-url/, not old-url or /old-url.

Events

These keys are read on pages in the eventsSection (default events) — the section juicer treats as the source of calendar events.

Key	Type	What
`recurring`	`String`	`"weekly"` for a weekly recurring event. The event expands onto every matching weekday in `.site.calendar`.
`recurringDay`	`String`	Day name (`"Monday"`, …, `"Sunday"`) for the recurrence. Defaults to the start date’s day of week when absent.

---
title: Tuesday Coffee
date: 2024-03-12T09:00:00
recurring: weekly
recurringDay: Tuesday
---

Photos

Key	Type	What
`photos`	`[String]` or `[{src, caption?, alt?}]`	Photos for the page. Aggregated site-wide into `.site.photos` (sorted by page date desc).

---
title: Picnic in the park
date: 2024-06-12
photos:
  - "/img/picnic-01.jpg"
  - { src: "/img/picnic-02.jpg", caption: "The pie table", alt: "A long folding table loaded with summer pies" }
---

These override defaults that the ogTags template helper otherwise computes from .page.title, .page.summary, .page.image, etc.

Key	Type	What
`description`	`String`	Fallback for the OpenGraph description when `summary` isn’t appropriate.
`image`	`String`	Default page image — used by `og:image` and as a card thumbnail by themes that show one.
`ogTitle`	`String`	Override the page title in OpenGraph and Twitter card tags.
`ogDescription`	`String`	Override the description in OpenGraph and Twitter card tags.
`ogImage`	`String`	Override the image in OpenGraph and Twitter card tags.

---
title: A long, descriptive, SEO-targeted post title
summary: A long summary tuned for the page's own list rendering.
ogTitle: A short, punchy title for social cards
ogDescription: A different summary that fits in a card preview.
ogImage: /img/posts/short-title-card.png
---

Computed (not set by you)

These fields appear on .page.<key> in templates but are not read from frontmatter — they’re set by juicer during build:

Key	What
`permalink`	Canonical site-relative URL — `/posts/the-post/`.
`relPermalink`	Same as `permalink` (Hugo parity).
`url`	Same as `permalink`.
`dateISO`	`2024-03-12T00:00:00Z` (only when `date:` is set).
`dateLong`	`March 12, 2024` (only when `date:` is set).
`dateShort`	`2024-03-12` (only when `date:` is set).
`slug`	URL stem (last path segment).
`wordCount`	Rendered-body word count.
`readingTime`	`ceil(wordCount / 200)` minutes, floor 1 for non-empty pages.
`isSection`	`true` for `_index.md` pages.
`parent`, `ancestors`	Section’s `_index` record, then root → parent chain.
`next`, `prev`	Sibling navigation by section page order.
`pages`, `subsections`	(`_index.md` only) Children of the section.
`series` (block)	`{name, pages, prev, next, index, total}` — populated when the page declares a `series:`.

The full .page reference, including these, lives in Template data → .page.

Cascade — inherited frontmatter

A section’s _index.md may declare a cascade: map; every key inside it is inherited by every descendant page that doesn’t set the same key in its own frontmatter. This lets a section establish defaults — author, layout, license, custom flags — without repeating them on every page.

# content/posts/_index.md
---
title: Posts
cascade:
  author: ed
  tone: editorial
  license: CC-BY
---

Every page under /posts/ now picks up .page.author = "ed", .page.tone = "editorial", .page.license = "CC-BY" automatically. A specific post can override any of them:

# content/posts/guest-piece.md
---
title: Guest piece
author: alice    # overrides the cascaded "ed"
---

Resolution rules

The page’s own frontmatter wins over any cascade value.
Nearer ancestors win over farther ancestors. Root _index.md‘s cascade is the weakest; a deeply-nested section’s cascade overrides everything above it.
A section’s cascade does NOT apply to its own _index.md. Cascade declares defaults for descendants, not for the declaring page itself. The section’s own _index.md only inherits cascades from sections above it.
Sections inherit cascade from ancestor sections. A nested section’s _index.md picks up cascades from every ancestor section, then merges its own (own wins).
Missing / empty cascade is a no-op. Pages without any cascade in their ancestor chain see exactly the frontmatter they wrote.

What can be cascaded

Any frontmatter key the engine or a theme reads. Useful candidates:

author / authors — section-wide attribution.
layout — force every page in a section through a specific template (e.g. layout: project across a portfolio section).
tags / categories — section-wide taxonomy; pages add their own and override the default list if needed.
Custom keys consumed by your theme — tone, region, license, noindex, …

Less useful (but legal) to cascade: date, title, summary — these are intrinsically per-page and rarely benefit from a default. There’s no enforcement; cascade is a blanket mechanism and the author is responsible for picking keys that make sense to inherit.

Theme-specific frontmatter

The bundled themes recognize their own frontmatter keys on top of the engine surface. Those are documented per theme:

Theme	What it reads on top
juicerblog	`static`, `layout: home`/`archive`, `series`
juicerstudy	`toc`, `summary` (as lead), `minutes`
juicerlanding	`layout: home`, `summary` (as subtitle), `lang`
juicerportfolio	`layout: project`, `year`, `tagline`, `role`, `client`, `tools`, `category`, `hero`, `heroAlt`, `caption`, `gallery`, `link`
juicerdocs	Engine-level keys only — no theme-specific frontmatter.

Any other key

Anything you write in frontmatter that juicer doesn’t read is exposed on .page.<key> for templates to use. So adding a custom field is just a matter of writing it:

---
title: Cherry pie
yield: 8 servings
prepTime: 45 min
cookTime: 1 h 10 min
---

<dl>
  <dt>Yield</dt><dd>{{ .page.yield }}</dd>
  <dt>Prep time</dt><dd>{{ .page.prepTime }}</dd>
  <dt>Cook time</dt><dd>{{ .page.cookTime }}</dd>
</dl>

Deploy to GitHub Pages

2026-05-27T20:59:11.669095985Z

This recipe is the same flow juicer.build itself uses (and the same flow used by squiggly’s docs). It builds your site with juicer inside a GitHub Actions runner and pushes the result to GitHub Pages — no third-party build service, no separate deploy step, no manual gh-pages branch management.

Note

This page assumes you already have a working juicer site building locally — that sbt 'juicerJVM/run build -s docs' produces a tree of HTML you’re happy with. If you haven’t gotten there yet, work through Quickstart first.

The shape of the deploy

push to `stable`  ──▶  build job  ──▶  deploy job  ──▶  https://<owner>.github.io/<repo>/
                       (sbt build)     (actions/deploy-pages)

Two GitHub Actions jobs, one workflow file. The build job runs juicer build and uploads the rendered site as a Pages artifact; the deploy job, gated on the stable branch, takes that artifact and publishes it to the github-pages environment. Pushes to other branches still run build (a sanity check), but the artifact is uploaded as a downloadable file rather than published.

Prerequisites

A git repo on GitHub with your site source in it

Anywhere under the repo root is fine — the workflow assumes docs/ (so sbt 'juicerJVM/run build -s docs' works). Adjust the -s path if your source lives somewhere else.

A long-lived branch named `stable` for production deploys

The workflow only deploys on pushes to stable. Use a separate dev (or main) branch for in-progress work, and merge into stable when you want to publish. This stops every git push from triggering a deploy.

If you’d rather deploy from main directly, swap stable → main in the workflow’s on.push.branches and the deploy job’s if: guard.

GitHub Pages enabled with “GitHub Actions” as the source

In your repository: Settings → Pages → Source: “GitHub Actions”. Setting this to “Deploy from a branch” instead won’t work — the workflow uses the Actions-based deploy path.

The workflow file

Drop this at .github/workflows/docs.yml:

# Build & deploy <https://<owner>.github.io/<repo>/>.
#
#   Push to `stable`       → builds and deploys to GitHub Pages.
#   PR targeting `stable`  → builds (sanity check), no deploy.
#   workflow_dispatch      → manual trigger from the Actions tab.

name: Docs

on:
  push:
    branches: ["stable"]
  pull_request:
    branches: ["stable"]
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: "docs-${{ github.ref }}"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "17"

      # actions/setup-java does NOT ship sbt. Install it via the
      # official sbt-maintained action.
      - name: Set up sbt
        uses: sbt/setup-sbt@v1

      - name: Cache sbt
        uses: actions/cache@v4
        with:
          path: |
            ~/.sbt
            ~/.cache/coursier
          key: ${{ runner.os }}-sbt-${{ hashFiles('**/build.sbt', '**/project/**') }}
          restore-keys: ${{ runner.os }}-sbt-

      - name: Build docs site
        run: sbt 'juicerJVM/run build -s docs -d _site -b https://<owner>.github.io/<repo>/'

      - name: Upload site artifact
        uses: actions/upload-artifact@v4
        with:
          name: docs-site
          path: _site

      - name: Upload Pages artifact
        if: github.ref == 'refs/heads/stable'
        uses: actions/upload-pages-artifact@v3
        with:
          path: _site

  deploy:
    if: github.ref == 'refs/heads/stable'
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Substitute <owner> and <repo> in the Build docs site step’s -b flag (e.g. -b https://edadma.github.io/juicer/). Getting this wrong is the single most common deploy bug — every link juicer emits is computed against baseURL, so a stale value sends visitors to the wrong host.

Warning

The trailing slash matters. baseURL = "https://example.com/repo" and baseURL = "https://example.com/repo/" produce different URLs in some edge cases (notably the sitemap and og:url tags). Always include the trailing slash.

What each step does

Checkout

Pulls the repo onto the runner. Default checkout depth is fine — juicer doesn’t need git history for anything.

Set up JDK 17

Juicer is Scala 3 and runs on JVM 17+. temurin is the standard free OpenJDK distribution.

Set up sbt

actions/setup-java only installs the JDK. sbt is a separate tool and ships via sbt/setup-sbt@v1. This step is non-obvious; copy it verbatim.

Cache sbt

The slow part of a cold juicer build is sbt fetching its plugins and dependencies from Maven Central. Caching ~/.sbt and ~/.cache/coursier keyed on build.sbt + project/ files cuts a typical build from ~3 minutes to ~30 seconds.

Build docs site

The actual juicer call. -s docs points at the source directory; -d _site puts the output where the next step expects it; -b sets the absolute base URL for permalinks, sitemaps, and og:url tags.

Upload site artifact

Uploads the rendered site as a regular GitHub Actions artifact named docs-site. PR builds — which don’t deploy — still produce this, so you can download it from the Actions tab and inspect the output before merging.

Upload Pages artifact

The Pages-specific upload, gated on stable. Pages artifacts are distinct from regular artifacts — they go through a separate TAR-based pipeline that the deploy-pages action consumes.

Deploy to GitHub Pages

Reads the Pages artifact and publishes it to the github-pages environment, also gated on stable. The deployment URL surfaces in the Actions UI and in the Pages settings page.

Project-pages vs user/org pages

There are two GitHub Pages URL shapes, and the -b flag has to match the one you’re using:

Site type	Repository naming	`baseURL`
Project pages	any name (e.g. `juicer`)	`https://<owner>.github.io/<repo>/`
User pages	`<owner>.github.io`	`https://<owner>.github.io/`
Org pages	`<org>.github.io`	`https://<org>.github.io/`

Project pages have a path prefix (/<repo>/); user/org pages don’t. Get this wrong and every internal link 404s. Run juicer config -s docs -b <your-url> locally to print the resolved baseURL and double-check before you push.

Custom domain (`juicer.build`-style)

To deploy to a domain you own — docs.example.com, example.com, or anything else — extend the workflow with two small things:

Add a `CNAME` file write to the workflow

After the build step, before the Pages upload, drop a line:

- name: Write CNAME
  if: github.ref == 'refs/heads/stable'
  run: echo 'docs.example.com' > _site/CNAME

GitHub Pages reads CNAME out of the deployed artifact and sets the custom-domain binding from it. Without this file, GitHub keeps serving the page at <owner>.github.io/<repo>/.

Point DNS at GitHub Pages

For a subdomain (docs.example.com), set a CNAME record:

Host	Type	Value
`docs`	CNAME	`<owner>.github.io`

For an apex domain (example.com), set four A records (and optionally four AAAA for IPv6 — GitHub publishes the v6 set alongside the v4):

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Enable HTTPS

In the repo: Settings → Pages → Custom domain, fill in the domain, wait for the DNS check to go green (a few seconds to a few minutes depending on TTL). Then GitHub auto-issues a Let’s Encrypt cert (another few minutes). Finally tick Enforce HTTPS.

Set `baseURL` to the custom domain

Update the Build docs site step’s -b flag to https://docs.example.com/ (or whatever your domain is). On project repos with a custom domain, the path prefix is gone — your URL no longer has /<repo>/ in it.

Pull-request previews

The workflow as written uploads docs-site as a regular artifact on every PR — you can download it from the Actions tab and serve it locally:

unzip docs-site.zip -d /tmp/preview
cd /tmp/preview
python3 -m http.server 8000

For true per-PR preview URLs (each branch gets its own <branch>.<project>.pages.dev), swap GitHub Pages for Cloudflare Pages: connect the repo to a Cloudflare Pages project, set the build command to sbt 'juicerJVM/run build -s docs -d _site -b $CF_PAGES_URL', and the output directory to _site. Cloudflare assigns preview URLs automatically; production maps to your custom domain.

Troubleshooting

Workflow fails on `Upload Pages artifact` with “Pages is not enabled”

You haven’t enabled Pages yet. Settings → Pages → Source: “GitHub Actions”. The first deploy after enabling can take a minute or two for the environment to register.

Site builds but every link 404s

baseURL is wrong. Run sbt 'juicerJVM/run config -s docs -b <your-url>' locally and inspect the baseURL value — it should match what visitors type in the browser. Common mistakes: missing trailing slash, wrong /<repo>/ prefix for user-page deploys.

CSS and JS load, but images 404

The image paths in your markdown are absolute (/img/x.png) but your site is under a project path prefix (/<repo>/). Two fixes:

Use the relURL template helper on every link/image emitted by layouts — <img src="{{ relURL '/img/x.png' }}">.
Inside markdown body content, write paths without the leading slash (img/x.png) and let the markdown renderer compute them relative to the page.

Build succeeds locally but fails in CI

Two usual suspects:

sbt version: ensure your local project/build.properties pins an sbt version that the runner’s sbt/setup-sbt@v1 knows about. Latest 1.x.x is always fine.
JDK version: CI uses java-version: "17". If you’ve been building locally with JDK 21, check the build for any Java 21-only API usage and pin your local JDK to 17 for parity.

Deploys hang at “Deploy to GitHub Pages”

Concurrent deploys queue. Check Actions → recent runs — an earlier run is probably still finishing. The concurrency: block prevents stacked deploys from the same ref, but cross-ref deploys (e.g. stable + a tag push at the same time) wait their turn.

Demo site

2026-05-27T20:59:11.669095985Z

This page is the placeholder for the live juicerwiki demo. When the docs site is built and deployed, this URL serves the actual demo rendered with the juicerwiki theme — a separate juicer build from docs/demos/juicerwiki/ is dropped on top of the docs render at the same path.

What the demo exercises

“Field Notes” — a small wiki of computing notes that link to each other:

Backlinks panel at the bottom of every note. Open Zettelkasten and see who points there.
Tag cloud on the home page sized by usage count.
Tag archives at /tags/<slug>/.
Search modal — open with Cmd/Ctrl-K, type any substring.

Preview locally

sbt 'juicerJVM/run serve -s docs/demos/juicerwiki -L'

The -L flag enables live reload — touch any markdown file under docs/demos/juicerwiki/content/ and the open browser tabs reload via SSE.

Use it as a template

Copy docs/demos/juicerwiki/ into your own project as a starting point. Drop notes into content/ as flat markdown files; link them to each other with regular markdown [text](/slug/) syntax; let the backlinks index do the rest.

Demo site

2026-05-27T20:59:11.669095985Z

This page is the placeholder for the live juicerstudy demo. When the docs site is built and deployed, this URL serves the actual demo rendered with the juicerstudy theme — a separate juicer build from docs/demos/juicerstudy/ is dropped on top of the docs render at the same path. See bin/build-demos.sh for the orchestration.

What the demo exercises

A fictional reader’s notebook (“Marginalia”) populated with two short studies and the conventions a long-form prose site actually needs:

Two authored sections — On Reading and On Time — each with an _index.md that reads as editorial introduction, not as an auto-cataloged TOC.
Nested subsections — on-reading/practices/ to exercise the arbitrarily-deep section tree.
KaTeX math — both inline ( $10^9$ ) and display ($$ … $$) forms; juicerstudy.math = true in site.toml opts in.
Right-rail “On this page” TOC on the pages that set toc: true in frontmatter.
Heading-shift = 0 — page <h1> comes from frontmatter title, markdown bodies start at ##.
Slate-and-amber palette retuned via [juicerstudy] overrides — intentionally distinct from juicerdocs’s defaults so the two themes don’t read as the same site.
Read-time hints — minutes: frontmatter on each page.

Preview locally

sbt 'juicerJVM/run serve -s docs/demos/juicerstudy -L'

The -L flag enables live reload — touch any markdown file under docs/demos/juicerstudy/content/ and the open browser tabs reload via SSE.

Use it as a template

Copy docs/demos/juicerstudy/ into your own project as a starting point. Replace the prose, retune the palette under [juicerstudy], turn math off if you don’t need it. The companion Configuration reference catalogues every site.toml key, palette / typography / sizing token, and per-page frontmatter knob the theme reads.

Demo site

2026-05-27T20:59:11.669095985Z

This page is the placeholder for the live juicerportfolio demo. When the docs site is built and deployed, this URL serves the actual demo rendered with the juicerportfolio theme — a separate juicer build from docs/demos/juicerportfolio/ is dropped on top of the docs render at the same path. See bin/build-demos.sh for the orchestration.

What the demo exercises

A fictional studio — “Atelier Hahn”, an industrial-design studio run by Mira Hahn in Lisbon — with content exercising every juicerportfolio layout:

Project grid on the home page — 2-up cards, each a hero image
- title + tagline.
Filter chips above the grid driven by [[workCategories]] in site.toml. Click a chip → JS toggles a data-active-filter attribute on the grid root. No framework, no router, no fetch.
Per-project pages with hero image, sticky right-side meta sidebar (year / role / client / materials / external link), writeup body, optional [[gallery]] figure grid, prev/next nav, “All work” back link.
Materials chips — tools: [...] in frontmatter renders as small monospace-tabular chips in the meta sidebar.
/work/_index.md archive — folder.html doubles as a full text-list of every project, complementary to the home grid’s curated image-led view.
Prose pages — /about/, /contact/, /cv/, /press/ — using the generic file.html layout with a constrained measure for comfortable reading.

Preview locally

sbt 'juicerJVM/run serve -s docs/demos/juicerportfolio -L'

The -L flag enables live reload — touch any markdown file under docs/demos/juicerportfolio/content/ and the open browser tabs reload via SSE.

Use it as a template

Copy docs/demos/juicerportfolio/ into your own project as a starting point. Drop your hero images into static/img/, write project pages in content/work/, retune [[workCategories]] and the palette under [juicerportfolio]. The companion Configuration reference catalogues every site.toml key, palette token, and per-project frontmatter knob the theme reads.

Demo site

2026-05-27T20:59:11.669095985Z

This page is the placeholder for the live juicerpodcast demo. When the docs site is built and deployed, this URL serves the actual demo rendered with juicerpodcast.

What the demo exercises

“Echo Chamber” — a fictional weekly long-form interview show with four episodes:

Audio player + cover artwork on every episode page.
Audio player on every home-page card so listeners can sample without leaving the index.
Atom feed enclosures at /feed.xml. Open it in a podcast platform’s “add by URL” flow to confirm.
PodcastEpisode JSON-LD on every episode page.
Subscribe strip with four platforms.

Preview locally

sbt 'juicerJVM/run serve -s docs/demos/juicerpodcast -L'

Use it as a template

Copy docs/demos/juicerpodcast/ into your own project, drop your audio files into static/audio/, write each episode as a markdown file with the audio: frontmatter, and the rest takes care of itself.

Demo site

2026-05-27T20:59:11.669095985Z

This page is the placeholder for the live juicerlanding demo. When the docs site is built and deployed, this URL serves the actual demo rendered with the juicerlanding theme — a separate juicer build from docs/demos/juicerlanding/ is dropped on top of the docs render at the same path. See bin/build-demos.sh for the orchestration.

What the demo exercises

A fictional SaaS product — “Tally”, privacy-first web analytics — with site.toml populated so every section in the juicerlanding stack renders:

Hero — title, subtitle, primary + secondary CTAs, install one-liner code snippet.
Features grid with icons.
[[pricing]] tiers — three plans, with one row marked featured = true to get the badge + ring + scale-up treatment.
[[testimonials]] — multi-customer quotes with avatars.
[[faqs]] — native <details> accordion, no JS.
[showcase] — featured-customer logos block.
[code] — standalone code-snippet section.
[[trust]] — security / compliance badges row.
[[footerColumns]] — four-column footer with brand blurb auto-generated from title + tagline.
Secondary pages — /changelog/, /privacy/, /about/ — using the generic file.html prose layout.
404 page that survives even if the topbar partial errors out.

Preview locally

sbt 'juicerJVM/run serve -s docs/demos/juicerlanding -L'

The -L flag enables live reload — touch any markdown file under docs/demos/juicerlanding/content/ (or change site.toml) and the open browser tabs reload via SSE.

Use it as a template

Copy docs/demos/juicerlanding/ into your own project as a starting point. The home page assembles entirely from site.toml blocks, so most of your edits land there — change the hero copy, the pricing table, the FAQ entries. The companion Configuration reference catalogues every section block, frontmatter knob, and palette token the theme reads.

Demo site

2026-05-27T20:59:11.669095985Z

This page is the placeholder for the live juicergallery demo. When the docs site is built and deployed, this URL serves the actual demo rendered with the juicergallery theme — a separate juicer build from docs/demos/juicergallery/ is dropped on top of the docs render at the same path. See bin/build-demos.sh for the orchestration.

What the demo exercises

A fictional Reykjavík photographer — “Hella Studio” — with three small galleries:

Iceland 2024 — landscapes, varied aspect ratios to show off the masonry.
Studio portraits — tall portrait crops, packed into the same grid.
Local sunsets — wide horizontals.

Every photo is rendered through the imageVariants pipeline, so the build emits webp + JPG variants at three widths and the <picture> markup carries a full multi-width srcset. View the page source on a gallery detail to see the variant URLs the browser picks from.

The home page uses layout: home to opt into the cover-grid; each gallery detail uses the default folder layout (no opt-in needed); the about page is a plain file.html prose layout.

Preview locally

sbt 'juicerJVM/run serve -s docs/demos/juicergallery -L'

The -L flag enables live reload — touch any markdown file under docs/demos/juicergallery/content/ and the open browser tabs reload via SSE.

Use it as a template

Copy docs/demos/juicergallery/ into your own project as a starting point. Drop your photos into static/img/<gallery-name>/, declare each gallery as a top-level section with a photos: list, and retune [juicergallery] palette tokens. The companion Configuration reference catalogues every site.toml key, palette token, and per-section frontmatter knob the theme reads.

Demo site

2026-05-27T20:59:11.669095985Z

Unlike the other six bundled themes — each of which has its own demo site under docs/demos/<theme>/ that the deploy pipeline builds into /themes/<theme>/demo/ — juicerdocs has no separate demo source. This site, juicer.build, is built with juicerdocs. Every page you’ve been reading is the live theme.

What this site demonstrates

The juicerdocs theme rendering against real-world content — over a hundred markdown pages, deep section trees, all 17 shortcodes in use, search backed by /search.json, the right-rail “On this page” TOC, mobile sidebar overlay, light + dark mode driven by the topbar toggle, server-side syntax highlighting in code blocks.

← Back to the home page and read around the docs to see every juicerdocs feature in context. Or, if you want a quick tour:

Hero treatment + feature-card grid — the home page.
Sidebar nav with arbitrary nesting depth — the Themes section ships three levels (Themes → juicerblog → Configuration) and the recursive partial supports more.
Right-rail TOC — long pages that opt into toc: true get the auto-highlighting “On this page” rail.
Code blocks with copy buttons + language chips — the “Copy” button flashes “Copied” on success.
Shortcodes in use — the catalogue page renders every shortcode against itself, so the styling is visible inline.

Use it as a template

The source for juicer.build lives at docs/ in the juicer repository. The shape:

docs/
├── site.toml             # site config
├── content/              # this entire docs tree
├── themes/juicerdocs/    # the theme itself
└── demos/                # per-theme demo sources (built separately)

Strip the existing content/ tree, replace it with your own, and point [juicerdocs] logo at your wordmark. The companion Configuration reference catalogues every site.toml key, palette token, and per-page frontmatter knob the theme reads.

Demo site

2026-05-27T20:59:11.669095985Z

This page is the placeholder for the live juicercook demo. When the docs site is built and deployed, this URL serves the actual demo rendered with the juicercook theme.

What the demo exercises

“Elder & Ash” — a small home-cooking site with six recipes split between breads, mains, and desserts:

Hero photo + recipe card on every recipe page.
Step photos on the sourdough recipe (shape, score, crumb cross-section).
schema.org Recipe JSON-LD on every recipe — paste any recipe URL into the Rich Results Test to see how Google parses it.
Print stylesheet — File → Print on any recipe page strips chrome and prints clean.
Category chips on the home page.

Preview locally

sbt 'juicerJVM/run serve -s docs/demos/juicercook -L'

Use it as a template

Copy docs/demos/juicercook/ into your own project, drop your hero photos into static/img/, write each recipe as a markdown file with the structured frontmatter shape, and the recipe pages render themselves.

Demo site

2026-05-27T20:59:11.669095985Z

This page is the placeholder for the live juicerchurch demo. When the docs site is built and deployed, this URL serves the actual demo rendered with the juicerchurch theme — a separate juicer build from docs/demos/juicerchurch/ is dropped on top of the docs render at the same path. See bin/build-demos.sh for the orchestration.

What the demo exercises

A fictional parish — “Grace Community Church” — with content populating every juicerchurch layout:

Sermon archive + per-sermon pages with scripture reference, preacher / leader, audio + video URLs with displayed durations, transcript body.
12-month calendar grid rendering .site.calendar with recurring weekly events expanded onto every matching weekday.
Events list + per-event pages sharing the calendar’s underlying data.
Ministries — each ministry has its own layout: ministry page: leader, meeting time, contact info, narrative.
Photo albums — per-event and site-wide.
Service-times block in the header driven by [[services]] in site.toml.
/visit/ block — address, mapURL — surfaced in the footer.
Multi-clergy bylines via the author registry (sermons by different preachers).
Beliefs page — a static page that opts out of the post chrome.

Preview locally

sbt 'juicerJVM/run serve -s docs/demos/juicerchurch -L'

The -L flag enables live reload — touch any markdown file under docs/demos/juicerchurch/content/ and the open browser tabs reload via SSE.

Use it as a template

Copy docs/demos/juicerchurch/ into your own project as a starting point. Replace the service times, the sermon content, the ministries — the layouts handle the rest. The companion Configuration reference catalogues every site.toml key, palette token, and per-page frontmatter knob the theme reads.

Demo site

2026-05-27T20:59:11.669095985Z

This page is the placeholder for the live juicercafe demo. When the docs site is built and deployed, this URL serves the actual demo rendered with the juicercafe theme — a separate juicer build from docs/demos/juicercafe/ is dropped on top of the docs render at the same path. See bin/build-demos.sh for the orchestration.

What the demo exercises

A fictional neighborhood café — “Stratus Coffee” — with content populating every juicercafe layout:

Hours widget — [[hours]] rows for each day, with “Open now”/”Closed” pill in the topbar driven by current time.
Menu sections — multiple layout: menu-section pages composed under a layout: menu index.
Events list + per-event pages — including weekly recurring events (recurring: weekly + recurringDay:).
Photo album — site-wide grid pulling from every page’s photos: frontmatter, sorted by date desc.
/visit/ block — address, city, state, zip, optional map URL surfaced in the footer on every page.
“We’re working on it” card layout for the pending-projects page.
Custom authors path — authorsPath = "/team/" so per-author archives live under /team/ instead of /authors/.
Multi-baker bylines via the author registry.

Preview locally

sbt 'juicerJVM/run serve -s docs/demos/juicercafe -L'

The -L flag enables live reload — touch any markdown file under docs/demos/juicercafe/content/ and the open browser tabs reload via SSE.

Use it as a template

Copy docs/demos/juicercafe/ into your own project as a starting point. Replace the hours table, the menu items, the photo URLs, the address — the layouts handle the rest. The companion Configuration reference catalogues every site.toml key, palette token, and per-page frontmatter knob the theme reads.

Demo site

2026-05-27T20:59:11.669095985Z

This page is the placeholder for the live juicerblog demo. When the docs site is built and deployed, this URL serves the actual demo rendered with the juicerblog theme — a separate juicer build from docs/demos/juicerblog/ is dropped on top of the docs render at the same path. See bin/build-demos.sh for the orchestration.

What the demo exercises

A short fictional engineering blog populated with realistic content covering both Phase 1 and Phase 2 blog features:

9 dated posts spanning Jul–Dec 2024 (most recent first).
3 authors (ed, alice, ben) with full author-registry records — avatars, bios, external links.
Multi-author co-byline on one post (Ed + Alice).
A 3-post series (“Reading on screens · Part N of 3”) with the series-progress badge above the body and the “In this series” sidebar.
Pagination at 4 posts/page on the home + archive listings.
[permalinks] with posts = ":year/:month/:slug/" — every post lives at /<year>/<month>/<slug>/ regardless of its source filename.
Year + month archives via dateArchives = true.
Aliases on one post (old URL redirects to new).
Server-side syntax highlighting (Scala, JS, TOML, Bash) via bundled grammars/.
Atom + RSS feeds at /feed.xml and /feed.rss.
OpenGraph + Twitter card meta in <head> on every post.

Preview locally

sbt 'juicerJVM/run serve -s docs/demos/juicerblog -L'

The -L flag enables live reload — touch any markdown file under docs/demos/juicerblog/content/ and the open browser tabs reload via SSE.

Use it as a template

Copy docs/demos/juicerblog/ into your own project as a starting point. Strip the example posts, replace the [[authors]] table, drop your favicon + author avatars into static/img/, and you’re shipping. The companion Configuration reference catalogues every site.toml key and palette token the theme reads.

Content files

2026-05-27T20:59:11.669095985Z

Every page on a juicer site comes from a markdown file under content/. There are two flavors:

Section index — a file named _index.md (configurable via folderContent). Renders to index.html at the section directory. Carries the section’s title, summary, and any list-page customizations.
Single page — every other markdown file (foo.md). Renders to its own foo/index.html for clean URLs.

content/
├── _index.md                 → /index.html
├── about.md                  → /about/index.html
└── docs/
    ├── _index.md             → /docs/index.html
    ├── installation.md       → /docs/installation/index.html
    └── api/
        ├── _index.md         → /docs/api/index.html
        └── spec.md           → /docs/api/spec/index.html

Frontmatter

Every content file may begin with a YAML frontmatter block, delimited by ---:

---
title: My page
summary: One-line description shown in lists and meta tags.
weight: 30
draft: false
---

# Welcome

The body is plain markdown.

Recognized frontmatter keys:

Key	Type	What it does
`title`	string	Page title; used by templates and search index
`summary`	string	Explicit summary; overrides auto-derived
`weight`	int	Sort key inside the section (lower = first)
`draft`	bool	Skip the page unless `--drafts` is passed
anything	any	Available to templates as `.page.<key>`

Note

The frontmatter format is YAML. JSON and TOML frontmatter are not supported — partly because YAML covers the use case fluently, partly because supporting three formats triples the surface area to keep correct.

Pretty URLs

Both flavors of content render to index.html so that URLs don’t carry file extensions. about.md becomes /about/, not /about.html. The _index.md for a section becomes /docs/, not /docs.html.

The `htmlDir` quirk

By default (the standard baseline config) juicer writes nested sections to dst/html/<section>/... rather than dst/<section>/.... That html/ segment is filesystem-only — every URL juicer emits has it stripped. The convention exists so that:

The site root index.html lives at the top of dst/, alongside static/ files (favicon.ico, robots.txt, etc.).
Nested content stays under a single subtree, so a webserver root pointing at dst/ doesn’t conflate static assets with rendered pages.

If this surprises you, set htmlDir = "" in your site.toml to disable. Most users don’t need to touch it.

Page bundles

Drop non-markdown files (images, attachments, anything that isn’t .md/.toml/.yaml/.html) next to a page’s markdown and they ride along as bundle assets:

content/iceland-2024/
  _index.md
  hero.jpg
  skogafoss.jpg

hero.jpg is copied to the section’s output directory and served from /iceland-2024/hero.jpg. Templates iterate .page.assets to render a gallery or attachments list, and imageVariants 'hero.jpg' (no leading slash) resolves bundle-relative — move the bundle, the markup follows.

Full reference (record shape, resolution rules, when NOT to use a bundle) in Template data → Page bundles.

Drafts

A page with draft: true is skipped entirely during a normal build — invisible to the TOC, sitemap, search index, and section listings. To preview drafts locally, pass --drafts (or -D):

sbt 'juicerJVM/run serve -s docs -D'

Scheduling future posts

A page whose parsed date: frontmatter is in the future is skipped during a normal build, the same way draft: true is — invisible to every downstream consumer. The intended workflow is:

Set the publication date in frontmatter

---
title: Big announcement
date: 2024-12-25T09:00:00Z
---

Push the post to your repo whenever it’s done

The post is invisible to a normal juicer build until the system clock catches up.

Re-build (or re-deploy) on or after the publication date

The post starts appearing in section listings, taxonomy archives, feeds, and the sitemap automatically. Most people set up a daily build cron or use a CI scheduler.

To preview future-dated posts locally, pass --future (or -F):

sbt 'juicerJVM/run serve -s docs -F'

--future and --drafts are independent flags. A post with draft: true and a future date requires both flags to render.

Note

The future-skip rule only applies to pages with explicit date: frontmatter. Pages relying on the filesystem-mtime fallback are never future-skipped — mtime can’t be in the future under any normal workflow, but the safer rule is “only authored future-dating counts”.

Summaries

Every page exposes a .page.summary. Three sources are tried, in order:

Explicit frontmatter

If summary: ... is set in frontmatter, it’s used verbatim. Stop.

`` marker

The body up to (but not including)  is rendered as HTML and used as the summary. Useful when the natural summary is the first paragraph or two but you don’t want to repeat yourself.

First paragraph (fallback)

The first paragraph’s plain text, capped at 30 words and ellipsised. Hugo defaults to 70 words; juicer trims tighter for compact list pages.

Configuration

2026-05-27T20:59:11.669095985Z

juicerwiki reads its configuration from three places:

A small set of top-level site keys (the same ones every juicer theme uses, plus topnav and links).
A namespaced [juicerwiki] table for palette + typography overrides.
Per-note frontmatter — flat content tree, one note per file.

Quick example

title    = "Field Notes"
tagline  = "A reading wiki on computing"
author   = "ed"
baseURL  = "https://fieldnotes.example"
theme    = "juicerwiki"

[[topnav]]
label = "Tags"
url   = "/tags/"

[[topnav]]
label = "About"
url   = "/about/"

A minimal note (content/zettelkasten.md):

---
title: Zettelkasten
date: 2024-02-10
tags: [method, history]
summary: A note-taking method built around small atomic notes that link to each other.
---

Body in markdown. Link other notes liberally — `[Atomic Notes](/atomic-notes/)`
shows up in the linked note's backlinks panel automatically.

And a root index that opts into the home layout (content/_index.md):

---
title: Field Notes
layout: home
---

Optional intro paragraph shown above the tag cloud.

Top-level keys

Key	Type	Default	Notes
`title`	`String`	required	Brand text in topbar + footer; `<title>` element.
`tagline`	`String`	unset	Italic subtitle next to the brand in the topbar.
`description`	`String`	unset	Default `<meta name="description">`.
`author`	`String`	unset	Footer copyright line. Falls back to `title`.
`baseURL`	`String`	required	Standard juicer key.
`theme`	`String`	required	Set to `"juicerwiki"`.
`favicon`	`String`	unset	Path to a favicon.
`hideJuicerCredit`	`Boolean`	`false`	Set `true` to remove the “Built with juicer” line.
`topnav`	`[[topnav]]`	unset	Array of `{label, url}` entries shown in the topbar.
`links`	`[[links]]`	unset	Array of `{label, url}` entries shown in the footer.

Per-note frontmatter

Key	Type	What
`title`	`String`	Required — the note’s display name.
`date`	`String`	Controls home-page recency ordering. Also drives the Article JSON-LD `datePublished`.
`tags`	`List`	Single string or list. Each tag generates a `/tags/<slug>/` archive page.
`summary`	`String`	Shown on the home list, in `<meta name="description">`, and in other notes’ backlinks panels.

`[juicerwiki]` palette + typography overrides

[juicerwiki]
brand        = "#3b2c1e"   # walnut ink# walnut ink
brandStrong  = "#1f150c"
accent       = "#7a4a1c"   # umber accent# umber accent
fontSans     = "'Inter', system-ui, sans-serif"
fontSerif    = "'Crimson Pro', Georgia, serif"

# Dark-mode overrides# Dark-mode overrides
brandDark    = "#f1e7d6"
accentDark   = "#d99a52"

See Reference → Theming for the shared theming model.

Client-side search

juicer auto-generates /search.json for every site — see Reference → Search for the field shape. juicerwiki ships a search partial that fetches it lazily on first modal open and runs an in-memory substring match. No backend, no API, no third-party service.

Configuration

2026-05-27T20:59:11.669095985Z

juicerstudy reads its configuration from three places in site.toml plus per-page frontmatter:

A small set of top-level site keys (the same ones every juicer theme uses — title, author, baseURL, etc.).
A namespaced [juicerstudy] table for theme-specific knobs — palette, typography, sizing, the math opt-in.
Per-page frontmatter for opt-ins like the right-rail TOC and the page’s own summary lead.

Anything you don’t set keeps the theme’s defaults. juicerstudy uses [juicerstudy] so it doesn’t collide with the keys other themes might want.

Quick example

A complete site.toml exercising every juicerstudy-aware feature:

title    = "Marginalia"
tagline  = "notes from the margins of books"
author   = "a slow reader"
baseURL  = "https://example.com"

theme    = "juicerstudy"
headingShift = 0

[juicerstudy]
# Optional KaTeX rendering. Off by default — sites without math# Optional KaTeX rendering. Off by default — sites without math
# don't pay the script + stylesheet cost.# don't pay the script + stylesheet cost.
math = true

# Logo for the topbar wordmark + the <link rel=icon> fallback.# Logo for the topbar wordmark + the <link rel=icon> fallback.
# Top-level `favicon` wins over this for the icon tag.# Top-level `favicon` wins over this for the icon tag.
logo = "/site-logo.png"

# Palette — a quiet scholarly grey with amber accent.# Palette — a quiet scholarly grey with amber accent.
brand           = "#475569"   # slate-600 — primary# slate-600 — primary
brandStrong     = "#334155"   # slate-700 — hover# slate-700 — hover
brandSoft       = "#f1f5f9"   # slate-100 — backgrounds# slate-100 — backgrounds
accent          = "#b45309"   # amber-700 — secondary, link-like# amber-700 — secondary, link-like
leaf            = "#65a30d"   # lime-600  — success / leaf# lime-600  — success / leaf

brandDark       = "#94a3b8"
brandStrongDark = "#cbd5e1"
brandSoftDark   = "rgb(148 163 184 / .12)"
accentDark      = "#fbbf24"
leafDark        = "#a3e635"

Top-level keys (read by juicerstudy)

Key	Type	Default	What it does
`title`	string	`"Untitled"`	Wordmark in the topbar; appears in `<title>` tags
`author`	string	`"Unnamed"`	Footer copyright line (only when `showCopyright = true`)
`baseURL`	string	(required)	Used for absolute permalinks, sitemap, atom feed
`theme`	string	(required)	Set this to `"juicerstudy"`
`headingShift`	int	`2`	The juicerstudy layout already provides an outer `<h1>{{ .page.title }}</h1>`, so set this to `0` if your markdown bodies start at `##` (the natural prose convention)
`favicon`	string	(none)	Path (relative to your site root) of the `<link rel=icon>`. When unset, `[juicerstudy].logo` is used as fallback.
`customCSS`	array	`[]`	Site-supplied stylesheets, loaded after `juicerstudy.css` so they can override anything. See Theming.
`showCopyright`	bool	`false`	When true, the footer renders a `© {{ .site.author }}` line beside the “Built with Juicer” attribution
`hideJuicerCredit`	bool	`false`	When true, suppresses the “Built with Juicer · Theme: juicerstudy” line in the footer

`[juicerstudy]` keys

Optional features

Key	Type	Default	What
`juicerstudy.math`	bool	`false`	When true, loads KaTeX (CSS + JS + auto-render) from CDN and renders $…$ , `$$…$$`, `$ … $`, `\[ … \]` math in the body. Pinned to a recent KaTeX major. Sites that don’t need math leave it off so the page stays zero-asset.
`juicerstudy.logo`	string	(none)	Path of the logo image used in the topbar wordmark and (when no top-level `favicon` is set) as the `<link rel=icon>` fallback

Palette — light mode

Key	Type	Default	What
`juicerstudy.brand`	color	`#1e3a8a` (ink blue)	Primary brand color — body link color, sidebar active border, code-highlight underlines
`juicerstudy.brandStrong`	color	`#1e40af`	Hover state for primary links and buttons
`juicerstudy.brandSoft`	color	`rgba(30,58,138,.10)`	Soft brand tint — sidebar hover, callout backgrounds, selection highlight
`juicerstudy.accent`	color	`#92400e`	Secondary accent — decorative highlights, secondary links
`juicerstudy.leaf`	color	`#166534`	“Confirmation green” — copy-button “copied” state, success indicators

Any CSS color expression works: hex (#...), rgb(...), hsl(...), oklch(...), color-mix(...), named colors. The values land in a <style> block emitted after juicerstudy.css.

Palette — dark mode overrides

Key	Type	Default
`juicerstudy.brandDark`	color	`#93c5fd`
`juicerstudy.brandStrongDark`	color	`#bfdbfe`
`juicerstudy.brandSoftDark`	color	`rgba(147, 197, 253, 0.14)`
`juicerstudy.accentDark`	color	`#fdba74`
`juicerstudy.leafDark`	color	`#86efac`

Set just the ones you want to differ — anything you leave out keeps its light-mode value, which is almost certainly wrong in dark mode, so it’s worth setting all five.

Typography

Key	Type	Default	What
`juicerstudy.fontSans`	string	`'Inter', system-sans-stack`	Sans-serif face. Chrome (topbar, sidebar, footer) and headings are sans by default.
`juicerstudy.fontSerif`	string	`'Source Serif Pro', 'Iowan Old Style', Charter`	Serif face. The reading column inside `.juicerstudy-content` is serif by default.
`juicerstudy.fontMono`	string	`'JetBrains Mono', ui-monospace, Menlo`	Monospace face for code blocks + the `kbd` shortcode.

To swap in a different font, set its @font-face declarations in your own static/site.css, add the file path to customCSS, and set the matching token here.

Sizing

Key	Type	Default	What
`juicerstudy.contentMax`	length	`38rem`	Max width of the reading column. Tuned for ~65ch of serif body.
`juicerstudy.sidebarW`	length	`16rem`	Width of the left sidebar nav.
`juicerstudy.railW`	length	`18rem`	Width of the right “On this page” rail (only emitted when a page sets `toc: true`).
`juicerstudy.radiusLg`	length	`0.5rem`	Border-radius for “large” surfaces — code-block frames, modal, callouts.

Per-page frontmatter

Keys juicerstudy reads from each page’s frontmatter:

Key	Type	Default	What
`title`	string	filename-derived	Rendered as the page’s `<h1>` and the `<title>` element
`summary`	string	(none)	Rendered as the `juicerstudy-lead` line under the title (an italic dropcap-ish subtitle) and used as `<meta name=description>`
`toc`	bool	`false`	When true, the right-side “On this page” rail is emitted for the page (heading IDs are auto-generated from the markdown body). Off by default — most prose doesn’t want it, but reference-style notes do.
`author`	string	(none)	Surfaces in the topbar metadata block (when present) and the atom feed
`minutes`	int	(none)	Read-time hint, surfaced by the `section-list` shortcode for landing pages that list children

Root landing (`_index.md`) extras

Keys juicerstudy reads on the root _index.md to drive the landing-page hero:

Key	Type	Default	What
`heroTitle`	string	(none)	Big hero headline. When set, the title text replaces the plain `<h1>` and you can highlight one word via `heroHighlight`.
`heroHighlight`	string	(none)	One word from the hero rendered with the brand-gradient `juicerstudy-grad` treatment.
`heroSuffix`	string	`.`	Appended after the highlight word — typically a period or exclamation point.
`heroImage`	path	(none)	Optional hero image, rendered through `imageVariants` for responsive `<picture>` markup.
`heroImageAlt`	string	(none)	Alt text for the hero image.
`heroImageCaption`	string	(none)	Caption shown under the hero image.

These are root-only — nested section landings render with a simpler header + subsection-card grid (and ignore the hero keys).

Site-level landing tokens

The root landing also reads two [juicerstudy] keys that control the hero’s CTAs:

Key	Type	Default	What
`juicerstudy.startReading`	bool or string	`false`	When `true`, emits a “Start reading” CTA pointing at `/start/`. Set to a path string (e.g. `"/intro/"`) to point elsewhere.
`juicerstudy.repoCTA`	bool	`false`	When `true` and a top-level `repoURL` is set, emits a “View on GitHub” CTA. The two-flag pattern is intentional: `repoURL` is commonly set just to drive the topbar GitHub icon, and personal / editorial sites usually don’t want a hero CTA tagging along.
`juicerstudy.logo`	path	(none)	Logo image shown in the hero’s meta row above the title.
`juicerstudy.version`	string	(none)	Optional version chip shown next to the logo.

Image variants

[images] enabled = true in site.toml turns on responsive image delivery for both the heroImage and any use of the figure shortcode. The build runs magick (ImageMagick 7) once per source, caches by content hash, and reuses across builds. See Reference → Image variants for the full configuration surface.

[images]
enabled = true
widths  = [480, 960, 1600]
formats = ["webp", "original"]
quality = 78

All other juicer engine frontmatter (date, weight, aliases, permalinks, etc.) works as documented in Reference → Frontmatter — juicerstudy doesn’t override or hide any of it.

Shortcodes

juicerstudy ships the standard juicer shortcode set plus one study-specific one:

Callouts — note, tip, warning, danger
Layout helpers — figure, collapse, tabs / tab, steps, buttons / button
Inline — kbd, badge, github
Embeds — youtube
Reference — filetree
juicerstudy-specific — section-list (renders a section’s direct children as a titled list with summaries; useful on authored section landings that want an explicit catalog beside the editorial prose). See the shortcodes reference for the generic shortcode usage and call-site conventions.

Note

The section-list shortcode is wired up but currently silently renders nothing — see the comment in docs/themes/juicerstudy/shortcodes/section-list.html for the engine-side gap. It will start working when juicer threads page context into shortcode rendering; the template and CSS are ready.

Where the values land

The <head> partial emits a <style> block immediately after juicerstudy.css, redefining only the variables you’ve set:

```css: root {

–brand: #475569; /* from juicerstudy.brand / –brand-strong: #334155; / from juicerstudy.brandStrong / / … / } [data-theme=”dark”] { –brand: #94a3b8; / from juicerstudy.brandDark / / … */ }


Anything not set falls through to the defaults declared at the top
of `juicerstudy.css`. The theme always toggles between light and
dark via the `data-theme` attribute on `<html>`, set by the
pre-paint script in `<head>`.

## Going beyond config

Drop a file with the same path under your own site to override
anything in the theme — the ordinary
[theme overlay](/concepts/themes/) pattern:

| You want to change… | Override at… |
|---------------------|--------------|
| The topbar          | `<src>/partials/topbar.html` |
| The footer markup   | `<src>/partials/footer.html` |
| The 404 page        | `<src>/layouts/_default/404.html` |
| The section landing | `<src>/layouts/_default/folder.html` |
| Custom CSS          | `<src>/static/site.css` (and add `"site.css"` to `customCSS` in `site.toml`) |

Site files always win over theme files, so overrides are a
one-file-at-a-time operation — no forking the theme.

## SEO

Every juicer theme ships a shared SEO partial (`partials/seo.html`) that emits the standard meta block: description (with site-level fallback), canonical link, author meta, robots `noindex`, OpenGraph + Twitter cards (via the `ogTags` builtin), Atom feed discovery, and theme-specific JSON-LD. The engine separately writes `sitemap.xml` and `robots.txt`.

### Site-wide keys

```toml
description = "Notes and short courses on linear algebra, written for the curious."
ogImage     = "/og/default.png"

robots   = true
noindex  = false                  # set true for staging/preview domains
disallow = ["/scratch/"]

Per-page frontmatter

---
title: Eigenvalues, intuitively
summary: A one-sentence dek for search results and OG cards.
date: 2026-04-12                  # surfaces in Article JSON-LD
author: ed
image: /img/eigenvalues-card.png
ogTitle: A snappier social headline
ogDescription: Tightened for socials
noindex: true   # excluded from sitemap, JSON-LD suppressed, <meta robots> emitted
---

Structured data emitted

Page	Schema
Root section	`WebSite`
Every other page	`Article` (with author / image / dateISO when present)
Any page with ancestors	`BreadcrumbList`

noindex: true suppresses ALL JSON-LD on that page.

Overriding the SEO partial

Drop a file at <src>/partials/seo.html (or seo-jsonld.html for just the structured-data part). Site overrides win over the theme’s copy.

Configuration

2026-05-27T20:59:11.669095985Z

juicerportfolio reads its configuration from three places:

A small set of top-level site keys (the same ones every juicer theme uses, plus a few portfolio-specific ones for the topbar / footer / filter chips).
A namespaced [juicerportfolio] table for theme-specific palette + sizing overrides.
Per-project frontmatter — projects opt into the project layout with layout: project, then set hero / meta / gallery fields the layout knows about.

Quick example

A minimal site.toml that produces a credible portfolio:

title    = "Studio Name"
tagline  = "Industrial design, Lisbon"
author   = "Studio Name"
baseURL  = "https://example.com"
theme    = "juicerportfolio"

[[topnav]]
label = "Work"
url   = "/"

[[topnav]]
label = "About"
url   = "/about/"

[contact]
email    = "studio@example.com"
location = "Lisbon, Portugal"

[[links]]
label = "Instagram"
url   = "https://instagram.com/example"

A minimal project page (content/work/my-project.md):

---
title: Tobias Lounge
layout: project
year: "2024"
tagline: Bent-ash lounge chair
summary: A short subtitle about the piece.
role: Design + production drawings
client: Private commission
tools:
  - European ash
  - 12 oz canvas
  - Brass
hero: /img/work/tobias-lounge.jpg
heroAlt: Tobias lounge chair, three-quarter view
---

The body of the writeup goes here, in regular markdown.

That’s enough to render the home grid, the project page with its meta sidebar, and the project body. Add category, gallery, link to unlock the rest.

Top-level keys

Standard juicer keys plus a few portfolio-specific ones.

Key	Type	Default	Notes
`title`	`String`	required	Brand text in topbar + footer; `<title>` element.
`tagline`	`String`	unset	Italic subtitle next to the brand in the topbar; appended to `<title>` when the page title equals the site title.
`description`	`String`	unset	Default `<meta name="description">` for pages that don’t set their own `summary`.
`author`	`String`	unset	Footer name + copyright line. Falls back to `title`.
`baseURL`	`String`	required	Standard juicer key.
`theme`	`String`	required	Set to `"juicerportfolio"`.
`favicon`	`String`	unset	Path to a favicon.
`hideJuicerCredit`	`Boolean`	`false`	Set `true` to remove the “Built with juicer” line in the footer.
`customCSS`	`[String]`	unset	Site stylesheets loaded after the theme CSS. See Theming → Layer 2.
`topnav`	`Array`	unset	Topbar nav links: `[[topnav]]` rows of `{label, url}`. Note: keyed `topnav` because top-level `nav` is reserved by juicer for table-of-contents config.
`workCategories`	`Array`	unset	Filter chips above the work grid: `[[workCategories]]` rows of `{label, value}`. Projects with `category = "<value>"` match the chip.
`contact`	`Object`	unset	`{email, location}` — surfaced in the footer brand block.
`links`	`Array`	unset	Footer external-link list: `[[links]]` rows of `{label, url}`.

Palette + token overrides — `[juicerportfolio]`

All optional. Anything you don’t set keeps the warm-paper / rust defaults. The full mapping (which token drives which CSS variable) is documented in Theming — juicerportfolio follows the same pattern as the other themes.

Key	CSS variable	Default	Notes
`brand`	`--brand`	`#c4633b` (warm rust)	The single accent — link hover, active filter chip, project meta link, blockquote rule.
`brandStrong`	`--brand-strong`	`#8a3f22`	Hover-emphasis on brand-coloured elements.
`brandSoft`	`--brand-soft`	`#f4e6dc`	Subtle paper-tinted backgrounds.
`accent`	`--accent`	`#2b2620` (near-black)	Reserved; not used by Stage-1/2 sections.
`brandDark`	`--brand` (dark)	`#d6845f`	Lifted rust for dark backgrounds.
`brandStrongDark`	`--brand-strong` (dark)	`#f0a982`
`brandSoftDark`	`--brand-soft` (dark)	`rgba(214,132,95,0.16)`
`accentDark`	`--accent` (dark)	`#ede7d9`
`fontSans`	`--font-sans`	system-ui stack	Body / UI / nav face.
`fontSerif`	`--font-serif`	Iowan Old Style stack	Project titles, brand, page titles.
`fontMono`	`--font-mono`	system mono stack	Materials chips, code in writeups.
`measure`	`--measure`	`62ch`	Prose column max-width on `file.html` / `folder.html`.
`gutter`	`--gutter`	`1.5rem`	Outer padding around content blocks.
`radiusLg`	`--radius-lg`	`0.375rem`	Large border-radius (cards, hero images).
`logo`	(none)	unset	Path to a small image; rendered next to the brand name in the topbar.

Per-project frontmatter

Projects opt into the project layout by setting layout: project. The home grid filters by exactly that flag, so anything else (about, contact, CV) is hidden from the project listing automatically.

Key	Type	What
`layout`	`String`	`project` to opt in. Required for the home grid + project layout.
`title`	`String`	The project name. Required.
`date`	`Date`	Drives `sortBy = "date"` ordering across the grid + the prev/next reading order.
`year`	`String`	Display-only year (e.g. `"2024"` or `"2023–2024"`). Appears on the home card byline and in the meta sidebar. Quote it; TOML reads bare `2024` as an integer.
`tagline`	`String`	One-line subtitle on the home card under the title.
`summary`	`String`	Italic subtitle directly under the title on the project page; also `<meta name="description">`.
`category`	`String`	Matches a `value` in one of the `[[workCategories]]` rows. Drives the home-page filter chips.
`role`	`String`	What you did on the project. Renders as a meta-sidebar row. Optional.
`client`	`String`	Who the project was for. Omit for self-initiated work.
`tools`	`[String]`	Materials / techniques / software list. Renders as small chips in the meta sidebar under “Materials”.
`link`	`Object`	`{label, url}` — external link in the meta sidebar (live site, shop, github, etc.).
`hero`	`String`	URL of the hero image at the top of the project page. Also used as the home-card thumbnail.
`heroAlt`	`String`	Alt text for the hero image. Falls back to the title.
`caption`	`String`	Italic caption under the hero image.
`gallery`	`[Object]`	List of `{src, alt, caption}` images rendered as a 2-up figure grid below the body. Section silently omits if absent.

Per-page frontmatter (non-project)

Most other pages on a portfolio site use the default file.html layout (about, contact, CV, press) or folder.html for section indexes (/work/_index.md, /press/_index.md).

Key	Type	What
`title`	`String`	Page heading + `<title>`.
`summary`	`String`	Italic subtitle under the page title; also `<meta name="description">`.
`date`	`Date`	Sort key for `folder.html` listings. Optional on prose pages.
`lang`	`String`	Sets `<html lang>` for the page. Defaults to `en`.

Prev / next reading order

Project pages get ← Previous / Next → nav at the bottom, sourced from the engine’s .page.prev / .page.next fields. The reading order is a depth-first traversal anchored at the root section, so the project series only links across siblings if /work/ itself has an _index.md to anchor it. Without that anchor, every project’s .page.prev and .page.next are null and the nav block silently omits.

The demo’s content/work/_index.md is intentionally minimal — it doubles as a text-list archive of all projects via folder.html. If you don’t want a /work/ archive page rendered, set static: true in the _index.md frontmatter (excluded from .site.posts) — it still anchors the section for the prev/next math.

SEO

Every juicer theme ships a shared SEO partial (partials/seo.html) that emits the standard meta block: description (with site-level fallback), canonical link, author meta, robots noindex, OpenGraph + Twitter cards (via the ogTags builtin), Atom feed discovery, and theme-specific JSON-LD. The engine separately writes sitemap.xml and robots.txt.

Site-wide keys

description = "Independent designer in Halifax, working in print + the screen."
ogImage     = "/og/portrait.jpg"

robots   = true
noindex  = false
disallow = ["/scratch/"]

# Optional: Person JSON-LD on the homepage. Drives Google's Knowledge# Optional: Person JSON-LD on the homepage. Drives Google's Knowledge
# Panel for an individual.# Panel for an individual.
[person]
name     = "Ada Hopper"           # defaults to .site.title when omitted# defaults to .site.title when omitted
jobTitle = "Graphic designer & illustrator"
image    = "/img/portrait.jpg"
email    = "hello@adahopper.com"
sameAs   = ["https://github.com/adahopper", "https://dribbble.com/adahopper"]

Per-page frontmatter

---
title: Field guide cover series
summary: A one-sentence dek for search results and OG cards.
image: /img/projects/field-guide.jpg   # used by ogTags AND CreativeWork JSON-LD
ogTitle: A snappier social headline
ogDescription: Tightened for socials
noindex: true   # excluded from sitemap, JSON-LD suppressed, <meta robots> emitted
---

Structured data emitted

Page	Schema
Root section	`WebSite` (+ `Person` when `[person]` is set in `site.toml`)
Project page with `image`	`CreativeWork` (name, url, image, description, dateCreated)
Any page with ancestors	`BreadcrumbList`

noindex: true suppresses ALL JSON-LD on that page.

Overriding the SEO partial

Drop a file at <src>/partials/seo.html (or seo-jsonld.html for just the structured-data part). Site overrides win over the theme’s copy.

Configuration

2026-05-27T20:59:11.669095985Z

juicerpodcast reads its configuration from three places:

A small set of top-level site keys.
A namespaced [juicerpodcast] table for palette + show artwork + the subscribe strip.
Per-episode frontmatter — audio:, duration:, image:, etc.

Quick example

title    = "Echo Chamber"
tagline  = "A weekly conversation with one interesting person"
author   = "Sara Lindholm"
baseURL  = "https://echochamber.example"
theme    = "juicerpodcast"

[[topnav]]
label = "Episodes"
url   = "/"

# Show artwork — used on the home hero and in the PodcastSeries JSON-LD.# Show artwork — used on the home hero and in the PodcastSeries JSON-LD.
[juicerpodcast]
cover = "/img/show-cover.jpg"

[[juicerpodcast.subscribe]]
label = "Apple Podcasts"
url   = "https://podcasts.apple.com/..."

[[juicerpodcast.subscribe]]
label = "RSS"
url   = "/feed.xml"

An episode (content/ep01.md):

---
title: "Ep 01 — Pilot"
date: 2024-03-25
audio: /audio/ep01.mp3
audioType: audio/mpeg
audioLength: 9821330
duration: PT24M02S
image: /img/ep01.jpg
summary: The pilot episode.
tags: [meta]
---

Show notes go here.

Top-level keys

Key	Type	Default	Notes
`title`	`String`	required	Show name.
`tagline`	`String`	unset	Show tagline (under the hero title).
`description`	`String`	unset	Default `<meta name="description">`. Also feeds `PodcastSeries.description`.
`author`	`String`	unset	Host name.
`baseURL`	`String`	required	Standard juicer key.
`theme`	`String`	required	Set to `"juicerpodcast"`.
`favicon`	`String`	unset	Path to a favicon.
`hideJuicerCredit`	`Boolean`	`false`	Remove “Built with juicer” footer line.
`topnav`	`[[topnav]]`	unset	Topbar nav.
`links`	`[[links]]`	unset	Footer links.
`feeds`	`Boolean`	`true`	Set `false` to disable the Atom feed entirely (you almost never want this for a podcast).

Per-episode frontmatter

Key	Type	What
`title`	`String`	Required.
`date`	`String`	Drives the feed `<updated>` and home-page ordering.
`audio`	`String`	Required for the audio player + Atom enclosure + JSON-LD. Absolute URL or site-relative path.
`audioType`	`String`	MIME type — `audio/mpeg` (mp3), `audio/aac` (m4a), `audio/ogg`. Feeds the enclosure `type=` attribute.
`audioLength`	`Int`	Bytes — feeds the enclosure `length=` attribute. Run `ls -l audio.mp3` to find it. Apple Podcasts validates this.
`duration`	`String`	ISO 8601 — `PT42M30S`. Displayed in the meta line + JSON-LD.
`guest`	`String`	Shown in the meta line as “with “.
`image`	`String`	Episode artwork. Falls back to the show cover if absent.
`imageAlt`	`String`	Alt text for the artwork.
`summary`	`String`	Card summary + `<meta name="description">` + JSON-LD description.
`links`	`List`	`{label, url}` entries shown as “Mentioned in this episode”.
`transcript`	`String`	Markdown string — rendered inside a `<details>` collapsible at the bottom.
`tags`	`List`	Drives `/tags/<slug>/` archives.

Atom feed enclosures

juicer’s feed generator emits <link rel="enclosure"> per entry that has frontmatter audio: (or enclosure:). The element follows RFC 4287 §4.2.7.2 and is picked up by podcast platforms the same way they’d read RSS 2.0 <enclosure>:

<link rel="enclosure"
      href="https://echochamber.example/audio/ep04.mp3"
      type="audio/mpeg"
      length="18347281"/>

audioType and audioLength are optional but recommended — without them the link still emits, but Apple may flag the episode. Frontmatter enclosureType and enclosureLength are accepted as aliases.

`[juicerpodcast]` palette + subscribe overrides

[juicerpodcast]
brand        = "#2b1f4a"
brandStrong  = "#160d2d"
accent       = "#e36e5b"
cover        = "/img/show-cover.jpg"
fontSans     = "'Inter', system-ui, sans-serif"

# Subscribe-strip buttons on the home page# Subscribe-strip buttons on the home page
[[juicerpodcast.subscribe]]
label = "Apple Podcasts"
url   = "https://podcasts.apple.com/..."

Configuration

2026-05-27T20:59:11.669095985Z

juicerlanding reads its configuration from three places:

A small set of top-level site keys (the same ones every juicer theme uses, plus a few landing-specific ones for the topbar / footer).
A namespaced [juicerlanding] table for theme-specific palette + sizing overrides.
A stack of section blocks ([hero], [[features]], [[pricing]], etc.) that drive the home page. Each block is independently gated; missing block silently omits the section.

The home layout calls nine section partials in a fixed order: hero → trust → features → code → showcase → pricing → testimonials → faq → final-cta. You don’t need to think about the order; you just include the blocks for the sections you want.

Quick example

A minimal site.toml that produces a credible landing page:

title    = "My product"
tagline  = "What it does, in eight words or less."
baseURL  = "https://example.com"
theme    = "juicerlanding"

[hero]
headline    = "The headline."
subheadline = "The subheadline that makes the headline land."
primaryCta   = { label = "Start free", url = "/signup/" }
secondaryCta = { label = "View on GitHub", url = "https://github.com/me/it" }

[[features]]
icon  = "⚡"
title = "Fast"
body  = "Less than a kilobyte."

[[features]]
icon  = "🔒"
title = "Private"
body  = "No cookies, no fingerprinting, no consent banners."

[[features]]
icon  = "💰"
title = "Free"
body  = "Self-hosted is free forever, MIT-licensed."

[finalCta]
title = "Ready to ship?"
body  = "Two minutes to install."
primaryCta = { label = "Start free", url = "/signup/" }

Adding [[pricing]], [[testimonials]], [[faqs]], [showcase], [code], and [[trust]] blocks fills in the rest of the page. The full demo at docs/demos/juicerlanding/ exercises every section — see Demo site.

Top-level keys

Standard juicer keys plus a few landing-specific ones. juicerlanding-specific keys are flagged in the right-most column.

Key	Type	Default	Notes
`title`	`String`	required	Brand text in topbar + footer; used as `<title>` element.
`tagline`	`String`	unset	Appears under the brand in the footer; appended to `<title>` when the page title equals the site title.
`description`	`String`	unset	Default `<meta name="description">` for pages that don’t set their own `summary`.
`author`	`String`	unset	Footer copyright line. Falls back to `title`.
`baseURL`	`String`	required	Standard juicer key.
`theme`	`String`	required	Set to `"juicerlanding"`.
`repoURL`	`String`	unset	When set, juicerlanding shows a GitHub icon link in the topbar.
`favicon`	`String`	unset	Path to a favicon; emitted as `<link rel="icon">` in `<head>`.
`hideJuicerCredit`	`Boolean`	`false`	Set `true` to remove the “Built with juicer” line in the footer.
`customCSS`	`[String]`	unset	Site stylesheets loaded after the theme CSS. See Theming → Layer 2.
`topbarCta`	`Object`	unset	`{label, url}` — adds a CTA button to the topbar. Surfaced on every page so the conversion path is one click from anywhere.
`topnav`	`Array`	unset	Topbar nav links: `[[topnav]]` rows of `{label, url}`. Note: keyed `topnav` because top-level `nav` is reserved by juicer for table-of-contents config.
`footerColumns`	`Array`	unset	Footer link columns: `[[footerColumns]]` rows of `{title, links: [{label, url}]}`. The brand-blurb column is auto-generated.
`trustLabel`	`String`	`"Trusted by teams at"`	Header line above the trust-bar logos.

Palette + token overrides — `[juicerlanding]`

All optional. Anything you don’t set keeps the slate / indigo / amber defaults. The full mapping (which token drives which CSS variable) is documented in Theming — juicerlanding follows the same pattern as the other themes.

Key	CSS variable	Default	Notes
`brand`	`--brand`	`#4f46e5` (indigo-600)	Primary brand colour — primary buttons, focus rings, link hover.
`brandStrong`	`--brand-strong`	`#3730a3` (indigo-800)	Heading emphasis on light backgrounds; primary-button hover.
`brandSoft`	`--brand-soft`	`#eef2ff` (indigo-50)	Eyebrow chip background, hero gradient, feature-card icon background.
`accent`	`--accent`	`#f59e0b` (amber-500)	Reserved for “warm” highlights; not used by Stage-1 sections.
`leaf`	`--leaf`	`#10b981` (emerald-500)	Checkmark colour in the pricing + code-section bullet lists.
`brandDark`	`--brand` (dark)	`#818cf8` (indigo-400)	Lifted indigo for dark-mode backgrounds.
`brandStrongDark`	`--brand-strong` (dark)	`#c7d2fe` (indigo-200)
`brandSoftDark`	`--brand-soft` (dark)	`rgba(129,140,248,0.12)`
`accentDark`	`--accent` (dark)	`#fbbf24` (amber-400)
`leafDark`	`--leaf` (dark)	`#34d399` (emerald-400)
`fontSans`	`--font-sans`	Inter stack	Body / UI / heading face.
`fontMono`	`--font-mono`	JetBrains Mono stack	Code blocks.
`measure`	`--measure`	`65ch`	Prose column max-width on `file.html` / `folder.html`.
`gutter`	`--gutter`	`1.5rem`	Outer padding around content blocks.
`radiusLg`	`--radius-lg`	`1rem`	Large border-radius (cards, hero panels, code frame).
`logo`	(none)	unset	Path to a small image; rendered next to the brand name in the topbar + footer.

Section blocks

Each section partial reads its own block. Missing block = silently omitted, so an early-stage site can ship with just [hero] + [[features]] + [finalCta], and add the rest later without changing the layout.

`[hero]` — the main pitch

[hero]
eyebrow      = "v1.0 · privacy-first"
headline     = "The headline."
subheadline  = "Subheadline."
codeLang     = "html"
codeSnippet  = "<script src=...></script>"
screenshot   = "/img/screenshots/hero.png"   # alternative to codeSnippet# alternative to codeSnippet
screenshotAlt = "Dashboard screenshot"

primaryCta   = { label = "Start free", url = "/signup/" }
secondaryCta = { label = "View on GitHub", url = "https://github.com/..." }

codeSnippet and screenshot are mutually exclusive — codeSnippet wins if both are set. If neither is set, the hero renders as a single-column copy block.

`[[trust]]` — the social-proof strip

trustLabel = "Trusted by teams at"     # optional; default shown# optional; default shown

[[trust]]
logo = "/img/logos/acme.svg"
alt  = "Acme Corp"
url  = "https://acme.example/"          # optional — wraps the logo in <a># optional — wraps the logo in <a>

Logos are rendered greyscale with a hover that lifts the saturation back. Aim for monochrome wordmarks at ~120×40.

`[featuresHead]` + `[[features]]` — the feature grid

[featuresHead]
title = "Everything you need, nothing you don't"
body  = "Optional intro paragraph."

[[features]]
icon  = "⚡"            # any emoji, OR a path to an SVG# any emoji, OR a path to an SVG
title = "Title"
body  = "Body copy."

3-up at desktop, 2-up at tablet, 1-up at mobile. The icon is rendered inline; emoji-as-icon is the recommended path because it ships zero asset weight.

`[code]` — code showcase with bullet list

[code]
title   = "Track what matters"
body    = "Optional intro paragraph above the bullets."
lang    = "javascript"
snippet = "tally('signup', { plan: 'pro' })"
bullets = [
  "First-party only",
  "Properties aggregated server-side",
  "Same API everywhere",
]

Two-column layout — code on one side, copy + checklist on the other.

`[showcase]` — the screenshot section

[showcase]
title   = "A dashboard you can read at a glance"
body    = "Body copy."
image   = "/img/screenshots/dashboard.svg"
alt     = "Tally dashboard"
caption = "Optional figcaption under the image."
reverse = true     # flip image to the left, copy to the right# flip image to the left, copy to the right

reverse = false (default) puts copy on the left and image on the right. Set true when you’ve already used the same orientation in [code] immediately above and want visual variety.

`[pricingHead]` + `[[pricing]]` — pricing tiers

[pricingHead]
title = "Simple pricing"
body  = "Optional intro."

[[pricing]]
tier     = "Free"
price    = "$0"
cadence  = "self-hosted"
tagline  = "One-line subtitle."
features = ["Feature one", "Feature two", "Feature three"]
featured = false
cta      = { label = "Get the source", url = "/docs/install/" }

The row marked featured = true gets the highlighted column treatment (border, glow, scale-up, “Most popular” badge). Order in the file is left-to-right on the page.

`[testimonialsHead]` + `[[testimonials]]` — quote cards

[testimonialsHead]
title = "What devs are saying"
body  = "Optional intro."

[[testimonials]]
quote   = "..."
name    = "..."
role    = "..."
company = "..."         # optional# optional
avatar  = "/img/avatars/jane.svg"   # optional# optional

3-up at desktop, 1-up at mobile. The avatar is rendered as a 2.5rem circle; SVG initial-badges work well as placeholders before you have real photos.

`[faqHead]` + `[[faqs]]` — accordion

[faqHead]
title = "Frequently asked"
body  = "Optional intro."

[[faqs]]
q    = "Question?"
a    = "Answer."
open = true   # optional — render this item open by default# optional — render this item open by default

Native <details>/<summary>. No JS. The <a> tag inside the answer string works as expected (it’s emitted into the page as plain HTML).

`[finalCta]` — the close

[finalCta]
title        = "Ready to ship?"
body         = "Two minutes to install."
primaryCta   = { label = "Start free", url = "/signup/" }
secondaryCta = { label = "Read the docs", url = "/docs/" }

Indigo-gradient panel with white copy and a primary + ghost button pair. Always render this if you can — it’s the last conversion surface before the footer.

Per-page frontmatter

Most pages on a juicerlanding site are the home page (layout: home) and a handful of secondary pages (layout: file is the default). The frontmatter knobs:

Key	Type	What
`layout`	`String`	`home` for the section-driven landing page, omitted (or `file`) for prose pages, `folder` for section indexes (e.g. `/blog/_index.md`).
`title`	`String`	Heading at the top of the page; also `<title>`. The home `_index.md` should omit this so the page title falls through to `.site.title`.
`summary`	`String`	Subtitle under the page title; also `<meta name="description">` for that page.
`date`	`Date`	Sort key for `folder.html` listings. Optional.
`lang`	`String`	Sets `<html lang>` for the page. Defaults to `en`.

SEO

Site-wide keys

description = "The fastest way to ship docs that look like you wrote them yourself."
ogImage     = "/og/hero.png"

robots   = true
noindex  = false                  # set true for staging/preview domains# set true for staging/preview domains
disallow = ["/private/"]

# Optional: Organization JSON-LD on the homepage. Drives Google's# Optional: Organization JSON-LD on the homepage. Drives Google's
# Knowledge Panel for the brand.# Knowledge Panel for the brand.
[organization]
name   = "Juicer Labs"            # defaults to .site.title when omitted# defaults to .site.title when omitted
logo   = "/img/logo-square.png"
email  = "hello@juicerlabs.io"
sameAs = ["https://github.com/edadma/juicer", "https://twitter.com/juicerlabs"]

Per-page frontmatter

---
title: Pricing
summary: A one-sentence dek for search results and OG cards.
image: /img/og/pricing.png
ogTitle: Snappier headline for socials
ogDescription: Tightened for socials
noindex: true   # excluded from sitemap, JSON-LD suppressed, <meta robots> emitted
---

Structured data emitted

Page	Schema
Root section	`WebSite` (+ `Organization` when `[organization]` is set in `site.toml`)
Any page with ancestors	`BreadcrumbList`

Landing-page sites usually don’t have a “post” surface, so juicerlanding doesn’t emit Article JSON-LD by default. Add your own via a <src>/partials/seo-jsonld.html override if you need it.

noindex: true suppresses ALL JSON-LD on that page.

Overriding the SEO partial

Drop a file at <src>/partials/seo.html (or seo-jsonld.html for just the structured-data part). Site overrides win over the theme’s copy.

Configuration

2026-05-27T20:59:11.669095985Z

juicergallery reads its configuration from three places:

A small set of top-level site keys (the same ones every juicer theme uses, plus a few gallery-specific ones for the topbar / footer).
A namespaced [juicergallery] table for theme-specific palette + sizing overrides.
Per-section frontmatter — galleries are top-level sections whose _index.md carries cover, summary, and photos: lists.

Quick example

title    = "Hella Studio"
tagline  = "Photography, Reykjavík"
author   = "Hella Carlsen"
baseURL  = "https://hellastudio.example"
theme    = "juicergallery"

[images]
enabled = true
widths  = [480, 960, 1600]
formats = ["webp", "original"]
quality = 78

[[topnav]]
label = "Work"
url   = "/"

[[topnav]]
label = "About"
url   = "/about/"

[contact]
email    = "studio@hellastudio.example"
location = "Reykjavík, Iceland"

A minimal gallery (content/iceland-2024/_index.md):

---
title: Iceland 2024
date: 2024-09-15
cover: /img/iceland/cover.jpg
summary: A two-week loop around the ring road.
photos:
  - src: /img/iceland/skogafoss.jpg
    alt: Skógafoss at golden hour
    caption: Skógafoss, day one
  - /img/iceland/diamond-beach.jpg
---

Optional prose body — context, equipment notes, trip narrative.

And a root index that opts into the home cover-grid (content/_index.md):

---
title: Hella Studio
layout: home
---

Optional intro paragraph shown above the cover grid.

That’s enough to render the home grid, each gallery detail, and a static prose page or two.

Top-level keys

Standard juicer keys plus a few gallery-specific ones.

Key	Type	Default	Notes
`title`	`String`	required	Brand text in topbar + footer; `<title>` element.
`tagline`	`String`	unset	Italic subtitle next to the brand in the topbar; appended to `<title>` when the page title equals the site title.
`description`	`String`	unset	Default `<meta name="description">` for pages that don’t set their own `summary`.
`author`	`String`	unset	Footer name + copyright line. Falls back to `title`.
`baseURL`	`String`	required	Standard juicer key.
`theme`	`String`	required	Set to `"juicergallery"`.
`favicon`	`String`	unset	Path to a favicon.
`hideJuicerCredit`	`Boolean`	`false`	Set `true` to remove the “Built with juicer” line in the footer.
`topnav`	`[[topnav]]`	unset	Array of `{label, url}` entries shown in the topbar.
`contact`	`Table`	unset	`{email, location}` — shown in the footer brand block.
`links`	`[[links]]`	unset	Array of `{label, url}` entries shown in the footer.
`[images]`	`Table`	unset	Enables the image-variants pipeline. See the reference for the full surface — required for responsive `<picture>` markup.

Per-page frontmatter (gallery sections)

Key	Type	What
`title`	`String`	Required — the gallery’s display name.
`date`	`String`	Used for sort order on the home cover-grid (newest first).
`cover`	`String`	Path to the cover image. Required for the gallery to appear on the home grid.
`coverAlt`	`String`	Alt text for the cover image. Falls back to the title.
`summary`	`String`	Short description shown on the cover card and as `<meta name="description">`.
`photos`	`List`	List of photos. Each entry is either a string (path) or a `{src, alt, caption}` map.

`[juicergallery]` palette + typography overrides

[juicergallery]
brand        = "#1f2937"   # ink near-black# ink near-black
brandStrong  = "#0b1220"
accent       = "#b45309"   # amber hover accent# amber hover accent
fontSans     = "'Inter', system-ui, sans-serif"
fontSerif    = "'Cormorant Garamond', Georgia, serif"
gutter       = "0.6rem"    # tighter gutter → denser masonry# tighter gutter → denser masonry

# Dark-mode overrides (applied under [data-theme="dark"])# Dark-mode overrides (applied under [data-theme="dark"])
brandDark        = "#f3f1ec"
brandStrongDark  = "#ffffff"
accentDark       = "#f59e0b"

Token	Default	What
`brand`	`#1f2937`	Primary ink color.
`brandStrong`	`#0b1220`	Hover / emphasis ink.
`brandSoft`	`#e5e7eb`	Soft surface tint.
`accent`	`#b45309`	Hover / focus accent (amber).
`fontSans`	system stack	Body + UI font.
`fontSerif`	system serif	Headings + brand.
`gutter`	`1rem`	Masonry column gap. Drop to `0.5rem` for a denser feel.

See Reference → Theming for the shared theming model — the [<theme>] table contract, the customCSS chain, file-replacement override pattern.

Configuration

2026-05-27T20:59:11.669095985Z

juicerdocs reads its configuration from two places in site.toml:

A small set of top-level site keys (the same ones juicer itself uses for things like the page title and the showCopyright flag).
A namespaced [juicerdocs] table for theme-specific knobs — logo, brand colors, dark-mode overrides.

Anything you don’t set keeps the theme’s defaults. Themes can read from any TOML namespace; juicerdocs uses [juicerdocs] so it doesn’t collide with the keys other themes might want.

Quick example

title           = "My Project"
author          = "Acme Inc."
baseURL         = "https://docs.acme.example/"

theme           = "juicerdocs"
headingShift    = 0
showCopyright   = true

[juicerdocs]
logo            = "/acme-logo.png"
brand           = "#3b82f6"        # blue-500# blue-500
brandStrong     = "#2563eb"        # blue-600# blue-600
brandSoft       = "#dbeafe"        # blue-100# blue-100
accent          = "#0891b2"        # cyan-600# cyan-600
leaf            = "#10b981"        # emerald-500# emerald-500

# Dark-mode overrides (optional; sensible defaults derived from the lights)# Dark-mode overrides (optional; sensible defaults derived from the lights)
brandDark       = "#60a5fa"
brandStrongDark = "#93c5fd"
brandSoftDark   = "rgb(59 130 246 / .12)"
accentDark      = "#22d3ee"
leafDark        = "#34d399"

Top-level keys (read by juicerdocs)

Key	Type	Default	What it does
`title`	string	`"Untitled"`	Wordmark in the topbar; appears in `<title>` tags and the footer
`author`	string	`"Unnamed"`	Footer copyright (only when `showCopyright = true`)
`baseURL`	string	(required)	Used for absolute permalinks, sitemap, OpenGraph
`theme`	string	(required)	Set this to `"juicerdocs"` to activate the theme
`headingShift`	int	`2`	The juicerdocs layout already provides an outer `<h1>{{ .page.title }}</h1>`, so set this to `0` for `## Foo` markdown to render as `<h2>` (the natural docs-author convention)
`showCopyright`	bool	`false`	When true, the footer renders a `© {{ .site.author }}` line beside the “Built with Juicer” attribution

`[juicerdocs]` keys

Logo

Key	Type	Default	What
`juicerdocs.logo`	string	`"/juicer-logo.png"`	Path (relative to your site root) of the logo image. Drop your file into `<src>/static/` and point this at it. Used in the topbar, the hero on the home page, the 404 page, and as the favicon.

The default value points at the bundled juicer-logo.png shipped with the theme — fine if you’re previewing juicerdocs on its own, but you’ll want your own logo for any real deployment.

Hero call-to-action

Key	Type	Default	What
`juicerdocs.getStarted`	bool	`false`	When true, the homepage hero shows a primary “Get started” button linking to `/getting-started/`. Leave unset for sites that don’t have a getting-started section.

The hero also shows a secondary “Star on GitHub” button when the top-level repoURL is set (see Theming reference → Site-wide chrome keys). When both are off — getStarted unset and no repoURL — the action row collapses entirely and the hero ends at its summary paragraph (no reserved empty space).

Brand colors (light mode)

Key	Type	Default	What
`juicerdocs.brand`	color	`#d61472`	Primary brand color — links, button fills, sidebar active borders, hero gradient start
`juicerdocs.brandStrong`	color	`#a30d57`	Hover state for primary buttons + emphasized links
`juicerdocs.brandSoft`	color	`#fce7f3`	Soft brand tint — sidebar hover, brand-soft callout backgrounds, badges
`juicerdocs.accent`	color	`#6f1f9e`	Secondary accent — hero gradient end, decorative highlights
`juicerdocs.leaf`	color	`#65a30d`	“Confirmation green” — copy-button “copied” state, success indicators

Any CSS color expression works: hex (#...), rgb(...), hsl(...), oklch(...), color-mix(...), named colors. The values are dropped into <style> declarations, so anything CSS would accept here works.

Brand colors (dark mode overrides)

Key	Type	Default
`juicerdocs.brandDark`	color	`#ec4899`
`juicerdocs.brandStrongDark`	color	`#f472b6`
`juicerdocs.brandSoftDark`	color	`rgb(236 72 153 / .12)`
`juicerdocs.accentDark`	color	`#c084fc`
`juicerdocs.leafDark`	color	`#84cc16`

These override the light-mode values when the user toggles dark mode (or the page loads with the prefers-color-scheme: dark system preference). Set just the ones you want to differ — anything you leave out keeps its light-mode value, which is almost certainly wrong in dark mode for the brand pinks/blues, so it’s worth setting all five.

Tip

Picking a palette. A handy starting point: pick a brand hue, then derive brandStrong (≈10% darker), brandSoft (very light tint at ~10% lightness), brandDark (≈10% lighter — dark mode wants more luminance), brandStrongDark (slightly lighter still), brandSoftDark (transparent overlay at ~12% alpha). Tools like oklch.com and coolors.co make this fast.

Where the values land

The <head> partial emits a <style> block immediately after juicerdocs.css, redefining only the variables you’ve set:

```css: root {

–jd-brand: #3b82f6; /* from juicerdocs.brand / –jd-brand-strong: #2563eb; / from juicerdocs.brandStrong / / … / } [data-theme=”dark”] { –jd-brand: #60a5fa; / from juicerdocs.brandDark / / … */ }


Anything not set falls through to the defaults declared at the top of `juicerdocs.css`. The theme always toggles between light and dark via the `data-theme` attribute on `<html>`, set by the pre-paint script in `<head>`.

## Going beyond config

Drop a file with the same path under your own site to override anything in the theme — this is the ordinary [theme overlay](/concepts/themes/) pattern:

| You want to change… | Override at… |
|---------------------|--------------|
| The topbar          | `<src>/partials/topbar.html` |
| The footer markup   | `<src>/partials/footer.html` |
| The "Note" callout  | `<src>/shortcodes/note.html` |
| The 404 page        | `<src>/layouts/_default/404.html` |
| Custom CSS          | `<src>/static/site.css` (and link it from your overridden `head.html`) |

Site files **always** win over theme files, so overrides are a one-file-at-a-time operation — no forking the theme.

## SEO

Every juicer theme ships a shared SEO partial (`partials/seo.html`) that emits the standard meta block: description (with site-level fallback), canonical link, author meta, robots `noindex`, OpenGraph + Twitter cards (via the `ogTags` builtin), Atom feed discovery, and theme-specific JSON-LD. The engine separately writes `sitemap.xml` and `robots.txt`.

### Site-wide keys

```toml
description = "Reference and how-to docs for the juicer static site generator."
ogImage     = "/og/default.png"

robots   = true
noindex  = false                  # set true for staging/preview domains
disallow = ["/internal/"]

Per-page frontmatter

---
title: Configuration reference
summary: A one-sentence dek for search results and OG cards.
image: /img/og/configuration.png
ogTitle: A snappier social headline
ogDescription: Tightened for socials
noindex: true   # excluded from sitemap, JSON-LD suppressed, <meta robots> emitted
---

Structured data emitted

juicerdocs emits TechArticle on every page (more specific than Article; surfaces in Google’s developer-doc carousel and on Stack Overflow’s right-rail panel for tagged terms):

Page	Schema
Root section	`WebSite`
Every other page	`TechArticle`
Any page with ancestors	`BreadcrumbList` (especially valuable for docs — Google often uses it for the per-result hierarchy)

noindex: true suppresses ALL JSON-LD on that page.

Overriding the SEO partial

Drop a file at <src>/partials/seo.html (or seo-jsonld.html for just the structured-data part). Site overrides win over the theme’s copy.

Configuration

2026-05-27T20:59:11.669095985Z

juicercook reads its configuration from three places:

A small set of top-level site keys (the same ones every juicer theme uses).
A namespaced [juicercook] table for palette overrides and the home-page category strip.
Per-recipe frontmatter — structured fields that drive both the rendered card and the Recipe JSON-LD.

Quick example

title    = "Elder & Ash"
tagline  = "A small home cooking website"
author   = "Hanna Petrescu"
baseURL  = "https://elderandash.example"
theme    = "juicercook"

# Image variants — responsive <picture> markup on every recipe hero# Image variants — responsive <picture> markup on every recipe hero
# and card.# and card.
[images]
enabled = true
widths  = [480, 960, 1600]
formats = ["webp", "original"]
quality = 78

[[topnav]]
label = "Recipes"
url   = "/"

[[juicercook.categories]]
label = "All"
url   = "/"

[[juicercook.categories]]
label = "Breads"
url   = "/breads/"

[[juicercook.categories]]
label = "Desserts"
url   = "/desserts/"

A recipe (content/breads/sourdough.md):

---
title: Sourdough loaf
date: 2024-03-12
servings: 1 loaf
prepTime: PT30M
cookTime: PT45M
image: /img/sourdough.jpg
imageAlt: Crusty boule with an open crumb
summary: A reliable everyday loaf — 25 % whole wheat, 70 % hydration.
ingredients:
  - 500 g bread flour
  - 350 g water
  - 100 g active starter
  - 10 g sea salt
instructions:
  - Mix flour and water; rest 30 minutes (autolyse).
  - Add starter and salt; mix.
  - Bulk ferment 4–6 hours.
tags: [bread, sourdough]
---

Optional body content goes here.

Top-level keys

Key	Type	Default	Notes
`title`	`String`	required	Brand text in topbar + footer; `<title>` element.
`tagline`	`String`	unset	Italic subtitle in the topbar.
`description`	`String`	unset	Default `<meta name="description">`.
`author`	`String`	unset	Footer + JSON-LD author.
`baseURL`	`String`	required	Standard juicer key.
`theme`	`String`	required	Set to `"juicercook"`.
`favicon`	`String`	unset	Path to a favicon.
`hideJuicerCredit`	`Boolean`	`false`	Set `true` to remove the “Built with juicer” line.
`topnav`	`[[topnav]]`	unset	Topbar nav entries.
`links`	`[[links]]`	unset	Footer link entries.
`[images]`	`Table`	unset	Image-variants pipeline. Strongly recommended — the hero and recipe-card images use it.

Per-recipe frontmatter

Key	Type	What
`title`	`String`	Required.
`date`	`String`	Home-page recency ordering. Also `datePublished` in JSON-LD.
`servings`	`String`	“1 loaf”, “4–6”, etc. Maps to `recipeYield`.
`prepTime`	`String`	ISO 8601 duration — `PT30M`, `PT2H`, `P1D`.
`cookTime`	`String`	ISO 8601 duration.
`totalTime`	`String`	ISO 8601 duration. Optional.
`image`	`String`	Hero photo path.
`imageAlt`	`String`	Alt text. Falls back to the title.
`summary`	`String`	Card summary, `<meta name="description">`, JSON-LD description.
`category`	`String`	`recipeCategory` — `Dessert`, `Main`, `Side`, etc.
`cuisine`	`String`	`recipeCuisine` — `Italian`, `Indian`, etc.
`ingredients`	`List`	One string per ingredient line.
`instructions`	`List`	One string per numbered step.
`photos`	`List`	Optional process photos. Each entry is a string (path) or `{src, alt, caption}` map. Renders below the recipe card.
`tags`	`List`	Drives `/tags/<slug>/` archives.

`[juicercook]` palette overrides

[juicercook]
brand        = "#7a2e10"   # terracotta# terracotta
brandStrong  = "#4a1908"
accent       = "#c0571d"   # paprika# paprika
fontSans     = "'Inter', system-ui, sans-serif"
fontSerif    = "'Playfair Display', Georgia, serif"

# Home-page category chips# Home-page category chips
[[juicercook.categories]]
label = "All"
url   = "/"

[[juicercook.categories]]
label = "Breads"
url   = "/breads/"

Configuration

2026-05-27T20:59:11.669095985Z

juicerchurch reads its configuration from three places:

A small set of top-level site keys (the same ones every juicer theme uses, plus a few church-specific ones for services / visit info).
A namespaced [juicerchurch] table for theme-specific palette + sizing overrides.
Per-page frontmatter for sermons, events, ministries, and photo albums.

Quick example

A minimal site.toml that produces a credible parish site:

title    = "St. Stephen's Parish"
tagline  = "Anglican community, Riverdale."
author   = "St. Stephen's Parish"
baseURL  = "https://example.com"
theme    = "juicerchurch"

calendarMonths = 6
eventsSection  = "events"

[visit]
address = "120 River St"
city    = "Toronto"
state   = "ON"
zip     = "M4M 2P3"
mapURL  = "https://maps.example.com/ststephens"

[[services]]
day   = "Sun"
time  = "8:00 AM"
label = "Said Eucharist (BCP)"

[[services]]
day   = "Sun"
time  = "10:30 AM"
label = "Sung Eucharist"

[[services]]
day   = "Wed"
time  = "7:00 PM"
label = "Evening Prayer"

[juicerchurch]
brand     = "#2c5282"   # muted blue# muted blue
fontSerif = "'Source Serif 4', Georgia, serif"

A typical sermon page (content/sermons/2024-12-24-christmas-eve.md):

---
title: "On Comfort, and Why It Comes from a Manger"
date: 2024-12-24
author: ann
scripture: "Isaiah 9:2–7; Luke 2:1–14"
audioURL: "/audio/2024-12-24.mp3"
audioDuration: "23:14"
videoURL: "https://youtube.com/watch?v=..."
videoDuration: "24:02"
summary: A meditation on Christmas Eve, on what comfort means and where it comes from.
---

The transcript or summary body goes here.

A typical ministry page (content/ministries/food-bank.md):

---
title: Riverdale Food Bank
layout: ministry
leader: Mara Sanderson
meets: "Saturdays, 10am–noon"
contact: "foodbank@ststephens.example"
---

The ministry's narrative — who, what, why, how to get involved.

Top-level keys

Key	Type	Default	Notes
`title`	`String`	required	Brand text in topbar + footer; `<title>` element.
`tagline`	`String`	unset	Italic subtitle next to the brand.
`author`	`String`	unset	Footer copyright. Falls back to `title`.
`baseURL`	`String`	required	Standard juicer key.
`theme`	`String`	required	Set to `"juicerchurch"`.
`favicon`	`String`	unset	Path to a favicon.
`hideJuicerCredit`	`Boolean`	`false`	Set `true` to remove the “Built with juicer” line.
`customCSS`	`[String]`	unset	Site stylesheets loaded after the theme CSS.
`eventsSection`	`String`	`"events"`	Section name juicer treats as events; populates `.site.events` and `.site.calendar`. See Configuration → Calendar / events features.
`calendarMonths`	`Int`	`12`	Months of calendar grid `.site.calendar` pre-computes.
`visit`	`Object`	unset	`{address, city, state, zip, mapURL}` — surfaced in the footer on every page.
`services`	`Array`	unset	Regular weekly services: `[[services]]` rows of `{day, time, label}`. Surfaced in the home page hero and the footer.

Palette + token overrides — `[juicerchurch]`

All optional. Anything you don’t set keeps the muted-blue defaults.

Key	CSS variable	Notes
`brand`	`--brand`	Primary brand accent.
`brandStrong`	`--brand-strong`	Hover-emphasis.
`brandSoft`	`--brand-soft`	Subtle paper-tinted backgrounds.
`accent`	`--accent`	Warm secondary.
`leaf`	`--leaf`	“Today” indicator on the calendar grid.
`brandDark` …	dark counterparts	One per light token.
`fontSans`	`--font-sans`	Body / UI / nav face.
`fontSerif`	`--font-serif`	Headings, sermon titles.
`fontMono`	`--font-mono`	Scripture references, calendar cells.
`measure`	`--measure`	Prose column max-width. Default `38rem`.
`gutter`	`--gutter`	Outer padding around content blocks.
`radiusLg`	`--radius-lg`	Large border-radius.

Per-page frontmatter

Sermon pages

Sermons are dated, single-author posts that opt into the sermon layout. They live under content/sermons/ and surface on the sermon archive page.

Key	Type	What
`layout`	`String`	`sermon`. The sermon-archive page uses `layout: sermon-archive`.
`title`	`String`	Sermon title.
`date`	ISO	Required. Drives sort order and archive grouping.
`author`	`String`	Single preacher ID — references `[[authors]]` in `site.toml`.
`scripture`	`String`	Scripture reference text (`"Isaiah 9:2–7; Luke 2:1–14"`). Rendered in a tagged block above the body.
`audioURL`	`String`	Path or absolute URL to an audio file (mp3/m4a). Theme injects an `<audio>` element.
`audioDuration`	`String`	Display duration (`"23:14"`). Shown next to the audio control.
`videoURL`	`String`	Path or absolute URL to a video (YouTube / Vimeo / mp4).
`videoDuration`	`String`	Display duration.
`series`	`String`	(Engine feature.) Sermons share series support with `juicerblog` — Advent series, Lent series, etc.
`summary`	`String`	Short blurb on the archive page.

Event pages

Event pages live in the eventsSection (default events).

Key	Type	What
`date`	ISO string	Required for an event to surface in `.site.events`.
`eventTime`	`String`	Display time (`"7 PM"`, `"6:30–8 PM"`).
`eventLocation`	`String`	Address or named location.
`recurring`	`String`	`"weekly"` for weekly recurrence. Expands onto every matching weekday in `.site.calendar`.
`recurringDay`	`String`	Day name for recurrence. Defaults to the start date’s day of week.
`photos`	`[String]` or `[Object]`	Photos.

Ministry pages

Key	Type	What
`layout`	`String`	`ministry`.
`title`	`String`	Ministry name.
`leader`	`String`	Person’s name (free text, not a registry ID — ministries often have non-clergy leaders).
`meets`	`String`	Display string for meeting cadence (`"Saturdays, 10am–noon"`).
`contact`	`String`	Email / phone / freeform contact info.

Photo albums

Same as juicercafe — layout: album for one event’s gallery, layout: photo-album for the site-wide aggregate.

Going beyond config

Drop a file with the same path under your own site to override anything in the theme — this is the ordinary theme overlay pattern:

You want to change…	Override at…
The topbar	`<src>/partials/topbar.html`
The footer	`<src>/partials/footer.html`
The calendar grid	`<src>/partials/month-grid.html`
The photo grid	`<src>/partials/photo-grid.html`
The 404 page	`<src>/layouts/_default/404.html`
Custom CSS	`<src>/static/site.css` (and list it under `customCSS` in `site.toml`)

Site files always win over theme files, so overrides are a one-file-at-a-time operation — no forking the theme.

SEO

Site-wide keys

description = "Trinity Community Church — Sunday services at 9 and 11, Wednesday Bible study at 7."
ogImage     = "/og/sanctuary.jpg"

robots   = true
noindex  = false
disallow = ["/admin/"]

# Optional: Church JSON-LD on the homepage. Subtype of PlaceOfWorship —# Optional: Church JSON-LD on the homepage. Subtype of PlaceOfWorship —
# helpful for Google Maps Knowledge Panel.# helpful for Google Maps Knowledge Panel.
[church]
phone   = "+1-555-0100"
address = "412 Maple Street, Springfield IL 62701"
image   = "/img/sanctuary.jpg"

Per-page frontmatter

---
title: The Sermon on the Mount
summary: A one-sentence dek for search results and OG cards.
date: 2026-04-12
author: pastor-rob
image: /img/sermons/sermon-on-mount.jpg
ogTitle: A snappier social headline
ogDescription: Tightened for socials
noindex: true   # excluded from sitemap, JSON-LD suppressed, <meta robots> emitted
---

Structured data emitted

Page	Schema
Root section	`WebSite` (+ `Church` when `[church]` is set in `site.toml`)
Dated non-section page	`Article` (with author / image / dateISO)
Any page with ancestors	`BreadcrumbList`

noindex: true suppresses ALL JSON-LD on that page.

Overriding the SEO partial

Drop a file at <src>/partials/seo.html (or seo-jsonld.html for just the structured-data part). Site overrides win over the theme’s copy.

Configuration

2026-05-27T20:59:11.669095985Z

juicercafe reads its configuration from three places:

A small set of top-level site keys (the same ones every juicer theme uses, plus a few café-specific ones for hours / visit info).
A namespaced [juicercafe] table for theme-specific palette + sizing overrides.
Per-page frontmatter for menus, events, photo albums, and the “working on it” page.

Quick example

A minimal site.toml that produces a credible café page:

title    = "Magpie & Pearl"
tagline  = "Coffee, pastry, books — Lawrence Park."
author   = "Magpie & Pearl"
baseURL  = "https://example.com"
theme    = "juicercafe"

[visit]
address = "240 King St E"
city    = "Lawrence Park"
state   = "ON"
zip     = "M4S 1A1"
mapURL  = "https://maps.example.com/magpie"

[[hours]]
day  = "Mon"
open = "07:00"
close = "16:00"

[[hours]]
day  = "Tue"
open = "07:00"
close = "16:00"

# ... (Wed–Fri similar)# ... (Wed–Fri similar)

[[hours]]
day    = "Sat"
open   = "08:00"
close  = "17:00"

[[hours]]
day    = "Sun"
closed = true

[juicercafe]
brand     = "#9c3022"   # brick red# brick red
fontSerif = "'Source Serif 4', Georgia, serif"

A typical menu section page (content/menu/coffee.md):

---
title: Coffee
layout: menu-section
weight: 10
items:
  - { name: "Pour-over", price: "5.00", description: "Single-origin, brewed to order." }
  - { name: "Espresso", price: "3.50", description: "Double shot, in a small cup." }
  - { name: "Cortado", price: "4.50" }
---

A typical event page (content/events/picnic-may.md):

---
title: Spring Picnic
date: 2025-05-15T12:00:00
eventTime: "noon–4pm"
eventLocation: "Lawrence Park bandshell"
summary: Annual neighborhood picnic. Bring a side.
---

The full event writeup goes here.

Top-level keys

Standard juicer keys plus a few café-specific ones.

Key	Type	Default	Notes
`title`	`String`	required	Brand text in topbar + footer; `<title>` element.
`tagline`	`String`	unset	Italic subtitle next to the brand in the topbar; appended to `<title>` when the page title equals the site title.
`author`	`String`	unset	Footer copyright. Falls back to `title`.
`baseURL`	`String`	required	Standard juicer key.
`theme`	`String`	required	Set to `"juicercafe"`.
`favicon`	`String`	unset	Path to a favicon.
`hideJuicerCredit`	`Boolean`	`false`	Set `true` to remove the “Built with juicer” line in the footer.
`customCSS`	`[String]`	unset	Site stylesheets loaded after the theme CSS. See Theming → Layer 2.
`visit`	`Object`	unset	`{address, city, state, zip, mapURL}` — the place’s physical address, surfaced in the footer on every page.
`hours`	`Array`	unset	Day-of-week hours: `[[hours]]` rows of `{day, open?, close?, closed?, note?}`. Drives the topbar “Open now” badge and the footer hours block.

Hours-row shape

Each [[hours]] row describes one day of the week:

Field	Type	Notes
`day`	`String`	`Mon`, `Tue`, …, `Sun`. Used both for display and for the “Open now” computation.
`open`	`String`	`"HH:MM"` 24-hour. Required when not `closed`.
`close`	`String`	`"HH:MM"` 24-hour. Required when not `closed`.
`closed`	`Boolean`	When `true`, the day shows as “closed” and the hours fields are ignored.
`note`	`String`	Optional small note, e.g. `"holiday hours"`, `"breakfast only"`.

Palette + token overrides — `[juicercafe]`

All optional. Anything you don’t set keeps the warm-paper / brick-red defaults. The full mapping (which token drives which CSS variable) is documented in Theming — juicercafe follows the same pattern as the other themes.

Key	CSS variable	Notes
`brand`	`--brand`	Primary brand accent — link hover, “Open now” pill, active topbar entries.
`brandStrong`	`--brand-strong`	Hover-emphasis on brand-coloured elements.
`brandSoft`	`--brand-soft`	Subtle paper-tinted backgrounds.
`accent`	`--accent`	Warm secondary — used sparingly on CTAs.
`leaf`	`--leaf`	“Open now” green; success states.
`brandDark` …	dark counterparts	One per light token.
`fontSans`	`--font-sans`	Body / UI / nav face.
`fontSerif`	`--font-serif`	Headings, brand.
`fontMono`	`--font-mono`	Prices on menu pages.
`measure`	`--measure`	Prose column max-width. Default `38rem`.
`gutter`	`--gutter`	Outer padding around content blocks.
`radiusLg`	`--radius-lg`	Large border-radius (cards, hero images).

Per-page frontmatter

The menu has a two-level structure: a [layout: menu] page on /menu/_index.md and one [layout: menu-section] page per menu section (/menu/coffee.md, /menu/pastry.md, …). Each menu-section page lists its items inline.

Key	Type	What
`layout`	`String`	`menu` for the menu landing; `menu-section` for each section.
`title`	`String`	Section heading on the menu page.
`weight`	`Int`	Sort order of the section within the full menu. Lower first.
`items`	`[Object]`	Items in this section. Each `{name, price, description?, vegan?, gf?}`.

Event pages

Event pages live in the eventsSection (default events).

Key	Type	What
`date`	ISO string	Required for an event to surface in `.site.events`.
`eventTime`	`String`	Display time (`"noon–4pm"`, `"7pm–10pm"`).
`eventLocation`	`String`	Address or named location.
`recurring`	`String`	`"weekly"` for weekly recurrence. Expands the event onto every matching weekday in `.site.calendar`.
`recurringDay`	`String`	Day name for recurrence. Defaults to the start date’s day of week.
`photos`	`[String]` or `[Object]`	Photos for the event — surface on `.site.photos` and on the event page itself.

Photo album pages

A [layout: album] page renders a 3-up image grid; a [layout: photo-album] page renders the site-wide aggregated .site.photos list. Use the first for one event’s gallery, the second for “every photo on the site, sorted by date.”

Key	Type	What
`layout`	`String`	`album` (one event’s photos) or `photo-album` (the site-wide grid).
`photos`	`[Object]`	The album’s photos. Each `{src, caption?, alt?}`.

“Working on it” pages

A [layout: working] page lists pending projects — lease applications, renovations, hiring. Each page’s working: frontmatter is a list.

Key	Type	What
`layout`	`String`	`working`.
`working`	`[Object]`	Projects. Each `{title, status, body}` — `status` is a short label (`"in review"`, `"q2 2025"`, etc.).

Going beyond config

Drop a file with the same path under your own site to override anything in the theme — this is the ordinary theme overlay pattern:

You want to change…	Override at…
The topbar	`<src>/partials/topbar.html`
The footer	`<src>/partials/footer.html`
The hours widget	`<src>/partials/hours-widget.html`
The photo grid	`<src>/partials/photo-grid.html`
The 404 page	`<src>/layouts/_default/404.html`
Custom CSS	`<src>/static/site.css` (and list it under `customCSS` in `site.toml`)

Site files always win over theme files, so overrides are a one-file-at-a-time operation — no forking the theme.

SEO

Site-wide keys

description = "Hand-pulled espresso and tiny-batch pastries on Elgin Street."
ogImage     = "/og/default.jpg"

robots   = true
noindex  = false
disallow = ["/private/"]

# Optional: LocalBusiness JSON-LD on the homepage. Any subtype works# Optional: LocalBusiness JSON-LD on the homepage. Any subtype works
# (CafeOrCoffeeShop, Restaurant, Bakery — see schema.org/LocalBusiness).# (CafeOrCoffeeShop, Restaurant, Bakery — see schema.org/LocalBusiness).
[business]
type    = "CafeOrCoffeeShop"
phone   = "+1-555-0100"
address = "123 Elgin Street, Ottawa, ON K2P 1L4"
image   = "/img/storefront.jpg"

Per-page frontmatter

---
title: Espresso 101
summary: A one-sentence dek for search results and OG cards.
image: /img/menu/espresso.jpg
ogImage: /img/menu/espresso-social.jpg
ogTitle: Espresso, explained
ogDescription: Tightened for socials
noindex: true   # excluded from sitemap, JSON-LD suppressed, <meta robots> emitted
---

Structured data emitted

Page	Schema
Root section	`WebSite` (+ `LocalBusiness` when `[business]` is set in `site.toml`)
Non-section page with `date:`	`Article`
Any page with ancestors	`BreadcrumbList`

noindex: true suppresses ALL JSON-LD on that page.

Overriding the SEO partial

Drop a file at <src>/partials/seo.html (or seo-jsonld.html for just the structured-data part). Site overrides win over the theme’s copy.

Configuration

2026-05-27T20:59:11.669095985Z

juicerblog reads its configuration from three places:

A small set of top-level site keys (the same ones every juicer theme uses).
A namespaced [juicerblog] table for theme-specific palette overrides.
Per-page frontmatter for opt-in conventions like the static-page flag and the homepage layout selector.

Anything you don’t set keeps the theme’s defaults. juicerblog uses [juicerblog] so it doesn’t collide with keys other themes might want.

Quick example

A complete site.toml exercising every juicerblog-aware feature:

title    = "My blog"
tagline  = "a place for prose"
author   = "Ed Maxedon"
baseURL  = "https://example.com"

theme    = "juicerblog"
paginate = 5
sortBy   = "date"

# Every post lives at /<year>/<month>/<slug>/.# Every post lives at /<year>/<month>/<slug>/.
[permalinks]
posts = ":year/:month/:slug/"

# Year + month archive pages.# Year + month archive pages.
dateArchives = true

# Author registry — see [Blogging features → Author registry] for the# Author registry — see [Blogging features → Author registry] for the
# full data shape. Each id is referenced from per-post `author:` /# full data shape. Each id is referenced from per-post `author:` /
# `authors:` frontmatter.# `authors:` frontmatter.
[[authors]]
id     = "ed"
name   = "Ed Maxedon"
bio    = "Writes about Scala, languages, and the craft of small tools."
avatar = "/img/avatar-ed.png"

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

# Optional palette overrides. Defaults are warm-neutral (amber + indigo).# Optional palette overrides. Defaults are warm-neutral (amber + indigo).
[juicerblog]
brand  = "#0f766e"  # teal-700# teal-700
accent = "#7c3aed"  # violet-600# violet-600

Top-level keys

Standard juicer keys, with a note on how juicerblog uses each:

Key	Type	Default	What
`title`	string	`"Untitled"`	Wordmark in the topbar; appears in `<title>` tags and the footer
`tagline`	string	(none)	Italic line beside the wordmark; rendered as the hero subtitle on the homepage
`author`	string	`"Unnamed"`	Footer copyright line; also drives the site-wide Atom feed `<author>` element
`baseURL`	string	(required)	Used for absolute permalinks, sitemap, OpenGraph, atom feeds
`theme`	string	(required)	Set this to `"juicerblog"`
`paginate`	int	`10`	Posts per page on the home + archive listings. juicerblog renders 4–5 well; 10+ starts feeling long
`sortBy`	string	`"weight"`	Set to `"date"` for a blog. juicerblog’s home + archive listings respect this

The [permalinks], dateArchives, and [[authors]] tables are engine-level features documented at Blogging features. juicerblog renders the layouts that surface them; the engine’s job is unchanged.

`[juicerblog]` keys

A small table for palette overrides. Defaults are:

Key	Type	Default	What
`juicerblog.brand`	color	`#c2410c`	Primary brand color — links on hover, brand pill backgrounds, reading-progress bar
`juicerblog.accent`	color	`#4338ca`	Default link color in prose (indigo-700 — readable against cream paper)
`juicerblog.leaf`	color	`#16a34a`	“Confirmation green” — the copy-button “Copied” flash, success badges

Any CSS color expression works: hex, rgb(...), hsl(...), oklch(...), named colors. Values are dropped into a <style> block in <head> immediately after juicerblog.css, redefining the named CSS variables.

Note

Dark-mode variants of these tokens are derived automatically by the theme — the dark palette tunes the same hues lighter and slightly cooler so they don’t burn against the dark background. The current build doesn’t expose dark-mode overrides as separate config keys; if you need radically different colors per theme, override static/juicerblog.css from your site’s static/ directory.

Per-page frontmatter

Three frontmatter conventions are juicerblog-specific (the engine doesn’t read them; the theme branches on them):

Field	Type	What
`static`	bool	When `true`, the page renders without post chrome — no date/reading-time line, no series badge, no prev/next nav. Use it for about / colophon / contact pages so they look like clean essays, not posts. Pages with `static: true` are also filtered out of the home post list, the per-tag archives, the per-author archives, and `.site.posts` / `.site.pagesByYear`.
`layout`	string	When set, juicer renders the page through `_default/<layout>.html` instead of the default `file.html` / `folder.html`. juicerblog ships two non-default layouts: `home` and `archive`.
`series`	string	(Engine feature.) When set, the post is part of a series — juicerblog adds a progress badge (“Reading on screens · Part 2 of 3”) above the body and an “In this series” sidebar after the body. See Blogging features → Series for the full data shape.

A typical post:

---
title: A whirlwind tour of Scala 3
date: 2024-11-18
author: ed
tags: [scala, language]
summary: Five things Scala 3 gets right.
---

Scala 3 cleans up a decade of accreted complexity…

A static page:

---
title: About this site
author: ed
static: true
summary: Who runs this place and why.
---

This blog exists for one reason…

A homepage:

---
title: My blog
layout: home
---

A short paragraph that renders inside the hero, under the title and tagline.

An archive landing:

---
title: Archive
layout: archive
static: true
summary: Every post on this site, grouped by year.
---

A short intro paragraph that renders above the year-grouped list.

Directory layout

The directories juicerblog cares about under your site root:

my-blog/
├── site.toml
├── content/
│   ├── _index.md            # the homepage (often layout: home)
│   ├── archive.md           # the archive page (layout: archive, static: true)
│   ├── about.md             # static: true
│   └── *.md                 # posts (with date, author, tags, etc.)
├── grammars/
│   ├── scala.tmLanguage.json
│   ├── javascript.tmLanguage.json
│   └── ...
└── static/                  # site-side asset overrides (avatars, og images)
    ├── img/avatar-ed.png
    └── og-default.png

grammars/ is the opt-in for syntax highlighting — covered in its own section below.

Syntax highlighting

juicerblog renders code blocks through juicer’s highlighter integration — TextMate grammars at build time, no JavaScript runtime, no FOUC. The integration is engine-level (any juicer theme benefits); juicerblog ships the .hl-* CSS palette that turns the spans into colors.

To enable highlighting, drop a <lang>.tmLanguage.json file into <src>/grammars/ for each language you want colored:

my-blog/grammars/
├── scala.tmLanguage.json
├── javascript.tmLanguage.json
├── python.tmLanguage.json
└── rust.tmLanguage.json

The <lang> part of the filename matches the fence’s language tag — a fenced block opened with ```scala looks for grammars/scala.tmLanguage.json. Languages with no matching grammar render as plain <pre><code> (no error).

Tip

Where to get grammars. Almost every VS Code language extension ships a TextMate grammar file. Grab them from the language’s official VS Code extension repository — for example, scala-lang/vscode-scala-syntax for Scala. Drop the .tmLanguage.json file directly into your grammars/ directory.

Note

Sites with no grammars/ directory pay zero cost. The build doesn’t try to load any highlighter at all. Code blocks render as plain <pre><code>. The theme’s CSS for the .hl-* classes is inert in that case (no .hl-* spans get emitted), so there’s no wasted bytes either.

The classes the theme styles, with their default light-mode colors:

Class	Color (light)	Color (dark)	What kinds of tokens
`.hl-keyword`	`#9a3412`	`#fb923c`	`class`, `def`, `if`, `for`, `match`, `import`, etc.
`.hl-string`	`#166534`	`#86efac`	String literals (single, double, triple)
`.hl-comment`	`#78716c`	`#a8a29e`	Line + block comments (italic)
`.hl-number`	`#b45309`	`#fdba74`	Numeric literals
`.hl-type`	`#1d4ed8`	`#93c5fd`	Type names (capitalized identifiers in most grammars)
`.hl-function`	`#6d28d9`	`#c4b5fd`	Function / method names — when the grammar tags them
`.hl-variable`	inherit	inherit	Variable references
`.hl-operator`	`#44403c`	`#d6d3d1`	`=>`, `::`, etc. — when the grammar tags them
`.hl-punctuation`	`#78716c`	`#a8a29e`	Brackets, commas, semicolons, dots

Override any of these from your site’s static/site.css (loaded after the theme’s stylesheet) if the defaults don’t match your site’s palette.

Going beyond config

Drop a file with the same path under your own site to override anything in the theme — this is the ordinary theme overlay pattern:

You want to change…	Override at…
The topbar nav	`<src>/partials/topbar.html`
The footer markup	`<src>/partials/footer.html`
The byline	`<src>/partials/post-byline.html`
The series sidebar	`<src>/partials/series-nav.html`
The 404 page	`<src>/layouts/_default/404.html`
Custom CSS	`<src>/static/site.css` (and link it from your overridden `head.html`)

Site files always win over theme files, so overrides are a one-file-at-a-time operation — no forking the theme.

SEO

Every juicer theme ships a shared SEO partial (partials/seo.html) that emits the standard meta block: description (with site-level fallback), canonical link, author meta, robots noindex, OpenGraph + Twitter cards (via the ogTags builtin), Atom feed discovery, and theme-specific JSON-LD structured data. The engine separately writes sitemap.xml and robots.txt. This section documents the knobs.

Site-wide keys

description = "A monthly journal of small tools and small wins."   # used as default meta description and JSON-LD site description# used as default meta description and JSON-LD site description
ogImage     = "/og/default.png"                                    # fallback OpenGraph image (absolute URL or site-relative path)# fallback OpenGraph image (absolute URL or site-relative path)

# robots.txt# robots.txt
robots   = true                                                    # default; set false to suppress robots.txt entirely (ship your own in static/)# default; set false to suppress robots.txt entirely (ship your own in static/)
noindex  = false                                                   # default; set true for staging/preview domains — emits Disallow: / for the whole site# default; set true for staging/preview domains — emits Disallow: / for the whole site
disallow = ["/drafts/", "/staging/"]                               # additional Disallow lines (string or array of strings)# additional Disallow lines (string or array of strings)

Per-page frontmatter

---
title: A short post about something
summary: A one-sentence dek for search results and OG cards.
image: /img/post-hero.jpg          # used by ogTags + JSON-LD BlogPosting
ogImage: /img/post-social.jpg      # explicit OG image, wins over `image`
ogTitle: A snappier social headline # explicit OG title, wins over `title`
ogDescription: Tightened for socials # explicit OG description, wins over `summary`
noindex: true                       # excluded from sitemap.xml, JSON-LD suppressed, <meta robots> emitted
---

Structured data emitted

juicerblog emits these JSON-LD @types:

Page	Schema
Root section (`content/_index.md`)	`WebSite`
Non-section page with `date:`	`BlogPosting` (with author / image / dateISO)
Any page with ancestors	`BreadcrumbList` (built from `.page.ancestors`)

noindex: true suppresses ALL JSON-LD on that page — a deliberately-hidden page should not advertise itself to crawlers in any form.

Overriding the SEO partial

To customize, drop a file at <src>/partials/seo.html (or seo-jsonld.html for just the structured-data part). The site override wins over the theme’s copy with no forking.

Configuration

2026-05-27T20:59:11.669095985Z

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

Name	What
`simple`	Flat layout — content, layouts, partials, static all at the source root
`standard`	Hugo-like nested layout (the default)
`norme`	French (Charter-of-the-French-Language compliant) — same as `standard` but with French directory names

Tip

The norme baseline is here because Quebec’s Charter of the French Language requires that public-facing software present primarily in French. Same code, French file names. If your content is bilingual, use this baseline alongside the upcoming i18n feature (Tier 2).

Keys

Identity

Key	Default	What
`title`	`"Untitled"`	Site title; available as `.site.title`
`author`	`"Unnamed"`	Site author; available as `.site.author`
`baseURL`	`"http://localhost:8080"`	Absolute base URL — used for permalinks, sitemap, OpenGraph

Theme

Key	Default	What
`theme`	(none)	Theme name (string) or chain (array of strings). Resolved under `themeDir`
`themeDir`	`"themes"`	Directory holding theme subfolders

Directory layout

Key	`standard` default	What
`contentDir`	`"content"`	Markdown source root
`htmlDir`	`"html"`	Filesystem-only prefix for nested sections; stripped from URLs
`publicDir`	`"public"`	Default output directory
`staticDir`	`"static"`	Verbatim-copied assets
`layoutDir`	`"layouts"`	Templates root
`partialDir`	`"partials"`	Partials root
`shortcodeDir`	`"shortcodes"`	Shortcodes root
`dataDir`	`"data"`	Structured data root — `.toml` / `.yaml` / `*.yml` files here are exposed to templates as `.site.data` (see Template data → `.site.data`). Themes can also ship a `data/` directory; site keys win at the file-leaf granularity.
`excludeDirs`	unset	Extra directories to skip during the site walk. String or array of strings; each entry is a path relative to the source root (`"node_modules"`, `"assets/raw"`). Match is exact-directory only — not a glob pattern.

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

Key	Default	What
`defaultLayout`	`"_default"`	Fallback layout subfolder under `layoutDir`
`baseofLayout`	`"baseof"`	Outer-shell layout filename (without extension)
`fileLayout`	`"file"`	Single-page layout filename
`folderLayout`	`"folder"`	Section-index layout filename
`folderContent`	`"_index"`	Filename (without extension) recognized as the section index

Behavior

Key	Default	What
`stripPrefix`	`true`	Strip leading numeric prefixes from filenames in URLs (`01-foo.md` → `foo`)
`headingShift`	`2`	Add this much to every markdown heading level. The default `2` exists because layouts typically emit an outer `<h1>{{ .page.title }}</h1>` and most theme CSS expects body markdown to start at `<h2>`. Set to `0` when a theme renders the page heading from the markdown body itself.
`feeds`	`true`	Emit Atom and RSS feed files alongside the rendered HTML. Set `false` for sites that don’t want feeds (single-page landings, internal wikis).

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.

Key	Default	What
`languages`	unset (single-language)	Array of language codes the site supports — `["en", "fr", "ja"]`. When unset, juicer is in single-language mode and `.page.lang` is the empty string.
`defaultLanguage`	first entry / `""`	Language used when a page’s URL prefix doesn’t match any of `languages`. Falls back to the first entry of `languages` when not set.

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.

Key	Default	What
`paginate`	(none)	Default slice size for section index pages. When unset, sections render in a single page no matter how many children they have.
`sortBy`	`weight`	Order section pages: `"date"` (newest first), `"title"` (alphabetical), or `"weight"` (juicer’s default — `weight` ascending)
`dateArchives`	`false`	Emit `/<year>/` and `/<year>/<month>/` archive pages from posts’ parsed dates. Requires matching `date-year.html` / `date-month.html` layouts; missing layouts are silent skips. Only pages with explicit `date:` frontmatter are included — mtime-fallback dates don’t pollute the archive.
`dateFormat`	(none)	Reserved for future per-site date-format overrides. Not yet wired up; templates use the built-in `dateLong` / `dateShort` / `dateISO` helpers for now.

Note

Both paginate and sortBy can be overridden per-section by setting the same key on the section’s _index.md frontmatter. So a site that wants 10 posts per page on /posts/ but 30 short notes per page on /notes/ puts paginate = 30 in content/notes/_index.md and leaves the site-wide value at 10.

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.

Key	Default	What
`eventsSection`	`"events"`	Name of the content section juicer treats as events. Pages in this section with explicit `date:` frontmatter populate `.site.events` and `.site.calendar`. The site-wide future-post filter is also exempted for pages in this section so future-dated event detail pages still render to disk.
`calendarMonths`	`12`	How many months `.site.calendar` pre-computes, starting at the current month. Higher values cost build time and HTML size; lower values mean the calendar runs out sooner.

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:

Token	Resolves to
`:slug`	The cleaned filename (`01-foo.md` → `foo` when `stripPrefix = true`)
`:title`	`slugify(.page.title)` — frontmatter title, lowercased and ASCII-folded
`:year`	4-digit year from `.page.date`
`:month`	2-digit month from `.page.date`
`:day`	2-digit day from `.page.date`
`:section`	The section name itself

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.

Note

Permalink templates change both the URL and the on-disk write location of each affected page. Juicer doesn’t keep both copies — only the permalinked path exists in the output tree. So a posts/foo.md with posts = ":year/:slug/" writes only to <dst>/2024/foo/index.html, never to <dst>/posts/foo/index.html.

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:

Provider	Conventional keys
`giscus`	`repo`, `repoId`, `category`, `categoryId`, `mapping`, `reactions`, `theme`
`utterances`	`repo`, `issueTerm`, `label`, `theme`
`disqus`	`shortname`

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.

Note

juicer is static-output-only — it doesn’t proxy comments, store moderation state, or call the provider’s API. The block above is a config slot only. If a provider needs server-side state, that belongs in the provider’s own infrastructure, not in juicer.

`[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

Key	Default	What
`enabled`	`false`	Master switch. `false` → templates that call `imageVariants` get a passthrough-only set with no `<source>` rows.
`widths`	`[320, 640, 960, 1280]`	Target widths in pixels. Widths ≥ the source’s own width are dropped (no upscaling); the source’s exact width is always included.
`formats`	`["webp", "original"]`	Output formats in priority order. Known: `webp`, `avif`, `jpeg`, `png`, `original`. Unknown names are dropped.
`quality`	`80`	Encoder quality (1–100). Used for lossy formats; `png` ignores it.
`cacheDir`	`".image-cache"`	Directory under `dst` where generated variants live. Content-hashed filenames mean re-runs on unchanged sources skip the encoder shell-out.

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"

Top-level key	Default	What
`enabled`	`false`	Master switch. `false` → no pipeline runs, the `asset` builtin returns its input unchanged.
`fingerprint`	`false`	When `true`, juicer inserts the output bytes’ content-hash before the extension: `/css/site.css` → `/css/site.<16-hex>.css`. The `asset` builtin resolves to the fingerprinted URL automatically.

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

Entry kind	Required keys	Optional keys	What
`[[assets.sass]]`	`input`, `output`	`minify`, `logical`	SCSS / Sass → CSS via `sass –no-source-map [–style=expanded
`[[assets.esbuild]]`	`input`, `output`	`minify`, `logical`	JS bundle via `esbuild <in> --bundle [--minify] --outfile=<out>`.
`[[assets.copy]]`	`input`, `output`	`logical`	Byte-for-byte copy (no tool involved). Useful when fingerprinting a file no compiler needs to touch.

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"

Field	Required	What
`id`	yes	Stable url-safe identifier; archive lives at `/authors/<id>/`
`name`	no	Display name
`email`	no	Author email; useful in feed templates
`bio`	no	Short bio used in bylines and author archive headers
`avatar`	no	URL of avatar image — site-relative or absolute
`links[]`	no	Each entry has `label` and `url`; renders as a list of external links

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.

CLI

2026-05-27T20:59:11.669095985Z

Juicer’s CLI has four subcommands: build, serve, config, and theme (with add / upgrade sub-subcommands). Every command runs on JVM, Scala.js (Node), and Scala Native — serve and its live-reload watcher use microserve for cross-platform HTTP and file-watching.

Global options

These apply to every subcommand. Place them before the subcommand name on the command line:

Flag	What
`-b`, `--baseurl <URL>`	Override `baseURL` from the config — typically used in CI for environment-specific URLs (`https://staging.example.com/` vs `https://example.com/`).
`-c`, `--config <name>`	Pick a baseline config: `simple`, `standard` (default), or `norme`. Your `site.toml` overlays on top of the chosen baseline.
`-h`, `--help`	Print usage and exit.
`-v`, `--verbose`	Print step-by-step build progress — layout selection, file walks, what’s being written where. Indispensable when a page is being silently skipped.
`--version`	Print the version and exit.

sbt 'juicerJVM/run --baseurl https://staging.example.com/ build -s docs'
sbt 'juicerJVM/run --config simple build -s notes'
sbt 'juicerJVM/run -v build -s docs'

`build`

Render the site to disk. Output goes to <src>/<publicDir> (default <src>/public/) unless -d overrides.

sbt 'juicerJVM/run build -s docs'
sbt 'juicerJVM/run build -s docs -d _site -b https://juicer.build/'
sbt 'juicerJVM/run build -s blog -D -F'

Flag	Default	What
`-s`, `--source <p>`	`.`	Site source directory.
`-d`, `--dest <p>`	`<src>/<publicDir>`	Output directory. Overrides the `publicDir` config key.
`-D`, `--drafts`	off	Include pages with `draft: true` frontmatter. Drafts are normally invisible to every downstream consumer — TOC, sitemap, search index, section listings.
`-F`, `--future`	off	Include pages whose parsed `date:` is past the current build time. Future-skip applies only to pages with explicit `date:` frontmatter — mtime-fallback dates are never future-skipped. Pages in the `eventsSection` (default `events`) are also exempt from future-skip.

Tip

The classic CI build, e.g. for a GitHub Pages workflow:

sbt 'juicerJVM/run build -s docs -d _site -b https://example.github.io/repo/'

`serve`

Build the site once, then serve it on localhost. Optionally watch the source and rebuild on every change.

sbt 'juicerJVM/run serve -s docs'
sbt 'juicerJVM/run serve -s docs -L'
sbt 'juicerJVM/run serve -s docs --host 0.0.0.0 -p 4000'

Flag	Default	What
`-s`, `--source <p>`	`.`	Site source directory.
`-d`, `--dest <p>`	`<src>/<publicDir>`	Output directory. Excluded from the live-reload watch loop so builds don’t trigger themselves.
`--host <h>`	`localhost`	Bind host. Use `0.0.0.0` to expose the dev server on the LAN.
`-p`, `--port <p>`	`8080`	Listen port. If the port is already bound, juicer scans up to 20 ports upward (`:8081`, `:8082`, …) and prints the actual port it landed on.
`-D`, `--drafts`	off	Include drafts (same semantics as `build -D`).
`-F`, `--future`	off	Include future-dated pages (same semantics as `build -F`).
`-L`, `--live-reload`	off	Watch the source recursively, rebuild on change, and live-reload connected browser tabs.

Live reload — how it works

When -L is on, every HTML response gets a tiny long-polling client script injected before </body>. The script calls GET /__juicer/wait?since=<version>; the server holds each poll open until the next rebuild (or 30s, whichever comes first) and responds with {reload, version}. The client calls location.reload() on reload: true.

Long-polling — not SSE — was chosen because SSE leaks a connection during page-unload across browsers, and HTTP/1.1 connection-limit pooling makes the failure mode look like “live-reload silently stopped working.” A fresh fetch per cycle has neither problem.

The watcher is debounced at 150ms, so saving five files in rapid succession results in one rebuild and one reload. Saves to the output directory (-d) are ignored to prevent build-triggers-itself loops.

`config`

Print the resolved configuration after the chosen baseline, site.toml overlay, and CLI overrides are merged. Useful for debugging “why is htmlDir doing that?” — the answer is right there in the printed config.

sbt 'juicerJVM/run config -s .'
sbt 'juicerJVM/run --config simple config -s notes'

Flag	Default	What
`-s`, `--source <p>`	`.`	Site source directory.

`theme add`

Install a theme from a git repository into <src>/<themeDir>/. After running it, set theme = "<name>" in your site.toml to activate.

sbt 'juicerJVM/run theme add https://github.com/edadma/juicer.git -n juicerdocs'
sbt 'juicerJVM/run theme add https://github.com/me/my-theme.git -r v1.2.0'
sbt 'juicerJVM/run theme add https://github.com/edadma/juicer.git -n juicerblog --subdir docs/themes/juicerblog'

Flag	Default	What
`<git-url>` (positional)	required	HTTPS or SSH URL of the theme repository.
`-s`, `--source <p>`	`.`	Site source directory. The theme is installed under `<src>/<themeDir>/`.
`-n`, `--name <name>`	derived from URL/subdir	Directory name to install under. Required when juicer can’t infer a sensible name from the URL.
`-r`, `--ref <ref>`	repo HEAD	Branch, tag, or commit SHA to check out. Lock to a tag for reproducible builds.
`--subdir <path>`	repo root	Install only this subdirectory of the cloned repo. Useful when one repo ships several themes (e.g. juicer ships all six under `docs/themes/`).
`--force`	off	Overwrite an existing theme directory. Without this, an existing `<themeDir>/<name>/` aborts the install.

The metadata for an upgrade later (URL, ref, subdir) is recorded in <themeDir>/<name>/.juicer-theme.toml. Don’t commit that file is up to you — it’s small, it’s plain TOML, and committing it means collaborators get the same theme version after git pull without re-running theme add.

Note

theme add only installs the theme directory. You still have to set theme = "<name>" in site.toml to activate it — juicer doesn’t guess which of your installed themes you want active. Run juicer config -s . after editing site.toml to verify the resolved theme value.

`theme upgrade`

Re-fetch one or every installed theme from the URL+ref recorded in its .juicer-theme.toml. Use this after the upstream theme has shipped a fix and you want to pull it in.

sbt 'juicerJVM/run theme upgrade'
sbt 'juicerJVM/run theme upgrade juicerblog'
sbt 'juicerJVM/run theme upgrade juicerblog -r v1.3.0'

Flag	Default	What
`<name>` (positional)	every theme	Which theme to upgrade. Omitted = upgrade every theme that has a `.juicer-theme.toml`.
`-s`, `--source <p>`	`.`	Site source directory.
`-r`, `--ref <ref>`	recorded ref	Override the recorded ref for this upgrade only. Doesn’t rewrite `.juicer-theme.toml` — the next bare `theme upgrade` returns to the previously-recorded value unless you also re-run `theme add`.

Exit codes

Code	Meaning
`0`	Success.
`1`	Any failure — bad source path, missing required config, parse error in `site.toml`, template render error, git failure in `theme add`/`upgrade`. Run with `-v` for the verbose stack trace.

Blogging features

2026-05-27T20:59:11.669095985Z

Juicer’s docs-site features (sections, _index.md, partials, themes) work fine for a blog as-is, but a real blog usually wants four extra things: a way to tag posts, archive pages that group posts by tag, paginated list pages so the front page doesn’t drag, and parsed publication dates so list pages can sort by recency. This page covers all of those, plus reading-time estimates and the bundled juicerblog theme that exercises every feature.

Note

Every feature on this page is opt-in. A docs site that doesn’t set tags frontmatter, doesn’t configure paginate, and doesn’t supply date frontmatter will render exactly the same after these features as before — same files, same URLs, byte-identical output.

Tags and categories

Add a tags field to a post’s frontmatter to mark it. Either a list or a single string is accepted:

---
title: Whirlwind tour of Scala 3 enums
date: 2024-03-12
tags: [scala, language]
---

---
title: A short note
tags: meta
---

Two archive pages are emitted for each tag the site uses:

URL pattern	What it lists
`/tags/`	Every tag the site uses, with post counts
`/tags/<slug>/`	Every post tagged with that one tag

Tag names are slugified for URLs — lowercased, ASCII-folded (café → cafe), and any run of non-alphanumeric characters is collapsed into a single -. So a tag named "Functional Programming" becomes /tags/functional-programming/.

categories is parsed identically and treated as a separate axis. You can use both or neither — sites that want a single way to group posts pick one and ignore the other:

---
title: Setting up the studio
date: 2024-03-12
categories: [behind-the-scenes]
tags: [meta, design]
---

That post would be reachable at /categories/behind-the-scenes/ and at both /tags/meta/ and /tags/design/.

Templates

Tag and category archives need their own layouts. The juicerblog theme ships a default pair; if you’re rolling your own theme, drop these two layouts under layouts/_default/:

Layout file	What it renders
`tag-list.html`	The `/tags/` index — full directory of every tag
`tag-page.html`	A single tag’s archive, e.g. `/tags/scala/`

The same names with category-list.html / category-page.html cover the categories axis.

The data your tag layouts see:

{{ .terms }}                 // List of every term — for tag-list.html
{{ .terms[0].name }}         // "scala"
{{ .terms[0].slug }}         // "scala"
{{ .terms[0].url }}          // "/tags/scala/"
{{ .terms[0].count }}        // 7

{{ .term }}                  // The current term — for tag-page.html
{{ .term.name }}             // "scala"
{{ .term.pages }}            // List of pages tagged with this term
{{ .term.pages[0].title }}   // "Whirlwind tour of Scala 3 enums"

Tip

If a layout is missing, the corresponding archive is silently skipped. So a docs site that ships no tag-list.html and no tag-page.html won’t get tag URLs even if you accidentally write tags: [foo] somewhere.

Site-wide template access

Templates that aren’t tag archives — say, your topbar.html — can still iterate over every tag the site uses:

{{ .site.tags }}            // List of every tag, sorted by count desc
{{ .site.categories }}      // Same shape, for categories

Each entry has name, slug, url, count, pages — same shape as .terms.

Pagination

A blog with thirty posts shouldn’t render every post on the front page. Set paginate in site.toml to chunk section index pages into multiple pages:

paginate = 10
sortBy = "date"

That tells juicer:

Slice section pages

For each section index page (every _index.md), take the section’s child pages and split them into chunks of 10.

Render slice 1 to `index.html`

The first chunk lands at the section’s natural URL — /posts/index.html, /index.html for the site root, etc.

Render slices 2..N to `page/N/index.html`

The second chunk lands at /posts/page/2/index.html, the third at /posts/page/3/, and so on. Static-host friendly: every URL is a real directory with a real file.

If a section has fewer pages than paginate, only the first slice is emitted and total reads 1 — your template doesn’t need to special-case that.

`sortBy`

Value	Order
`"date"`	`.page.date` descending (newest first); the blog default
`"title"`	`.page.title` ascending (alphabetical)
`"weight"`	`weight` frontmatter ascending — same as juicer’s default

A page with weight frontmatter overrides whichever sort the section uses, so you can pin a “Welcome” post above date-sorted listings.

Per-section overrides

Set paginate or sortBy on a section’s _index.md frontmatter to override site-wide:

---
title: Notes
paginate: 20
sortBy: title
---

A handful of short, alphabetised notes.

Templates

The data layouts see — both _index layouts and tag archives:

{{ .section.paginator.current }}     // 1-based index of THIS slice
{{ .section.paginator.total }}       // total slice count
{{ .section.paginator.pages }}       // pages on THIS slice (already sliced)
{{ .section.paginator.first }}       // URL of slice 1
{{ .section.paginator.last }}        // URL of last slice
{{ .section.paginator.prevURL }}     // empty string on slice 1
{{ .section.paginator.nextURL }}     // empty string on the last slice

A typical pagination footer:

{{ if .section.paginator.prevURL }}
  <a href="{{ .section.paginator.prevURL }}">← Newer</a>
{{ end }}
<span>Page {{ .section.paginator.current }} of {{ .section.paginator.total }}</span>
{{ if .section.paginator.nextURL }}
  <a href="{{ .section.paginator.nextURL }}">Older →</a>
{{ end }}

Dates

Frontmatter date is parsed into a real timestamp, not a passthrough string. Three input shapes are recognized:

Shape	Treated as
`2024-03-12T10:30:00Z`	Full ISO-8601 with offset
`2024-03-12T10:30:00`	Local datetime — assumed UTC
`2024-03-12`	Plain date — midnight UTC

If date is absent, juicer falls back to the source markdown file’s filesystem mtime. That means a freshly-written post sorts correctly without you having to set date explicitly.

Rendering

Three pre-formatted helpers ride alongside the parsed value, so templates don’t have to call format functions:

Field	Example	Use for
`.page.date`	`OffsetDateTime`	Sorting, math
`.page.dateISO`	`2024-03-12T00:00:00Z`	`<time datetime=...>` attributes
`.page.dateLong`	`March 12, 2024`	Body copy
`.page.dateShort`	`2024-03-12`	Compact list pages

A standard post-meta line:

<time datetime="{{ .page.dateISO }}">{{ .page.dateLong }}</time>

Note

The long-form English month names (January, February, …) are hand-baked into juicer rather than driven by a locale-aware DateTimeFormatter. The reason is purely practical: juicer’s Native build ships a minimal locale database and MMMM falls back to M01/M02 there. Hand-rolled month names render identically across the JVM, JS, and Native targets. If you need a non-English long format right now, write your own helper using .page.dateShort plus your own month table.

Reading time and word count

Two more fields automatically computed for every page:

Field	Type	What
`.page.wordCount`	int	Word count of the rendered HTML body (after shortcodes, before stripping)
`.page.readingTime`	int	Minutes — `ceil(wordCount / 200)`, with a floor of 1 for non-empty pages

The 200-words-per-minute figure is the Medium-popularized average. If you want a different cadence, render wordCount directly and divide it yourself in the template:

{{ .page.readingTime }} min read

about {{ .page.wordCount }} words

Empty pages get wordCount = 0 and readingTime = 0 so a stub _index.md doesn’t say “1 min read” misleadingly.

Permalinks

By default, the URL juicer emits for a page is one-to-one with its location in the content/ tree: content/posts/hello.md becomes /posts/hello/. That’s the right behaviour for docs sites where the file layout is the information architecture. For a blog, you usually want something different — most blogs route every post through /<year>/<month>/<slug>/, regardless of whether the post lives in content/posts/ or content/posts/scala/ or content/drafts/.

Configure that with the [permalinks] table in site.toml:

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

Each key is the section name (the first path segment after htmlDir is stripped). Each value is a URL template with substitution tokens. A post under content/posts/2024-03-12-hello.md with date: 2024-03-12 in its frontmatter renders to:

Default URL	With `posts = ":year/:month/:slug/"`
`/posts/2024-03-12-hello/`	`/2024/03/2024-03-12-hello/`

(Tip: when you’re using date-prefixed permalinks, drop the date prefix from the filename and let stripPrefix do its job — keep the URL clean.)

The available tokens

Token	Resolves to
`:slug`	The cleaned filename (numeric prefixes stripped, non-alnum runs collapsed)
`:title`	`slugify(.page.title)` — frontmatter `title` lowercased and ASCII-folded
`:year`	4-digit year from `.page.date`
`:month`	2-digit month from `.page.date`
`:day`	2-digit day from `.page.date`
`:section`	The section name itself — useful in nested patterns like `:year/:section/:slug/`

:title and :slug are usually different — the slug comes from the filename (so 01-getting-started.md becomes getting-started), the title comes from the title: frontmatter (so "Getting Started" becomes getting-started too, but "Café au Lait" becomes cafe-au-lait). Use :title when filenames are opaque or numbered and you want human-readable URLs anyway:

[permalinks]
posts = ":year/:title/"

Section index pages stay put

_index.md files are never routed through a permalink template. Even when posts = ":year/:slug/" is set, the posts/_index.md page still lives at /posts/, not at /2024/posts/. The reason is structural: the _index.md describes a section, not a piece of content, and a section’s URL has to be predictable so links in your nav and breadcrumbs keep working.

Sections you don’t list keep their default URL

[permalinks] is a map of overrides, not an all-or-nothing switch. Sections that aren’t keys in the table render at their default physical-path URL. So a site with both blog posts (under permalinked /posts/) and prose pages (about.md, contact.md at the root) just lists posts in [permalinks] and leaves the rest alone:

[permalinks]
posts = ":year/:month/:slug/"
# `about.md` is still at /about/, `contact.md` still at /contact/.# `about.md` is still at /about/, `contact.md` still at /contact/.

Tip

If a permalink template uses :year / :month / :day for a post that has no date: frontmatter, juicer falls back to the source markdown file’s filesystem mtime. That means a freshly written post gets the current date even when you forgot to set frontmatter — convenient for drafts, but worth being aware of when you git mv files and find the URL shifted.

What happens on disk

Permalink templates change both the URL and the on-disk write location: juicer doesn’t keep two copies of the page. So with posts = ":year/:month/:slug/", a post writes only to <dst>/2024/03/hello/index.html; the legacy <dst>/posts/hello/ directory is never created. (If you set htmlDir = "html" in site.toml, the path is <dst>/html/2024/03/hello/index.html, since htmlDir is the filesystem prefix that gets stripped from URLs.)

Date archives

Most blogs eventually want a “browse posts by date” navigation: an archive page for each year, optionally with a sub-archive for each month. Turn it on with one line in site.toml:

dateArchives = true

Juicer then emits two kinds of pages, gated independently by the presence of their layouts:

Layout	URL pattern	What it lists
`_default/date-year.html`	`/<year>/index.html`	Every dated post in that year, plus a per-month roll-up
`_default/date-month.html`	`/<year>/<month>/index.html`	Every dated post in that year + month

Both layouts are optional. Ship the year layout to get year-only archives; ship both for full month granularity; ship neither and dateArchives = true does nothing visible.

Note

Only pages with explicit date: frontmatter make it into the archives. Pages whose .page.date came from the filesystem mtime fallback are excluded — otherwise a docs site that turns the feature on would suddenly find every reference page in the current year’s archive. The rule is “if you set a date, you’re in; if you didn’t, you’re not.”

Year-archive data

The date-year.html layout sees:

{{ .year }}                // 2024 (BigDecimal)
{{ .pages }}               // every dated post in 2024, newest first
{{ .pages[0].title }}      // most recent post's title
{{ .months }}              // per-month roll-up, ascending by month number
{{ .months[0].month }}     // 1 (BigDecimal)
{{ .months[0].monthName }} // "January"
{{ .months[0].url }}       // "/2024/01/"
{{ .months[0].count }}     // 4 (BigDecimal)
{{ .months[0].pages }}     // pages in that month, newest first

A typical year-archive layout:

<h1>{{ .year }}</h1>
<ol>
  {{ for m <- .months }}
  <li>
    <a href="{{ m.url }}">{{ m.monthName }}</a>
    <span>({{ m.count }} posts)</span>
  </li>
  {{ end }}
</ol>

Month-archive data

The date-month.html layout sees:

{{ .year }}        // 2024
{{ .month }}       // 3 (BigDecimal)
{{ .monthName }}   // "March"
{{ .pages }}       // posts in March 2024, newest first

<h1>{{ .monthName }} {{ .year }}</h1>
<ol>
  {{ for p <- .pages }}
  <li>
    <time datetime="{{ p.dateISO }}">{{ p.dateShort }}</time>
    <a href="{{ p.url }}">{{ p.title }}</a>
  </li>
  {{ end }}
</ol>

Combining with permalinks

Date archives compose cleanly with permalink templates: the URL space remains hierarchical and unique. With:

dateArchives = true

[permalinks]
posts = ":year/:month/:slug/"

a single post with date: 2024-03-15 lives at /2024/03/hello/, and archive pages cover that same prefix:

URL	What
`/2024/03/hello/`	The single post
`/2024/03/`	March 2024 archive
`/2024/`	2024 year archive

There’s no collision because permalink output paths and archive paths land in different places — a permalinked post writes to /<year>/<month>/<slug>/index.html, while the year archive writes to /<year>/index.html and the month archive to /<year>/<month>/index.html. The directory structure interleaves cleanly.

Series / multi-part posts

Some posts read better as a series — three parts on debugging, four on setting up a project, twelve on writing your own OS. Juicer joins related posts into a navigable series via two frontmatter fields:

---
title: OS Internals, Part 1 — The Boot Process
series: OS Internals
seriesOrder: 1
---

---
title: OS Internals, Part 2 — The Memory Subsystem
series: OS Internals
seriesOrder: 2
---

Pages with the same series value (case-sensitive, exact match) are linked. Each one sees a .page.series block:

Field	What
`.page.series.name`	The series name as it appears in frontmatter
`.page.series.pages`	List of every page in the series, ordered
`.page.series.prev`	Previous page’s record, or `null` on the first
`.page.series.next`	Next page’s record, or `null` on the last
`.page.series.index`	1-based position of the current page
`.page.series.total`	Number of pages in the series

A typical “in this series” sidebar:

{{ if .page.series }}
<aside aria-label="In this series">
  <h2>{{ .page.series.name }}</h2>
  <p>Part {{ .page.series.index }} of {{ .page.series.total }}.</p>
  <ol>
    {{ for s <- .page.series.pages }}
    <li><a href="{{ s.url }}">{{ s.title }}</a></li>
    {{ end }}
  </ol>
</aside>
{{ end }}

The juicerblog theme ships exactly this widget as the partials/series-nav.html partial; _default/file.html calls it after the post body. Override it from your site’s partials/ if you want custom copy.

Ordering rules

Within a series, pages sort by:

`seriesOrder` ascending

Pages with explicit seriesOrder come first in the order they declare. A page with seriesOrder: 2 sorts before one with seriesOrder: 5.

Date ascending (oldest first)

Pages WITHOUT a seriesOrder sort by .page.date ascending. Series usually read chronologically — older posts before newer ones — and the ascending direction matches that.

Filename, as a stable tiebreaker

Two unordered same-day posts fall back to filename order, so the result is deterministic regardless of filesystem walk order.

Note

A page can be in at most one series — series: is a string, not a list. If you need a multi-membership relationship, that’s exactly what tags is for. Series is for narratively-linked posts that share a single arc.

Author registry

A single-author blog can lean on .site.author from site.toml and call it a day. A multi-author site needs more: per-author bio, avatar, external links, and an archive page that lists each author’s posts.

Declare authors as an array of tables:

[[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"

[[authors.links]]
label = "Mastodon"
url   = "https://hachyderm.io/@edadma"

[[authors]]
id     = "alice"
name   = "Alice Smith"
bio    = "Does a lot of design."
avatar = "/img/alice.jpg"

Then point a post at one (or more) of the registered ids:

---
title: A solo post
author: ed
---

---
title: A co-authored post
authors: [ed, alice]
---

author: is the singular shorthand; authors: is the multi-author form. Either works. Templates see both fields, normalised:

Field	Type	What
`.page.author`	`Map?`	First (or only) resolved author record, or `null`
`.page.authors`	`List[Map]`	All resolved author records — empty list when none

Each record carries every key from the registry — id, name, bio, avatar, links[] — so a per-post byline can render the avatar, name, and external links directly:

{{ if .page.author }}
<div class="byline">
  {{ if .page.author.avatar }}
  <img src="{{ .page.author.avatar }}" alt="" />
  {{ end }}
  <div>
    <p class="name">{{ .page.author.name }}</p>
    {{ if .page.author.bio }}<p class="bio">{{ .page.author.bio }}</p>{{ end }}
  </div>
</div>
{{ end }}

Note

A frontmatter author: value that doesn’t match any registry id falls back to a stub record {id: "<typo>"}. Templates that read .page.author.name get an empty string rather than a hard failure — the build doesn’t break on a typo, but the author archive is empty. Audit .site.authors if a name disappears unexpectedly.

Author archives

Two archive pages per author registry are emitted, each gated by an optional layout:

Layout	URL pattern	What it lists
`_default/author-list.html`	`/authors/index.html`	Every author with at least one referencing post
`_default/author-page.html`	`/authors/<id>/index.html`	One author’s posts, newest first

The author-list.html layout sees:

{{ .authors }}                  // List of records, in registry order
{{ .authors[0].name }}
{{ .authors[0].url }}           // "/authors/ed/"
{{ .authors[0].count }}         // 12
{{ .authors[0].pages }}         // their posts (already date-desc)

The author-page.html layout sees:

{{ .author }}                   // single record
{{ .author.name }}
{{ .author.bio }}
{{ .author.count }}
{{ .author.pages }}             // posts, newest first

Authors with zero referencing posts are omitted from both archives — keeps a partially-populated [[authors]] registry from emitting empty “see all posts by Bob” pages.

`.site.authors`

Like .site.tags and .site.categories, the same author records are exposed site-wide for use in any template:

{{ for a <- .site.authors }}
<a href="{{ a.url }}">{{ a.name }} ({{ a.count }})</a>
{{ end }}

Useful for a “contributors” list in a footer or about page.

Aliases / redirects

When you change a post’s URL — by editing its filename, adding a [permalinks] template, or renaming a section — every link to the old URL breaks. Aliases stop the bleeding without server-side rewrites.

Add the old URL(s) to the new page’s frontmatter:

---
title: Setting up a Scala 3 project
date: 2024-03-12
aliases:
  - /old-blog-name/setting-up-scala/
  - /2023/setting-up/
---

Juicer emits a small static HTML page at each listed URL. The page sets a <meta http-equiv="refresh"> to the canonical URL, plus a visible fallback link in case the meta refresh is blocked:

<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="refresh" content="0; url=/posts/setting-up-scala-3/">
  <link rel="canonical" href="https://example.com/posts/setting-up-scala-3/">
  <title>Redirecting…</title>
</head>
<body>
  <p>This page has moved. Redirecting to <a href="/posts/setting-up-scala-3/">/posts/setting-up-scala-3/</a>.</p>
</body>
</html>

That’s the built-in default. It works without any theme. If you want different markup — branded styling, custom copy, JavaScript fallback — drop a layout at layouts/_default/alias.html:

<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="refresh" content="0; url={{ .target }}">
  <link rel="canonical" href="{{ .absTarget }}">
  <title>{{ .page.title }} — moved</title>
</head>
<body>
  <h1>This page has moved</h1>
  <p><a href="{{ .target }}">Continue to {{ .page.title }}</a></p>
</body>
</html>

The custom layout has access to:

Field	What
`.target`	Site-relative canonical URL
`.absTarget`	Absolute canonical URL (`baseURL` + `.target`)
`.page.<...>`	Every field of the canonical page’s record
`.site.<...>`	The full site context

Aliases accept a single string or a list:

aliases: /old-url/

aliases:
  - /old-url/
  - /even-older-url/

Note

Aliases are not the same as URL rewriting. Each alias is a real static HTML file in the output tree — <dst>/old-url/index.html, <dst>/even-older-url/index.html, etc. That’s the point: it works on any static host (GitHub Pages, Cloudflare Pages, S3, Netlify…) without edge-rule configuration. Cost is one tiny HTML file per alias.

OpenGraph / Twitter cards

When a post is shared on social media, the platform renders a “card” preview built from a small block of <meta> tags in the page’s <head>. Juicer ships a {{ ogTags .page }} template builtin that emits the canonical block in one line:

<head>
  ...
  {{ ogTags .page }}
</head>

That call expands to:

<meta property="og:type" content="article" />
<meta property="og:title" content="The post title" />
<meta property="og:url" content="https://example.com/posts/the-post/" />
<meta property="og:description" content="The post summary." />
<meta property="og:image" content="https://example.com/img/hero.jpg" />
<meta property="og:site_name" content="My blog" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="The post title" />
<meta name="twitter:description" content="The post summary." />
<meta name="twitter:image" content="https://example.com/img/hero.jpg" />

Tags whose source field is empty are omitted (you don’t get an empty <meta property="og:image" content="" /> cluttering the output).

Resolution rules

For each value the builtin needs, it tries fields in priority order:

Tag	Resolution chain
`og:title`, `twitter:title`	`.page.ogTitle` → `.page.title`
`og:description`, `twitter:description`	`.page.ogDescription` → `.page.description` → `.page.summary`
`og:image`, `twitter:image`	`.page.ogImage` → `.page.image` → `.site.ogImage` → `.site.image`
`og:url`	`.page.permalink` (always present — the absolute URL juicer computed)
`og:site_name`	`.site.title`
`twitter:card`	`summary_large_image` if an image was resolved, otherwise `summary`

Image URLs are promoted to absolute via the configured baseURL — a site-relative /img/hero.jpg becomes https://example.com/img/hero.jpg. Crawlers typically reject relative URLs in og:image, so this matters.

Per-page overrides

To set a different card title or summary than the page’s own title and summary, add ogTitle / ogDescription / ogImage to the post’s frontmatter:

---
title: A long, descriptive, SEO-targeted post title
summary: A long summary that's good for the page's own list-page meta…
ogTitle: A short, punchy title for social cards
ogDescription: A different summary that fits in a card preview.
ogImage: /img/posts/short-title-card.png
---

Note

The juicerblog theme calls {{ ogTags .page }} from its partials/head.html, so every page gets the meta block automatically without you doing anything in the post itself. Sites that want to control the call site (or skip it for some pages) can override the partial.

The `juicerblog` theme

Juicer ships a default blog theme under themes/juicerblog/ that exercises every feature on this page — plus server-side syntax highlighting, author bylines, series progress badges, a reading-progress hairline, code-block copy buttons, and a homepage / archive layout pair. The full theme reference lives in its own section: see juicerblog for the overview and juicerblog · Configuration for the full config knobs, frontmatter conventions, syntax-highlighting setup, and override patterns.

The fastest way to see every blog feature working together is the bundled demo:

sbt 'juicerJVM/run serve -s docs/demos/juicerblog -L'

That spins up a live preview of docs/demos/juicerblog/ — 9 dated posts spanning Jul–Dec 2024, three authors with a multi-author co-byline, a 3-post series, dateArchives + permalinks + aliases, syntax highlighting, the works. Touch any markdown file in the source and the page reloads in under a second.

Where each feature lives

When a feature breaks, here’s where to start looking:

Feature	Engine	Theme
Tags / categories	`App.scala` `collectTaxonomy`, `renderTaxonomyArchives`	`tag-list.html`, `tag-page.html`
Pagination	`paginate.scala`, render-loop slicing in `App.scala`	`partials/pagination.html`
Dates	`App.scala` `parseDateString`, `formatDateLong`	`partials/post-meta.html`
Reading time	`App.scala` `wordsOf`, `readingTimeOf`	Anywhere `.page.readingTime` is used
Slug helper	`package.scala` `slugify`, `asciiFold`	(used internally for tag URLs)

Juicer

Troubleshooting

Build / install

sbt 'juicerJVM/run --help' errors out before printing the help banner

not a readable directory: <src>

unknown base configuration: <name>

compile errors after a git pull

Layouts

layout '<X>' not found for rendering '<page>' in verbose output

A page renders with the wrong layout

A _index.md renders as a single post instead of a section

Themes

Theme renders with no styling at all

theme add <git-url> fails with “could not derive theme name”

A new theme doesn’t show up after theme add

Site assets (logo, favicon) override theme assets but they don’t appear

Blog features

Code blocks aren’t highlighted

Highlighted code has no colors

Date archives /2024/ etc. aren’t being emitted

Tag pages don’t include a post that has the tag

Author archive page is empty even though the author has posts

Permalinks [permalinks] aren’t applying

Aliases redirect to the wrong place

Serve / live reload

juicer serve fails with “address already in use”

Live-reload doesn’t fire when I save a markdown file

Browser shows old content even after a save

Templates

unknown variable: X at build time

not a number: <X> (java.lang.Y) in template comparisons

Markdown body content doesn’t render its {{ for ... }} loops

When all else fails

Theming

Layer 1 — palette and token overrides via [juicerXxx]

Palette tokens (all four themes)

Typography tokens

Sizing tokens

Example — quietly retune juicercafe to a teal palette

Layer 2 — customCSS: drop your own stylesheet alongside the theme

Layer 3 — replace a theme file outright

Site-wide chrome keys

Themes

Theme chains

What a theme can ship

Picking the right primitive

Bundled themes

Building your own

Theme inheritance

The lookup chain

Deduplication

Errors

No theme.toml?

Templates

Template kinds

The two-pass render

First pass — the particular template runs

Second pass — baseof.html runs

The data context

Template syntax

Substitution

Built-in functions

imageDims

imageVariants and srcset

Conditionals

Loops

Partials

Defines & blocks

Builtin filters

Comments

Scope inside loops

Template data

.site

Term shape

.site.posts and .site.pagesByYear

.site.authorRegistry

When /authors/ and /authors/<id>/ get rendered

Renaming the URL prefix — authorsPath

.site.now

.site.events

`sbt 'juicerJVM/run --help'` errors out before printing the help banner

`not a readable directory: <src>`

`unknown base configuration: <name>`

`compile` errors after a `git pull`

`layout '<X>' not found for rendering '<page>'` in verbose output

A `_index.md` renders as a single post instead of a section

`theme add <git-url>` fails with “could not derive theme name”

A new theme doesn’t show up after `theme add`

Date archives `/2024/` etc. aren’t being emitted

Permalinks `[permalinks]` aren’t applying

`juicer serve` fails with “address already in use”

`unknown variable: X` at build time

`not a number: <X> (java.lang.Y)` in template comparisons

Markdown body content doesn’t render its `{{ for ... }}` loops

Layer 1 — palette and token overrides via `[juicerXxx]`

Layer 2 — `customCSS`: drop your own stylesheet alongside the theme

Second pass — `baseof.html` runs

`imageDims`

`imageVariants` and `srcset`

`.site`

`Term` shape

`.site.posts` and `.site.pagesByYear`

`.site.authorRegistry`

When `/authors/` and `/authors/<id>/` get rendered

Renaming the URL prefix — `authorsPath`

`.site.now`

`.site.events`

`.site.calendar`

`.site.photos`

`.site.data`

`.site.comments`

`.page`

`.page.series` shape

`.page.backlinks` shape

`.section`

`.section.paginator`

`asset` builtin

`[= note =]`

`[= tip =]`

`[= warning =]`

`[= danger =]`

`[= steps =]`

`[= tabs =]` / `[= tab "Label" =]`

`[= filetree =]`

`[= collapse "Summary" =]`

`[= kbd "Ctrl+K" /=]`

`[= badge "alpha" /=]`

`[= button "Label" href="..." /=]` / `[= buttons =]`

`[= figure "/img/foo.png" alt="..." caption="..." /=]`

`[= github "owner/repo" /=]`

`[= youtube "<video-id>" /=]`

Deferred shortcodes — the `[~ … ~]` delimiter

2. Écrire `site.toml`

2. Write `site.toml`