Frontmatter

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

Publishing & visibility

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

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

Taxonomy

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

Authors

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

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

Aliases (redirects)

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

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

Photos

---
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" }
---

OpenGraph / social cards

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

---
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:

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:

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>