Juicer

Themes

2026-05-07T23:55:58.03149558Z

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.

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.

Building your own

The juicerdocs source is a good reference. It uses every theme primitive, so reading through themes/juicerdocs/ end-to-end is a quick tour of the conventions.

edadma/juicer GitHub repository

Templates

2026-05-07T23:55:58.03149558Z

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
.page.next, .page.prev — sibling navigation
.page.isSection — true for _index.md pages
Plus any custom frontmatter key

See Reference / Template data for the full set.

Template syntax

2026-05-07T23:55:58.03149558Z

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)

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

Juicer-specific helpers

Builtin	What
`relURL '...'`	Site-relative URL (prepends `baseURL.path`)
`absURL '...'`	Absolute URL (prepends `baseURL.base + baseURL.path`)
`markdownify '...'`	Render a markdown string to HTML
`emojify '...'`	`:smile:` → 😄 substitution

Comments

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

Template data

2026-05-07T23:55:58.03149558Z

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.root`	`Map?`	The root section’s `_index` record (or `null`)

`.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.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.<custom>`	varies	Any frontmatter key

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

`.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

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-07T23:55:58.03149558Z

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>

Quickstart

2026-05-07T23:55:58.03149558Z

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-07T23:55:58.03149558Z

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.run/) 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.run/ 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.
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-07T23:55:58.03149558Z

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 (TODO).

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.1.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 examples/minimal directory in the repo:

sbt 'juicerJVM/run build -s examples/minimal'
ls examples/minimal/public

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

Content files

2026-05-07T23:55:58.03149558Z

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.

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'

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-07T23:55:58.03149558Z

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
brandStrong     = "#2563eb"        # blue-600
brandSoft       = "#dbeafe"        # blue-100
accent          = "#0891b2"        # cyan-600
leaf            = "#10b981"        # emerald-500

# 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.

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.

Configuration

2026-05-07T23:55:58.03149558Z

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

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 (1-clamped)

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-07T23:55:58.03149558Z

Juicer’s CLI has three subcommands: build, serve, and config.

Global options

Flag	What
`-b`, `--baseurl <URL>`	Override `baseURL` from the config
`-c`, `--config <name>`	Pick a baseline config (`simple` / `standard` / `norme`); default is `standard`
`-h`, `--help`	Print usage and exit
`-v`, `--verbose`	Print step-by-step build progress
`--version`	Print the version and exit

`build`

Build the site to <src>/public/ (or -d <dst> to override).

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

Flag	What
`-s`, `--source <p>`	Site source directory (default: `.`)
`-d`, `--dest <p>`	Output directory (default: `<src>/<publicDir>`)
`-D`, `--drafts`	Include `draft: true` pages

`serve`

Build, then start a local HTTP server.

sbt 'juicerJVM/run serve -s . -p 8080'

Flag	What
`-s`, `--source <p>`	Site source directory
`-d`, `--dest <p>`	Output directory
`--host <h>`	Bind host (default: `localhost`)
`-p`, `--port <p>`	Listen port (default: `8080`)
`-D`, `--drafts`	Include drafts

Note

serve is currently JVM-only — com.sun.net.httpserver doesn’t exist on Scala.js or Native. The build itself works on all three platforms; serving is the lone JVM exception.

`config`

Print the merged site config (after baseline + overlay + CLI overrides).

sbt 'juicerJVM/run config -s .'

Useful for debugging “why is my htmlDir doing that?” — the answer is right there in the printed config.

Juicer

Themes

Theme chains

What a theme can ship

Picking the right primitive

Building your own

Templates

Template kinds

The two-pass render

First pass — the particular template runs

Second pass — baseof.html runs

The data context

Template syntax

Substitution

Conditionals

Loops

Partials

Defines & blocks

Builtin filters

Juicer-specific helpers

Comments

Template data

.site

.page

.section

Other top-level

Page ordering

Shortcodes

What juicerdocs ships

Tabs

Steps

Install Juicer

Make a site directory

Build & serve

File trees

Inline pieces

Collapsible sections

Buttons

GitHub repo cards

YouTube embeds

Writing your own

Quickstart

1. Make a directory

2. Write site.toml

3. Write a layout

4. Write content

5. Build & serve

What just happened?

Markdown

CommonMark — the basics

GFM extras

Tables

Strikethrough

Task lists

Footnotes

Auto-linking

Smart punctuation

Callouts (admonitions)

Auto heading IDs

Definition lists

Emoji

Code blocks with language

Installation

From source (recommended for now)

sbt dependency (library use)

Requirements

Verifying the install

Content files

Frontmatter

Pretty URLs

The htmlDir quirk

Drafts

Summaries

Explicit frontmatter

marker

First paragraph (fallback)

Configuration

Quick example

Top-level keys (read by juicerdocs)

[juicerdocs] keys

Second pass — `baseof.html` runs

`.site`

`.page`

`.section`

2. Write `site.toml`

The `htmlDir` quirk

`` marker

`[juicerdocs]` keys

`build`

`serve`

`config`