domma-cms 1.6.60 → 1.7.0

package/docs/markdown-shortcodes.md

@@ -0,0 +1,1738 @@
+# Markdown Shortcodes
+
+Domma CMS extends standard Markdown with shortcodes - special tags you write in page content that the server converts to HTML before rendering. Shortcodes are processed before the Markdown parser runs, so Markdown formatting works inside shortcode bodies.
+
+All shortcode attributes accept single or double quotes, and bare flags (e.g. `hover`, `dismissible`) are allowed.
+Most shortcodes are skipped inside fenced code blocks and inline code, so you can show shortcode syntax on a page
+(`[block]` / block short tags and `[banner]` are the exceptions - they are expanded even inside code).
+
+## Expiring any shortcode
+
+Every shortcode accepts the following optional expiry attributes. Conditions combine: when any configured limit is reached, the shortcode and its body are hidden from that visitor.
+
+```markdown
+[banner expires-at="2026-12-31T23:59:00Z"]Offer ends this year.[/banner]
+[card expire-after="60" expire-scope="ip"]Shown for an hour after the first view from this IP.[/card]
+[button expire-views="3" expire-scope="ip" /]
+[text expire-views="1" expire-scope="session"]Shown once in this browser session.[/text]
+[card expire-ip="203.0.113.8, 2001:db8::/32"]Only shown to these IP addresses.[/card]
+```
+
+`expires-at` takes an ISO 8601 date and time, including its timezone (for example, `2026-12-31T23:59:00Z`). `expire-after` starts its timer on the visitor's first view. `expire-views` sets the maximum rendered page views. Both counters use the IP address by default; set `expire-scope="session"` to track the browser session instead. `expire-session="true"` is shorthand for showing a shortcode once per browser session. `expire-ip` is an optional allowlist of exact IP addresses or CIDR ranges. Editor previews ignore expiry limits and do not consume views. Expiry state stores hashed visitor identifiers in `content/shortcode-expiry.json`.
+
+Use `expiry-id` to change which visitor counter a shortcode uses after changing its position in the page. Without it, each shortcode occurrence has its own counter.
+
+---
+
+## `[card]`
+
+Wraps content in a Domma card component.
+
+### Basic usage
+
+```
+[card]
+Card body with **Markdown** support.
+[/card]
+```
+
+### With a title
+
+```
+[card title="Getting Started"]
+Follow these steps to set up your site.
+[/card]
+```
+
+### All attributes
+
+| Attribute | Type | Description |
+|---|---|---|
+| `title` | string | Card header title. Omit for a body-only card |
+| `subtitle` | string | Optional subtitle below the title |
+| `icon` | string | Domma icon name displayed in the card header |
+| `icon-layout` | string | `"inline"` (default) or `"stacked"` - controls icon/title arrangement |
+| `icon-size` | string | `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, or an explicit size: `48` / `48px`, `3rem`, `2em` |
+| `icon-align` | string | `left`, `center` (or `centre`) or `right` - aligns the icon and title together; works with `icon-layout` and the `icon-top` / `icon-inline` layouts |
+| `footer` | string | Text content for the card footer |
+| `layout` | string | One of 33 ready-made card designs - see [Card layouts](#card-layouts) below |
+| `variant` | string | `clean`, `gradient`, `glass`, `accent`, `dark` or `glow`. Legacy `"primary"` still adds the primary colour theme |
+| `gradient` | string | Gradient name used with `variant="gradient"` (default `indigo`) |
+| `image` | string | Image URL, used by the image-based layouts |
+| `collapsible` | `"true"` | Makes the card body toggle on header click |
+| `hover` | flag | Adds a hover highlight effect; `hover="off"` switches the lift off instead |
+| `font` | string | `serif` or `mono` |
+| `font-size` | string | `sm`, `lg` or `xl` |
+| `borderless` | flag | No border |
+| `shadow` | string | `none`, `md` or `lg` |
+| `rounded` | string | `none`, `xs` (2px), `sm`, `lg` or `full` |
+| `text-align` | string | `center` or `right` |
+| `padding` | string | `compact` or `spacious` |
+| `class` | string | Extra CSS classes added to the card element |
+| `id` | string | HTML `id` attribute on the card element |
+
+Effects can also be added straight onto a card as flags - see [Effect injection](#effect-injection).
+
+### Card layouts
+
+`layout="…"` picks one of 33 ready-made designs. The page editor's Card builder exposes all of them. Extra
+attributes used by particular layouts are shown in brackets.
+
+`basic`, `header-body`, `header-body-footer`, `no-header-footer`, `icon-top`, `icon-inline`, `image-top`,
+`image-overlay`, `thumb-left`, `thumb-right`, `wide-left-image`, `full-bg`, `split-half`, `avatar-profile`,
+`stat-metric` (`delta`, `progress`), `quote-testimonial`, `callout` (`callout-type`), `video-media`,
+`location-map` (`address`), `step-numbered` (`step` - the number on its badge, default 1), `corner-badge` and `badge-band` (`badge`), `glass-gradient-border`,
+`rating-review` (`rating` 0-5), `tag-cloud` (`tags`), `timeline-entry`, `code-snippet` (`lang`), `before-after`,
+`pricing` (`price`, `period`, `href` for its button, `footer` for its label, `[feature]` lines), `feature-comparison`, `activity-feed`, `progress-goal` (`progress`),
+`file-document` (`filename`, `filesize`, `filetype`).
+
+A card with no `layout` (or an unknown one) renders the classic header/body/footer card shown below.
+
+```
+[card title="Why us" layout="icon-top" icon="star" variant="glass"]
+Fast, file-based and friendly.
+[/card]
+```
+
+### Collapsible card
+
+```
+[card title="Frequently Asked Questions" collapsible="true"]
+Content that can be shown or hidden.
+[/card]
+```
+
+### Card with icon
+
+```
+[card title="Tips & Tricks" icon="lightbulb" icon-layout="inline"]
+Here are some helpful tips.
+[/card]
+```
+
+### Rich header and footer sub-tags
+
+Use `[header]` and `[footer]` sub-tags when you need Markdown-rendered content (bold, links, icons) in the card header
+or footer regions. Sub-tags take precedence over the `title`/`subtitle`/`icon` and `footer` attributes.
+
+```
+[card]
+[header]
+### Custom Title with **bold** and [a link](/about)
+[/header]
+
+Body content here - works exactly as before.
+
+[footer]
+[Read more](/about) | [icon name="arrow-right" /]
+[/footer]
+[/card]
+```
+
+Both sub-tags are optional and independent:
+
+```
+[card title="With attribute title"]
+[footer]
+**Note:** This footer uses Markdown, the header still comes from the `title` attribute.
+[/footer]
+[/card]
+```
+
+```
+[card]
+[header]
+## Rich Header - no footer on this card
+[/header]
+
+Just a body, no footer.
+[/card]
+```
+
+When a sub-tag is present alongside its equivalent attribute (e.g. both `[header]` and `title="..."`), the sub-tag
+always wins and the attribute is ignored.
+
+### Rendered output
+
+The shortcode outputs:
+
+```html
+<div class="card mb-4">
+  <div class="card-header">
+    <div class="card-title">Getting Started</div>
+  </div>
+  <div class="card-body"><p>Follow these steps…</p></div>
+</div>
+```
+
+---
+
+## `[box]`
+
+A card with no header - a plain container around any content. Without attributes it has **no shadow** and a
+**2px corner radius**.
+
+```
+[box]
+Anything here: text, a [button href="/contact" label="Get in touch" /], a [grid] or a [card].
+[/box]
+```
+
+`shadow` and `rounded` on the tag replace those defaults; every other body-card attribute works as on `[card]`.
+
+| Attribute | Type | Description |
+|---|---|---|
+| `shadow` | string | `"none"` (default), `"md"` or `"lg"` |
+| `rounded` | string | `"xs"` (2px, default), `"none"`, `"sm"`, `"lg"` or `"full"` |
+| `padding` | string | `"compact"` or `"spacious"` |
+| `borderless` | flag | No border |
+| `hover` | string | `"off"` stops the box lifting when the pointer is over it (boxes and cards lift by default). Also `false`, `none`, `no`, `0` |
+| `color` (or `colour`) | string | A theme colour - `primary`, `secondary`, `success`, `info`, `warning`, `danger` - or a hex colour (`#0f766e`, `#fa0`). Replaces `variant` |
+| `variant` | string | As on `[card]` (`clean`, `glass`, `accent`, `dark`, `glow`, `gradient`, `primary`) |
+| `footer` | string | Text for a footer strip |
+| `class` / `id` | string | On the box element (it also carries `card` and `dm-box`) |
+
+**Colours follow the theme.** A plain box takes its background, border and text from the theme's card tokens, so
+it matches every theme, light or dark, and changes with the theme switcher. `color="success"` (and the other theme
+colour names) tints the box with that theme colour over the card background - a pale tint on a light theme, a deep
+one on a dark theme - with the theme's text colour on top; links in it take the tone, pulled towards the text
+colour so they stay readable.
+
+```
+[box color="warning"]
+**Heads up:** the office is closed on Friday.
+[/box]
+
+[box color="#0f766e" rounded="lg"]
+Our own brand teal, whatever the theme.
+[/box]
+```
+
+A hex colour is yours and is kept on every theme: the box gets black or white text, whichever reads better on it,
+and headings, links, code and the footer follow that text colour. A mid-grey such as `#777` cannot reach 4.5:1
+with either, so pick a lighter or darker shade for body text. Anything else in `color` (a colour name like `red`,
+`rgb(…)`) is ignored and the box is drawn plain. `variant="dark"` stays a dark panel on every theme, with light
+text, links, code and footer on it.
+
+A header is never drawn: `title`, `subtitle`, `icon`, `image` and `layout` are ignored. Effects that go on a
+`[card]` (`reveal`, `pulse`, …) go on a `[box]` too. A `[card]` can sit inside a `[box]` and a `[box]` inside a
+`[card]`; a `[box]` cannot hold another `[box]`. `rounded="xs"` is also available on `[card]`.
+
+---
+
+## `[grid]` / `[row]` with `[col]`
+
+Lay out content in multi-column grids using Domma's native CSS Grid system.
+
+### Grid (explicit column count)
+
+```
+[grid cols="2" gap="3"]
+[col]
+Left column content with **Markdown**.
+[/col]
+[col]
+Right column content.
+[/col]
+[/grid]
+```
+
+### Grid with a spanning column
+
+```
+[grid cols="3" gap="2"]
+[col span="2"]Wide column (spans 2 of 3)[/col]
+[col]Narrow column[/col]
+[/grid]
+```
+
+### Row (auto-layout)
+
+```
+[row gap="2"]
+[col]Column A[/col]
+[col]Column B[/col]
+[col]Column C[/col]
+[/row]
+```
+
+### `[grid]` attributes
+
+| Attribute | Type | Description |
+|---|---|---|
+| `cols` | number | Number of equal columns. By default the grid stacks on small screens (one column on mobile, then more at the `md`/`lg` breakpoints) |
+| `responsive` | `"false"` | Turn off mobile stacking - always use exactly `cols` columns (`grid-cols-N`) |
+| `gap` | number | Gap size token (`gap-N`) |
+| `class` | string | Extra CSS classes on the grid wrapper |
+| `fullwidth` | `"true"` | Adds `grid-breakout` to break out of the content column |
+| `id` | string | HTML `id` attribute |
+
+### `[row]` attributes
+
+| Attribute          | Type   | Description                                                                                   |
+|--------------------|--------|-----------------------------------------------------------------------------------------------|
+| `gap`              | number | Gap size token (`gap-N`)                                                                      |
+| `class`            | string | Extra CSS classes on the row wrapper                                                          |
+| `id`               | string | HTML `id` attribute                                                                           |
+| `reveal`           | flag   | Enables scroll-triggered reveal animations on child columns                                   |
+| `reveal-mode`      | string | `"stagger"` (default) or `"sequence"`                                                         |
+| `reveal-animation` | string | Animation type: `slide-up`, `slide-down`, `slide-left`, `slide-right`, `fade`, `zoom`, `flip` |
+| `reveal-duration`  | number | Animation duration in ms (default: `400`)                                                     |
+| `reveal-stagger`   | number | Delay between each child in ms (default: `60`)                                                |
+| `reveal-delay`     | number | Initial delay before first animation in ms (default: `0`)                                     |
+| `reveal-direction` | string | `"ltr"` (default) or `"rtl"`                                                                  |
+
+### Row with staggered reveal
+
+Columns animate into view one by one as the row scrolls into the viewport:
+
+```
+[row gap="4" reveal reveal-mode="stagger" reveal-animation="slide-up" reveal-duration="400" reveal-stagger="60"]
+[col]First to appear[/col]
+[col]Second to appear[/col]
+[col]Third to appear[/col]
+[/row]
+```
+
+### Row with fade and right-to-left direction
+
+```
+[row gap="3" reveal reveal-animation="fade" reveal-direction="rtl"]
+[col]Appears third[/col]
+[col]Appears second[/col]
+[col]Appears first[/col]
+[/row]
+```
+
+### Row with zoom and delay
+
+```
+[row gap="4" reveal reveal-animation="zoom" reveal-delay="200" reveal-stagger="100"]
+[col]Zooms in after 200ms[/col]
+[col]Zooms in after 300ms[/col]
+[/row]
+```
+
+### `[col]` attributes
+
+| Attribute | Type | Description |
+|---|---|---|
+| `span` | number | Number of columns to span (`col-span-N`) |
+| `id` | string | HTML `id` attribute |
+
+`[col]` also accepts injected effects (`reveal`, `breathe`, `animate`, `ripple`) - see [Effect injection](#effect-injection).
+
+### Rendered output
+
+```html
+<div class="grid grid-cols-2 gap-3">
+  <div>Left column content…</div>
+  <div>Right column content.</div>
+</div>
+```
+
+Note: `[col]` inside `[grid]` renders as a plain `<div>` (no `.col` class). The `.col` compatibility layer is not used.
+
+---
+
+## `[slideover]`
+
+Renders a trigger button that opens a Domma slideover panel when clicked.
+
+### Basic usage
+
+```
+[slideover title="More Information" trigger="Read more"]
+This content appears in a side panel.
+
+You can use **Markdown**, [cards](#), and other shortcodes here.
+[/slideover]
+```
+
+### All attributes
+
+| Attribute | Default | Description |
+|---|---|---|
+| `title` | `""` | Title shown in the slideover header |
+| `trigger` | `"Open"` | Label for the trigger button |
+| `size` | `"md"` | Panel width: `"sm"`, `"md"`, `"lg"` |
+| `position` | `"right"` | Which side the panel slides in from: `"right"` or `"left"` |
+
+### Rendered output
+
+```html
+<button class="btn btn-link dm-so-trigger" data-so-target="dm-so-1">Read more</button>
+<div class="dm-so-content" id="dm-so-1" style="display:none"
+     data-so-title="More Information"
+     data-so-size="md"
+     data-so-position="right">
+  <!-- Markdown body rendered here -->
+</div>
+```
+
+The public `site.js` wires `.dm-so-trigger` click events to open the corresponding slideover via `E.slideover()`.
+
+### Nesting shortcodes inside slideover
+
+`[card]`, `[grid]`, and other shortcodes are fully supported inside a slideover body:
+
+```
+[slideover title="Resources" trigger="View resources"]
+[grid cols="2"]
+[col]
+[card title="Guide"]Quick start guide.[/card]
+[/col]
+[col]
+[card title="API"]API reference.[/card]
+[/col]
+[/grid]
+[/slideover]
+```
+
+---
+
+## `[dconfig]`
+
+Embeds declarative page-specific behaviour configuration using Domma's `$.setup()` system. No JavaScript is required.
+
+### Basic usage
+
+```
+[dconfig]
+{
+  "#my-button": {
+    "events": {
+      "click": {
+        "target": "#my-panel",
+        "toggleClass": "hidden"
+      }
+    }
+  }
+}
+[/dconfig]
+```
+
+This wires a click on `#my-button` to toggle the `hidden` class on `#my-panel`, entirely through configuration.
+
+### How it works
+
+1. The server validates the JSON and base64-encodes it into a hidden `<div>`:
+
+   ```html
+   <div class="dm-page-config" style="display:none" data-config="eyIjbXktYnV..."></div>
+   ```
+
+2. `site.js` decodes and merges all `dm-page-config` blocks on the page (inline blocks merge with any `dconfig` set in the page editor's frontmatter - inline wins on key conflicts).
+
+3. `$.setup(merged)` is called, which wires all event handlers declaratively.
+
+### Multiple blocks
+
+You can use multiple `[dconfig]` blocks on one page. All valid blocks are merged:
+
+```
+[dconfig]
+{ "#btn-a": { "events": { "click": { "target": "#section-a", "toggleClass": "active" } } } }
+[/dconfig]
+
+[dconfig]
+{ "#btn-b": { "events": { "click": { "target": "#section-b", "toggleClass": "active" } } } }
+[/dconfig]
+```
+
+### Notes
+
+- Invalid JSON is silently dropped (no output, no error)
+- The `[dconfig]` shortcode is processed first in the pipeline, before all other shortcodes
+- `$.setup()` config can also be set per-page in the page editor's **DConfig** card (stored as `dconfig` in frontmatter)
+- Window-level `__CMS_DCONFIG__` (from frontmatter) and inline `dm-page-config` divs are merged at page load, with inline blocks taking precedence
+
+---
+
+## Additional Shortcodes
+
+The following shortcodes are also available in page Markdown:
+
+### `[tabs]` / `[tab]`
+
+```
+[tabs style="pills"]
+[tab title="First Tab"]First tab content.[/tab]
+[tab title="Second Tab"]Second tab content.[/tab]
+[/tabs]
+```
+
+Attributes on `[tabs]`: `style` (`"pills"`, `"bordered"`, or default underline), `align` (`"center"` or `"right"`),
+`fade` (flag - fade between panes), `id`.
+Attributes on `[tab]`: `title`, `icon` (Domma icon name shown before the title).
+
+---
+
+### `[accordion]` / `[item]`
+
+```
+[accordion]
+[item title="Question 1"]Answer to question 1.[/item]
+[item title="Question 2"]Answer to question 2.[/item]
+[/accordion]
+```
+
+Attributes on `[accordion]`: `multiple="true"` (allow multiple items open simultaneously), `id`.
+Attributes on `[item]`: `title`.
+
+---
+
+### `[carousel]` / `[slide]`
+
+```
+[carousel autoplay="true" interval="5000" animation="fade"]
+[slide title="Slide 1" image="/media/photo.jpg"]Caption text.[/slide]
+[slide title="Slide 2"]Text-only slide.[/slide]
+[/carousel]
+```
+
+`[carousel]` attributes: `autoplay`, `interval` (ms), `loop`, `animation` (`"slide"`, `"fade"`, or `"crossfade"`), `animation-duration` (ms, default 500), `animation-easing` (any CSS timing function - `ease`, `linear`, `ease-in-out`, `cubic-bezier(...)`), `height-mode` (`crop` or `average`), `height` (optional fixed height in pixels), `arrow-position` (`top`, `middle` or `bottom`; default `middle`), `background`, `arrow-background`, `arrow-color`, `id`. The colour attributes accept CSS colours or theme tokens such as `primary`, `accent`, `text` and `surface`; `background` colours the carousel area, while the two arrow attributes set the navigation button background and icon colour.
+
+Image carousels use one height across all slides and align images to the top with crop-to-fill scaling. The default `height-mode="crop"` uses the shortest image's height after scaling every image to the carousel width. `height-mode="average"` uses `(shortest scaled image height + tallest scaled image height) / 2`. Both recalculate when the carousel width changes. `height="420"` sets a fixed height instead. Text-only carousels keep their natural content height.
+`[slide]` attributes: `title`, `image` (URL). In the page editor, the image button beside each slide (and Browse in the right-click menu) picks a picture from Media or uploads one.
+
+`fade` swaps opacity per slide; `crossfade` overlaps the outgoing and incoming slides for a smoother dissolve.
+
+---
+
+### `[hero]`
+
+```
+[hero title="Welcome" tagline="Build something great" size="lg" variant="gradient-blue"]
+Optional body content with **Markdown** support.
+[/hero]
+```
+
+Attributes: `title`, `tagline`, `size` (`sm`, `lg`, `xl`, `full`), `variant` (see below), `image`, `overlay` (`light`, `dark`,
+`darker`, `gradient`, `gradient-reverse`), `align` (`center`, `left`; content alignment),
+`bg-x` (`left`, `center`, `right`) and `bg-y` (`top`, `center`, `bottom`) position the background image; both default to `center`.
+`bg-fit` (`contain` to show the whole image, `cover` to fill the area with cropping). Extra large (`xl`) is at least 75vh. All sizes fill the background area by default; Show whole image is an explicit option. `fullwidth="true"` independently makes the hero span the viewport. `bg` (background colour CSS value),
+`color` (background colour; takes precedence over `bg`), `min-height` (a number with `px`, `em`, `rem`, `vh`, `vw`
+or `%`, e.g. `"60vh"`), `fullwidth="true"` (break out of page container to span full viewport width),
+`twinkle` (flag - adds particle overlay), `twinkle-count` (number of particles),
+`twinkle-colour` (particle colour CSS value), `blobs` (flag - adds ambient blob background),
+`blobs-type` (blob animation type; default: `float-blobs`), `class`, `id`.
+
+`[hero]` also accepts injected effects (`reveal`, `breathe`, `pulse`, `twinkle`, `ticker-tape`, `butterflies`,
+`strobe`, `ambient`, `animate`) - see [Effect injection](#effect-injection).
+
+**Gradient variants:**
+
+| Variant                                                | Description            |
+|--------------------------------------------------------|------------------------|
+| `gradient-purple`                                      | Pastel lavender wash   |
+| `gradient-blue`                                        | Pastel sky blue        |
+| `gradient-green`                                       | Pastel mint green      |
+| `gradient-sunset`                                      | Pastel amber/gold      |
+| `gradient-ocean`                                       | Pastel sky/teal        |
+| `gradient-rose`                                        | Pastel rose pink       |
+| `gradient-forest`                                      | Pastel fresh green     |
+| `gradient-night`                                       | Muted slate dark       |
+| `gradient-ocean-light` / `gradient-ocean-dark`         | Ocean theme pastel     |
+| `gradient-forest-light` / `gradient-forest-dark`       | Forest theme pastel    |
+| `gradient-sunset-light` / `gradient-sunset-dark`       | Sunset theme pastel    |
+| `gradient-royal-light` / `gradient-royal-dark`         | Royal theme pastel     |
+| `gradient-lemon-light` / `gradient-lemon-dark`         | Lemon theme pastel     |
+| `gradient-silver-light` / `gradient-silver-dark`       | Silver theme pastel    |
+| `gradient-charcoal-light` / `gradient-charcoal-dark`   | Charcoal theme pastel  |
+| `gradient-christmas-light` / `gradient-christmas-dark` | Christmas theme pastel |
+| `gradient-unicorn-light` / `gradient-unicorn-dark`     | Unicorn theme pastel   |
+| `gradient-dreamy-light` / `gradient-dreamy-dark`       | Dreamy theme pastel    |
+| `gradient-grayve-light` / `gradient-grayve-dark`       | Grayve theme pastel    |
+| `gradient-mint-light` / `gradient-mint-dark`           | Mint theme pastel      |
+| `gradient-wedding-light` / `gradient-wedding-dark`     | Wedding theme pastel   |
+
+---
+
+### `[table]`
+
+Wraps a GFM Markdown table with Domma table classes and a responsive container:
+
+```
+[table striped="true" caption="Sales Data"]
+| Product | Price |
+| ------- | ----: |
+| Widget  | $9.99 |
+[/table]
+```
+
+Attributes: `striped="true"`, `bordered="true"`, `compact="true"`, `caption`, `class`, `id`.
+
+---
+
+### `[badge]`
+
+Inline badge - renders a styled `<span>`:
+
+```
+[badge variant="success"]New[/badge]
+[badge variant="danger" outline pill]Deprecated[/badge]
+[badge variant="warning" size="small"]Beta[/badge]
+```
+
+Self-closing (empty badge, useful as a colour dot):
+
+```
+[badge variant="primary" pill /]
+```
+
+Attributes: `variant` (`primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark`), `pill` (flag), `outline` (flag), `size` (`"small"` or `"large"`).
+
+---
+
+### `[countdown]`
+
+Self-closing. Renders a countdown timer initialised client-side by `E.timer()`:
+
+```
+[countdown to="2026-12-31" format="DD:HH:mm:ss" /]
+[countdown duration="300" format="mm:ss" /]
+```
+
+Attributes: `to` (ISO date - counts down to it), `duration` (seconds), `format` (`mm:ss`, `HH:mm:ss`, `DD:HH:mm:ss`),
+`id`. Without a `format`, a countdown of an hour or more shows `HH:mm:ss`.
+
+---
+
+### `[timeline]` / `[event]`
+
+```
+[timeline layout="vertical" theme="modern"]
+[event title="Launch" date="2025-01-15" status="completed" icon="rocket"]
+Project launched successfully.
+[/event]
+[event title="V2 Release" date="2026-06-01" status="planned"]
+Next major release.
+[/event]
+[/timeline]
+```
+
+`[timeline]` attributes: `layout` (`vertical`, `centred`, `horizontal`), `theme` (`minimal`, `corporate`, `modern`), `mode` (`timeline`, `roadmap`), `class`, `id`.
+`[event]` attributes: `title`, `date`, `status` (`planned`, `in-progress`, `completed`, `blocked`), `icon` (kept on the
+item as `data-event-icon`; the timeline's markers show the status icon).
+
+---
+
+### `[listgroup]` / `[item]`
+
+Renders a Domma list group. Each `[item]` body takes inline Markdown.
+
+```
+[listgroup variant="flush" size="sm" itemvariant="info" action="true"]
+[item]**First** item[/item]
+[item]Second item with a [link](/about)[/item]
+[/listgroup]
+```
+
+`[listgroup]` attributes: `variant` (`flush`, `numbered` or `horizontal`), `size` (`sm` or `lg`), `itemvariant`
+(`primary`, `secondary`, `success`, `danger`, `warning` or `info` - colours every item), `action="true"` (hover/click
+styling on items). `[item]` takes no attributes. The same styling is available for collections with
+`[collection display="listgroup"]`.
+
+---
+
+### `[banner]`
+
+An alert-style message strip with an optional icon, title and dismiss button. The body is Markdown.
+
+```
+[banner type="warning" title="Maintenance" icon="alert-triangle" dismissible]
+The site will be read-only on **Sunday** from 8am.
+[/banner]
+```
+
+| Attribute | Description |
+|---|---|
+| `type` | `info` (default), `success`, `warning`, `danger` or `neutral` |
+| `title` | Bold title shown above the body |
+| `icon` | Domma icon name shown at the left |
+| `dismissible` | Flag - adds a close button |
+| `class` | Extra CSS classes on the banner |
+
+`[banner]` also accepts injected effects (`reveal`, `pulse`, `shake`, `ambient`, `animate`) - see
+[Effect injection](#effect-injection). It is processed late (after `[card]` and `[grid]`), so it cannot be nested inside
+a card, grid, tab or similar container body - place it at the top level of the page, or inside `[center]` or
+`[slideover]`.
+
+---
+
+### `[text]`
+
+Wraps inline text in a `<span>` with custom styles. All attributes are optional.
+
+```
+[text size="xl" bold italic color="primary"]Styled text[/text]
+[text font="Georgia" decoration="underline" spacing="wide"]Classic[/text]
+[text size="2em" color="#ff6600"]Custom size and colour[/text]
+```
+
+### Attributes
+
+| Attribute    | Values                                                                                      | Notes                                                               |
+|--------------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
+| `size`       | `xs` `sm` `base` `lg` `xl` `2xl` `3xl` `4xl` or raw CSS (e.g. `"1.5em"`)                    | Maps to `font-size`                                                 |
+| `point-size` | A positive number, e.g. `"14"`                                                              | Sets `font-size` in points (`14pt`)                                 |
+| `weight`     | `thin` `light` `normal` `medium` `semibold` `bold` `extrabold` `black`                      | Maps to `font-weight`                                               |
+| `bold`       | flag                                                                                        | Shorthand for `font-weight:700`. Overrides `weight` if both present |
+| `italic`     | flag                                                                                        | `font-style:italic`                                                 |
+| `color`      | Token (`primary` `secondary` `muted` `danger` `success` `warning` `info`) or any CSS colour | Maps to `color` (`colour` also works)                               |
+| `font`       | `Georgia` `Arial` `Verdana` `Courier New` `Times New Roman` `Trebuchet MS`                  | Web-safe fonts only                                                 |
+| `transform`  | `upper` `lower` `capitalize` `none`                                                         | Maps to `text-transform`                                            |
+| `decoration` | `underline` `line-through` `none`                                                           | Maps to `text-decoration`                                           |
+| `spacing`    | `tight` `normal` `wide` `wider` or raw CSS (e.g. `"0.1em"`)                                 | Maps to `letter-spacing`                                            |
+| `align`      | Any `text-align` value (`left` `center` `right` `justify`)                                   | Makes the span `display:block` and sets `text-align`                |
+| `style`      | Raw CSS declarations                                                                        | Appended to the generated inline style                              |
+| `class`      | CSS class name(s)                                                                           | Added to the `<span>` element                                       |
+| `id`         | Element ID                                                                                  | Added to the `<span>` element                                       |
+
+### Notes
+
+- `align` turns the span into a block so the alignment takes effect. For centring larger blocks of content, `[center]`
+  or a grid/card is usually a better fit.
+- The Page Editor's Insert menu has a **Text** entry that opens the shortcode form for it - every attribute in this
+  table, with a live preview of the tag it will insert. The same form is reachable by right-clicking an existing
+  `[text]` tag and choosing **Edit Text…**.
+
+---
+
+### `[spacer]`
+
+Self-closing. Inserts a vertical gap:
+
+```
+[spacer /]
+[spacer size="48" /]
+[spacer size="24" class="mt-4" /]
+```
+
+Attributes: `size` (px height; defaults to `layoutOptions.spacerSize` from `config/site.json`), `class`.
+
+---
+
+### `[contents]`
+
+Self-closing. This page's own settings for its **page contents** - the list a layout with a sidebar
+(With Sidebar) builds from the page's headings - over the layout's (**Layouts → Page contents
+settings**). It draws nothing itself; the first `[contents]` on a page counts.
+
+```
+[contents numbered="true" headings="h2h3" title="On this page" /]
+[contents side="right" collapsible="true" collapsed="true" /]
+[contents floating="true" float-anchor="BR" movable="true" /]
+[contents hidden="true" /]
+```
+
+Attributes: `side` (left / right), `width` (160-480 px), `sticky`, `floating`, `float-anchor` (TL, TR,
+BL, BR, L, R), `movable`, `hidden`, `collapsible`, `collapsed`, `autohide`, `scroll-spy`, `headings`
+(auto - H2s, else H3s - / h2 / h3 / h2h3), `numbered`, `title`, `exclude` (headings to leave out, comma
+separated), `hover`, `selected` (the menus' highlight effects), `accent`, `font`, `font-size`,
+`font-weight`. `true` / `false` switch a setting on or off. Floating wins over autohide, and both over
+collapse. The older front matter `sidebarSide` still works (the tag wins over it).
+
+---
+
+### `[navbar]`
+
+Self-closing. This page's own navbar settings, over the navbar menu's - for this page only. It draws
+nothing itself.
+
+```
+[navbar collapsed="true" /]
+[navbar autohide="true" width="200" /]
+[navbar orientation="horizontal" position="sticky" hide-on-scroll="true" /]
+[navbar position="floating" float-anchor="TR" float-collapsible="true" /]
+```
+
+Every Behaviour setting of a menu is an attribute: `position`, `orientation`, `side`, `align`,
+`variant`, `hover-open`, `hover`, `selected`, `accent`, `class`, `font`, `font-size`, `font-weight`,
+`letter-spacing`, `icon-size`, `width`, `collapsible`, `collapsed`, `autohide`, `hide-on-scroll`, and the
+floating panel's `float-anchor`, `float-x`, `float-y`, `float-width`, `float-radius`, `float-shadow`,
+`float-accent`, `float-opacity`, `float-title`, `float-collapsible`, `float-collapsed`, `float-movable`,
+`float-resizable`. `true` / `false` switch a setting on or off (so a page can turn off what the menu
+turns on); an empty value clears it back to the default. The first `[navbar]` on a page counts. The
+result is checked like a saved menu - an override that would not validate is ignored whole.
+
+In the page editor it is under Insert → Layout; right-clicking it offers one-click actions (collapse,
+autohide or keep the rail open on this page, hide the bar on scroll, remove the override) and the most
+used settings, with the rest in **Edit…**.
+
+---
+
+### `[theme-switcher]`
+
+Self-closing. The site's theme dots, placed by the page:
+
+```
+[theme-switcher /]
+[theme-switcher position="bottom-left" offset-x="24" offset-y="24" /]
+[theme-switcher themes="charcoal-dark,charcoal-light" /]
+```
+
+Attributes:
+
+- `position` - `inline` (the default: where the tag stands, inside the text if you like) or pinned to
+  the window: `top-left`, `top-right`, `left-center`, `right-center`, `bottom-left`, `bottom-right`
+- `offset-x`, `offset-y` - distance from the window's edges in px when pinned (0-400, default 32)
+- `themes` - a comma list narrowing the themes chosen under **Theme > Theme switcher**; the site's
+  list when absent or when none of the names match
+
+It works with the floating switcher off. On its page it takes the floating switcher's place, so a
+page never shows two; a switcher in a menu (`{"type": "theme-switcher"}`) is kept.
+
+---
+
+### `[center]`
+
+```
+[center]This content is centred.[/center]
+[center class="my-section"]More centred content.[/center]
+```
+
+Attributes: `class`.
+
+---
+
+### `[icon]`
+
+Self-closing. Renders a Domma icon inline:
+
+```
+[icon name="arrow-right" /]
+[icon name="star" size="24" color="#f59e0b" /]
+```
+
+Attributes: `name` (required - Domma icon name), `size` (px), `color` (CSS colour), `class`.
+
+---
+
+### `[embed]`
+
+Self-closing. Embeds a video or an external page. The `url` is auto-detected and rendered as the right element:
+
+- **YouTube / Vimeo** links → a privacy-friendly responsive `<iframe>` (`youtube-nocookie.com` / `player.vimeo.com`).
+- **Self-hosted video** (`.mp4`, `.webm`, `.ogg` - e.g. an uploaded `/media/…` file) → a native `<video>` player with controls.
+- **Any other URL** → a generic `<iframe>`, but **only if its host is in the allow-list** at `config/embeds.json`; otherwise a visible "not allowed" placeholder is shown.
+
+```
+[embed url="https://youtu.be/dQw4w9WgXcQ" /]
+[embed url="/media/showreel.mp4" ratio="16:9" title="Our showreel" /]
+[embed url="https://www.google.com/maps/embed?pb=…" width="640" align="center" /]
+[embed url="/media/hero.mp4" autoplay muted loop /]
+```
+
+| Attribute  | Description                                                                       |
+|------------|-----------------------------------------------------------------------------------|
+| `url`      | YouTube/Vimeo link, self-hosted video path, or generic iframe URL (**required**)  |
+| `ratio`    | Aspect ratio - `16:9` (default), `4:3`, `1:1`, `21:9`, `9:16`, `3:4`, or `W:H`     |
+| `title`    | Accessibility title on the frame **and** a visible caption underneath             |
+| `width`    | Max width in px or % (e.g. `640`, `80%`)                                           |
+| `align`    | `left`, `center`, or `right` (when `width` is set)                                 |
+| `autoplay` | Flag - starts playback automatically (forces `muted`, per browser policy)          |
+| `loop`     | Flag - loops playback                                                              |
+| `muted`    | Flag - starts muted                                                               |
+
+**Security:** generic iframes are gated by a host allow-list. Add trusted hosts to `config/embeds.json`:
+
+```json
+{ "allowedHosts": ["www.google.com", "codepen.io", "open.spotify.com"] }
+```
+
+The allow-list is enforced twice - at render time (the placeholder) and again in the HTML sanitiser
+(`allowedIframeHostnames`) - so a host that is not listed can never be framed. YouTube and Vimeo are always allowed.
+
+The editor's **Insert → Embed** menu opens a builder with a URL field, a "browse self-hosted video" picker, and live
+shortcode preview.
+
+---
+
+### `[form]`
+
+Self-closing. Embeds a CMS-managed form by slug. Forms are configured under **Forms** in the sidebar.
+
+```
+[form name="contact" /]
+[form name="newsletter" class="mt-4" id="newsletter-form" /]
+```
+
+| Attribute       | Description                          |
+|-----------------|--------------------------------------|
+| `name` / `slug` | Form slug (required)                 |
+| `class`         | Extra CSS classes on the wrapper div |
+| `id`            | `id` attribute on the wrapper div    |
+
+The form's own CSS classes (set in the form builder: Settings, Submit Button and each field) go on the `<form>`, the submit button and each field's wrapper; `class` here is for this placement's wrapper only.
+
+---
+
+### `[collection]`
+
+Self-closing. Renders a CMS collection inline on a public page. Supports table, cards, list, accordion, timeline, and
+block display modes, with structured filtering and per-user scoping.
+
+```
+[collection slug="enquiries" display="table" /]
+[collection slug="team" display="cards" columns="3" title-field="name" /]
+[collection slug="products" display="list" limit="10" sort="price" order="asc" /]
+[collection slug="jobs" where_location="London" where_salary_gte="50000" /]
+[collection slug="applications" scope="mine" display="cards" /]
+```
+
+| Attribute        | Description                                                                                                  |
+|------------------|--------------------------------------------------------------------------------------------------------------|
+| `slug`           | Required. The collection slug                                                                                |
+| `display`        | `table` (default), `cards`, `list`, `accordion`, `timeline`, `carousel`, `listgroup`, or `block`             |
+| `fields`         | Comma-separated field keys to show. Defaults to all                                                          |
+| `limit`          | Maximum number of entries to display (`0` or unset = no limit)                                               |
+| `sort`           | Field key to sort by (default `createdAt`)                                                                   |
+| `order`          | `asc` or `desc` (default `desc`)                                                                             |
+| `title-field`    | Field used as the card/list title (`cards` + `list` modes)                                                   |
+| `columns`        | Grid columns for `cards` display (2-4, default 3)                                                            |
+| `search`         | `true`/`false` - enable search in table mode (default `true`)                                                |
+| `sortable`       | `true`/`false` - enable column sorting in table mode (default `true`)                                        |
+| `exportable`    | `true`/`false` - show CSV export button in table mode (default `false`)                                      |
+| `page-size`      | Rows per page in table mode (default 25)                                                                     |
+| `empty`          | Text shown when there are no entries                                                                         |
+| `where`          | Legacy single-attribute filter - `"field=value,field2=value2"`. Equality only, AND-combined                  |
+| `where_<field>`  | Modern per-field filter - see **Structured filtering** below                                                 |
+| `scope`          | `mine` to render only entries created by the current user (per-user hydration; requires sign-in)             |
+| `cta`            | Action slug: enables per-entry CTA buttons                                                                   |
+| `cta-label`      | CTA button label (default: `"Run"`)                                                                          |
+| `cta-icon`       | CTA button icon name                                                                                         |
+| `cta-style`      | CTA button variant (default: `primary`)                                                                      |
+| `cta-confirm`    | CTA confirmation prompt text                                                                                 |
+| `transitions`    | Bare flag: lazy-loads available state-machine transitions per row and renders them as buttons (interactive Browser only; works with `scope="mine"`) |
+| `class`          | Extra CSS classes on the wrapper div                                                                         |
+| `item-class`     | Your own CSS classes on every entry's wrapper (cards, list, accordion, timeline, carousel, listgroup and block; not table rows, which are drawn in the browser) |
+| `id`             | `id` attribute on the wrapper div                                                                            |
+
+Table display uses Domma Table - search, sort, pagination, column selector, and CSV export are all built in. Cards and
+list are static.
+
+#### Timeline, carousel, and listgroup modes
+
+`display="timeline"` renders entries as a Domma progression. Field mapping: `title-field` (default `title`),
+plus optional `date-field`, `status-field`, `icon-field`, and `body-field` (Markdown). Layout attrs: `layout`
+(`vertical` | `centred` | `horizontal`), `theme` (`minimal` | `corporate` | `modern`), `mode`
+(`timeline` | `roadmap`). The public site JS hydrates the server markup into the full Domma progression
+component (markers, connectors, status icons).
+
+`display="carousel"` renders one slide per entry. It also accepts `height-mode` and `height` with the same sizing rules as `[carousel]`. Field mapping: `image-field`, `title-field`, `body-field`
+(Markdown). The `[carousel]` behaviour and colour attrs pass through: `autoplay`, `interval`, `loop`, `animation`,
+`animation-duration`, `animation-easing`, `arrow-position`, `background`, `arrow-background`, `arrow-color`.
+
+`display="listgroup"` renders one list-group item per entry. Field mapping: `title-field`, `body-field`
+(inline Markdown). Styling attrs match `[listgroup]`: `variant` (`flush` | `numbered` | `horizontal`),
+`size` (`sm` | `lg`), `itemvariant`, `action="true"`.
+
+Both `carousel` and `listgroup` also accept `block="<name>"` - each entry is then rendered through that
+reusable block template (same `{{field}}` placeholders as `display="block"`) instead of the field mapping,
+so any custom per-entry design works inside a carousel slide or list row.
+
+#### Right-click search & filter (all displays)
+
+Every collection-rendered display on the public site is filterable in place: visitors right-click any
+entry to get a context menu with quick filters on the clicked value (`=`, `≠`, and `>`/`<` for
+numeric/date values), a free-text search across the displayed fields, and removable filter chips above
+the display. The cursor changes to a custom filter cursor (arrow + funnel badge) over filterable
+content - a custom SVG cursor because the native `context-menu` cursor is unsupported on Windows. Only the fields the
+display actually shows are exposed - hidden fields never reach the page. No configuration needed;
+it works for cards, list, accordion, timeline, carousel, listgroup, block, and table modes on both
+`[collection]` and `[view]`.
+
+This menu owns the display it sits on: it is registered as an exclusive context menu, so another
+right-click menu placed on the page cannot take over a collection display and quietly remove filter,
+sort and export from it. Right-clicking outside any collection reaches whatever other menu the page
+defines, as normal.
+
+The same menu also offers **Sort…**, **Group by…**, **Copy…** (visible entries as CSV/JSON/Markdown),
+**Export…** (a download, gated by the collection's `export` permissions - see
+`docs/configuration.md`), **Print**, and **Copy link to this view**. Availability of Sort, Group and
+Export/copy varies by display type:
+
+| Display                                  | Filter | Sort | Group | Export / copy |
+|-------------------------------------------|--------|------|-------|----------------|
+| cards, list, listgroup, accordion, block  | yes    | yes  | yes   | yes            |
+| table                                      | yes    | yes  | -     | yes            |
+| timeline                                   | yes    | yes  | -     | yes            |
+| carousel                                   | yes    | yes  | -     | yes            |
+
+Grouping inserts a heading element between sibling entries, which only works where entries are
+rendered as direct DOM siblings - true of the five toggle-based display types (cards, list,
+listgroup, accordion, block), which filter by toggling a hidden class on each `[data-entry-id]`.
+The other three manage their own rendering and have nowhere for an injected heading to go:
+
+- **table** - rows are re-rendered by `T.create` and paginated; an injected heading row would fight
+  pagination and the table's own re-render
+- **timeline** - driven by the Progression instance's `.setItems()`, which takes a flat item list,
+  not section headers
+- **carousel** - slides are a sequence, and entries live inside `.carousel-track` rather than as
+  direct siblings of the wrapper
+
+The **Group by…** row is hidden, not disabled, on the three unsupported types.
+
+Sort, filters and grouping all persist in the URL hash (`#dmf=…`, keyed per display), so a
+filtered/sorted/grouped view survives a reload and can be bookmarked or shared - opening the link
+re-applies filters, sort, group and chips. Existing anchor fragments are preserved alongside the
+filter segment. **Copy link to this view** (in the same menu) writes the current state to the hash
+and copies the resulting URL to the clipboard.
+
+```
+[collection slug="events" display="timeline" title-field="title" date-field="date" body-field="summary" /]
+[collection slug="testimonials" display="carousel" image-field="photo" title-field="name" body-field="quote" autoplay="true" /]
+[collection slug="faqs" display="listgroup" variant="flush" title-field="question" body-field="answer" /]
+[collection slug="team" display="carousel" block="profile-card" /]
+```
+
+#### Structured filtering
+
+Add a filter by writing `where_<field>` or `where_<field>_<op>` attributes. Operators:
+
+| Suffix      | Meaning                            | Example                                  |
+|-------------|------------------------------------|------------------------------------------|
+| (none)      | equal                              | `where_location="London"`                |
+| `_eq`       | equal (explicit)                   | `where_status_eq="open"`                 |
+| `_ne`       | not equal                          | `where_status_ne="closed"`               |
+| `_gt`       | greater than                       | `where_salary_gt="40000"`                |
+| `_gte`      | greater than or equal              | `where_salary_gte="50000"`               |
+| `_lt`       | less than                          | `where_salary_lt="100000"`               |
+| `_lte`      | less than or equal                 | `where_postedAt_lte="2026-06-01"`        |
+| `_in`       | value in comma-separated list      | `where_type_in="full-time,contract"`     |
+| `_nin`      | value not in list                  | `where_status_nin="archived,withdrawn"`  |
+| `_contains` | substring match (case-insensitive) | `where_title_contains="engineer"`        |
+| `_starts`   | starts-with (case-insensitive)     | `where_title_starts="Senior"`            |
+| `_ends`     | ends-with (case-insensitive)       | `where_email_ends="@example.com"`        |
+| `_exists`   | field is present and non-null      | `where_remote_exists="true"`             |
+
+Predicates AND together. For OR or NOT, define a saved view (`content/views/`) and use `[view slug="…"]`.
+
+Two pseudo-fields are also recognised: `createdBy` (matches `meta.createdBy`) and `id` (matches the top-level entry id).
+Dot-paths into nested data work - `where_address.city_eq="London"` matches `entry.data.address.city`.
+
+The same DSL is honoured by:
+
+- The collection list API: `GET /api/collections/jobs/entries?filter[location]=London&filter[salary_gte]=50000`
+- The public read API: `GET /api/collections/jobs/public?filter[location]=London`
+
+Filtering is pushed down to the storage adapter - MongoDB sees a native `$gte` query, File mode does an in-memory pass.
+
+#### Interactive Collection Browser
+
+Add any of `searchable`, `sortable`, `filterable="…"`, or `paginate` to flip a `[collection]` block from a static
+render into a fully interactive **Collection Browser** - search box, sort dropdown, schema-derived filter rail,
+and pagination, all wired up automatically.
+
+```
+[collection slug="jobs"
+  display="cards" columns="3"
+  searchable
+  filterable="location,type,salary,tags"
+  sortable
+  page-size="9"
+  empty="No matching jobs." /]
+```
+
+The browser is **opt-in**: existing blocks without these attributes still render statically and look exactly as
+before. Once any interactive attr is present, the server emits a hydration shell with the schema + initial data
+and `public/js/collection-browser.js` takes over.
+
+| Attribute            | Description                                                                                                |
+|----------------------|------------------------------------------------------------------------------------------------------------|
+| `searchable`         | Render a free-text search box (substring match across all fields)                                          |
+| `sortable`           | Bare flag: sort by any field. Or `sortable="title,salary,postedAt"` to restrict the dropdown               |
+| `filterable`         | Comma-separated field names - each becomes a filter control in the rail                                    |
+| `paginate`           | Bare flag: enable pagination even without other interactive features                                       |
+| `pagination`         | `pages` (default) - prev/next pager. `scroll` - infinite scroll via IntersectionObserver                  |
+| `page-size`          | Entries per page (default `12`)                                                                            |
+| `mode`               | `client` (default) - ship all data inline, filter in browser. `server` - fetch each page from the API     |
+| `max-client-entries` | In client mode, the cap before auto-downgrading to server mode (default `1000`)                            |
+| `exportable`         | Bare flag: show an "Export CSV" button in the header                                                       |
+| `no-saved-searches`  | Bare flag: hide the saved-searches dropdown (it's on by default)                                          |
+| `no-url-sync`        | Bare flag: don't sync filter/sort/search/page to the URL query string (URL sync is on by default)          |
+
+**Filter controls are derived from each field's `type` in the collection schema:**
+
+| Field type                      | Control                                                | Operator |
+|---------------------------------|--------------------------------------------------------|----------|
+| `text`, `textarea`, `email`     | Text input                                             | `_contains` |
+| `number`                        | Min/max input pair                                     | `_gte` / `_lte` |
+| `date`, `datetime`              | From/to date picker                                    | `_gte` / `_lte` |
+| `select`, `chooser`             | Single dropdown (options from schema or distinct values) | `_eq` |
+| `multiselect`, `tags`, `tag`    | Multi-pick checkbox group                              | `_in` |
+| `boolean`, `checkbox`           | Any / Yes / No dropdown                                | `_eq` |
+
+For fields without `options` in the schema, the browser **auto-discovers distinct values** from the current dataset
+- so `filterable="location"` on a plain text field still gives you a useful dropdown.
+
+**Author-baked filters compose with user filters.** A `where_*` attribute is locked-in - the user can narrow further
+but never widen past it:
+
+```
+[collection slug="jobs"
+  searchable filterable="location,salary"
+  where_status="open" /]
+```
+
+The job board only ever shows open roles; the user picks from London/Berlin/Remote and adjusts the salary range
+within that pool.
+
+**URL state sync** (default on) pushes the user's choices to `?cb_<id>_search=…&cb_<id>_filter[location]=London&…`
+via `history.replaceState`. Deep-linking, sharing filtered views, and the browser back button all work without a
+full page reload. Multiple browsers on one page use distinct id-prefixed param names.
+
+**`mode="server"`** is the right choice for large collections that won't fit comfortably in a single page payload.
+Every search/sort/filter/page change becomes a `GET /api/collections/:slug/public?filter[…]=…&page=…` round-trip;
+the storage adapter (Mongo or File) handles the heavy lifting. Client mode is faster for small datasets but ships
+all entries inline.
+
+##### Power-user features (all on by default unless noted)
+
+- **Facet counts** - each multi-pick chip and single-select option shows how many entries would match if that
+  option were toggled with the user's other current filters. Standard faceted-search behaviour so users see
+  what's available before clicking. **Client mode only** - server mode would need a separate aggregate endpoint;
+  the page-bounded total there would mislead.
+- **Mobile filter drawer** - on viewports under 768 px a "Filters (n)" button replaces the rail; tapping it
+  slides the rail in from the left with a dimmed overlay. The badge counts active conditions.
+- **Saved searches** - header dropdown that captures the current state under a user-chosen name. Stored in
+  browser `localStorage` keyed per-browser id (`cb_saved_<id>`). Disable with `no-saved-searches`.
+- **CSV export** - adds a button in the header (`exportable` attr). Client mode builds the file from the
+  current filtered set in JS; server mode hits the existing `/api/collections/:slug/export?format=csv&filter=…`
+  endpoint with the active filter applied.
+- **Relevance sort** - when the search box has a term AND the user hasn't manually picked a sort, results are
+  ordered by match count (with a 3× boost on matches in `title-field`). Switching the sort dropdown to anything
+  explicit takes over.
+- **Keyboard shortcuts** - `/` focuses the first browser's search box; `←` / `→` pages backwards/forwards on
+  the browser containing the focused element. Disabled while you're typing in an input.
+- **Infinite scroll** (`pagination="scroll"`) - replaces the pager with a sentinel that loads more on scroll.
+  Subsequent pages append rather than replace; filter/sort changes reset to page 1 normally.
+- **Server-mode debounce + abort** - in-flight fetches are cancelled when a new state change supersedes them, so
+  fast typing in the search box doesn't fight for response order.
+- **Polished controls** - multiselect renders as toggleable chips with counts; numeric ranges add a dual-handle
+  slider above the min/max inputs (when bounds can be derived from the dataset).
+
+##### State-machine transitions
+
+Set `transitions` on an interactive `[collection]` block (one with `searchable`,
+`sortable`, `filterable` or `paginate`) and each row sprouts buttons for
+the actions that legally apply to that row's current state - based on the
+`transition: { field, from, to }` config on action definitions.
+
+```
+[collection slug="applications" display="cards"
+  title-field="jobId"
+  searchable transitions /]
+```
+
+`transitions` has no effect on a static `[collection]`. On a `scope="mine"` block it works the same once
+the block is interactive (see [Per-user scoping](#per-user-scoping---scopemine)): each row is one of the
+viewer's own, and the server refuses a transition on any other row.
+
+Behind the scenes each row's transitions are fetched independently via
+`GET /api/actions/transitions?collection=applications&entryId=…`, which
+returns only the actions whose:
+
+- `transition.from` includes the row's current value of `transition.field`, **and**
+- `access.roles` admits the requesting user - any listed role is enough, and every more senior role
+  inherits it (the page-visibility ladder; a role name the site does not have admits only the level-0 role), **and**
+- the action's `access.rowLevel` rule, if any, passes for that row
+
+That means a candidate viewing their application in `status: submitted` sees
+a "Withdraw" button, but the same UI viewed after the application moves to
+`status: rejected` shows no actions - there's nothing they can do from a
+terminal state. No client-side conditionals; the server's transition rules
+are the only source of truth.
+
+Action-side configuration looks like:
+
+```json
+{
+  "slug": "withdraw-application",
+  "title": "Withdraw",
+  "collection": "applications",
+  "transition": {
+    "field": "status",
+    "from":  ["submitted", "reviewing"],
+    "to":    "withdrawn"
+  },
+  "access": { "roles": ["candidate"], "rowLevel": { "ownerField": "createdBy" } },
+  "steps": [
+    { "type": "updateField", "config": { "field": "status", "value": "withdrawn" } }
+  ]
+}
+```
+
+Execute-time validation rejects illegal moves with HTTP 409 - so an action
+URL someone copies and pastes after the state has changed gets a clean
+"Cannot apply X - current status is Y" message rather than mutating data
+out from under the rules.
+
+##### Interactive saved views
+
+`[view slug="…"]` shortcodes can opt into the Browser the same way:
+
+```
+[view slug="employer-applications" searchable sortable page-size="20" /]
+```
+
+Because saved views may aggregate across collections (joins, projections), they don't expose a filter rail by
+default - the view itself owns its filter logic. But search, sort, pagination, saved searches, and CSV export all
+work. This is how you give users an interactive UI over a complex cross-collection query without re-inventing the
+join in shortcode syntax.
+
+#### Per-user scoping - `scope="mine"`
+
+Add `scope="mine"` to render only entries created by the current signed-in user. The page is still cached per role,
+but the scoped block is replaced with a hydration placeholder that fetches the user's data client-side
+(`POST /api/collections/render-scope`). This keeps caching efficient while making per-user "My Applications" / 
+"My Bookmarks" / "My Orders" patterns trivial.
+
+```
+[collection slug="applications" scope="mine" display="cards" title-field="jobTitle" /]
+```
+
+Anonymous visitors see a "Please sign in" prompt where the block would render. The endpoint never trusts the client
+to declare which user they are - the JWT is verified server-side and `createdBy = <user.id>` is injected before
+re-running the render pipeline.
+
+The collection does not need `api.read` enabled for `scope="mine"` to work - by definition the user can only see
+their own entries.
+
+Make the block interactive (`searchable`, `sortable`, `filterable` or `paginate`) and it hydrates as the Collection
+Browser instead of a static list - still only the viewer's rows, with paging fetched as `scope=mine` - and
+`transitions` then works on it:
+
+```
+[collection slug="applications" scope="mine" display="cards" title-field="jobId" paginate transitions /]
+```
+
+Everything that block does is scoped on the server: the transition list (`GET /api/actions/transitions?…&scope=mine`)
+offers nothing on another user's row, and running a transition or `cta` from it sends `scope: "mine"`, so
+`POST /api/actions/:slug/public` answers 403 (`Row-level access denied`) for a row the viewer did not create - before
+the state check, so an illegal move on their own row is still 409. The hard boundary against someone calling the
+action directly is the action's own `access` (its roles and `rowLevel`), so give an action meant for "my rows"
+`"rowLevel": {"mode": "owner"}` as well.
+
+---
+
+### `[block]`
+
+Renders a single block template with static inline data. Use this for one-off content where creating a full Collection
+would be unnecessary.
+
+**Syntax:**
+
+```
+[block template="post-card" title="My Post" author="Jane Doe" excerpt="A short intro." /]
+```
+
+**Attributes:**
+
+| Attribute  | Required | Description                                                                              |
+|------------|----------|------------------------------------------------------------------------------------------|
+| `template` | Yes      | Name of the block template (files in `content/blocks/`)                                  |
+| `*`        | No       | Any other attribute is passed as data for `{{placeholder}}` substitution in the template |
+
+**Placeholders in the template:**
+
+| Placeholder | Behaviour |
+|---|---|
+| `{{field}}` | Value is HTML-escaped before substitution |
+| `{{{field}}}` | Value is inserted **raw**, without escaping - use only for trusted HTML |
+| `{{field:FORMAT}}` | Formats the value as a date, e.g. `{{date:DD MMM YYYY}}`. Tokens: `YYYY YY MMMM MMM MM M DD D dddd ddd HH H hh h mm m ss s A a`. A value that is not a valid date is output unformatted |
+
+**Notes:**
+
+- If the named template does not exist, the shortcode is silently removed.
+- Missing placeholder values render as empty strings.
+- `class` and `id` attributes are applied to the wrapping `<div class="dm-static-block">`.
+- If the block has companion CSS (`content/blocks/<name>.css`), it is emitted once alongside the block, scoped to
+  `[data-block="<name>"]`.
+- To create or edit block templates, go to **Data > Blocks**.
+
+**Short tags:** every block can also be used with its own name as the tag. These two lines are equivalent:
+
+```
+[block template="contact-card" full_name="Jane Doe" /]
+[contact-card full_name="Jane Doe" /]
+```
+
+Short tags are self-closing only, and only work for block names made of lowercase letters, digits and hyphens that
+do not clash with a built-in shortcode name (a block called `card` or `menu`, for example, can only be used through
+`[block template="…"]`).
+
+**Example:**
+
+```
+[block template="contact-card"
+  full_name="Jane Doe"
+  phone_number="555-1234"
+  email_address="jane@example.com" /]
+```
+
+---
+
+### `[component]`
+
+Mounts a custom web component (a `.dmc` component from **Data > Components**, stored in
+`content/components/<name>.dmc`). The shortcode is rewritten to the component's custom-element tag, so these two lines
+are equivalent:
+
+```
+[component name="counter" initial="5" /]
+<dm-counter initial="5"></dm-counter>
+```
+
+`name` is required (lowercase letters, digits and hyphens); every other attribute is passed to the element as a prop.
+Only the scripts for components actually used on the page are loaded, and a tag for a component that does not exist
+is stripped. Components are processed first, before any other shortcode, so they can be written inside any container.
+
+---
+
+### `[menu]`
+
+Self-closing. Renders any menu (by slug or by mapped location) inline as a nested `<nav>` of `<ul>`s. Menus are defined in `config/menus/<slug>.json` and mapped to slots in `config/menu-locations.json` (see `docs/configuration.md`).
+
+```
+[menu slug="legal" /]
+[menu location="footer-primary" /]
+[menu slug="legal" variant="inline" class="prose-nav" /]
+[menu slug="legal" depth="2" /]
+[menu slug="main" orientation="horizontal" /]
+```
+
+| Attribute     | Description                                                                              |
+|---------------|------------------------------------------------------------------------------------------|
+| `slug`        | Render this menu by slug. One of `slug` or `location` is required                        |
+| `location`    | Render whichever menu is currently mapped to this slot                                   |
+| `variant`     | Optional render variant override                                                         |
+| `class`       | Extra CSS class on the wrapper, after the menu's own `class` (if any)                    |
+| `depth`       | Cap render depth (integer ≥ 1); items deeper than this are dropped from the output       |
+| `orientation` | `horizontal` or `vertical` for this placement only, overriding the menu's own setting     |
+| `float`       | `no` renders this placement inline even when the menu is floating in its slot             |
+
+Items with `visibility` set are filtered per requesting user, and items with `hidden: true` are always dropped - both happen server-side per request.
+
+`location` honours **menu bindings**: if another menu is bound to that slot for the page being rendered, the shortcode renders the bound menu, exactly as the navbar does. `slug` names a menu directly and is never redirected.
+
+Orientation adds a `dm-menu--horizontal` / `dm-menu--vertical` class to the wrapper. A menu that sets no orientation gets neither class and renders as a plain nested list, as it always has.
+
+A menu's `highlight` block (hover and current-page item effects - see `docs/configuration.md`) travels with it here: the wrapper carries `data-menu-hover` / `data-menu-active` and the item pointing at the page being rendered is marked `is-active` + `aria-current="page"`. There is no shortcode attribute for it - the effect belongs to the menu, so every placement of it matches.
+
+**Output:**
+
+```html
+<nav class="dm-menu dm-menu--legal" data-menu="legal" data-menu-hover="underline">
+  <ul>
+    <li><a href="/privacy" class="is-active" aria-current="page">Privacy</a></li>
+    <li>
+      <a href="/legal">Legal</a>
+      <ul>
+        <li><a href="/legal/terms">Terms</a></li>
+      </ul>
+    </li>
+  </ul>
+</nav>
+```
+
+---
+
+### `[view]`
+
+Self-closing. Renders a saved View with full filtering, pagination, and display options. Works on every
+storage adapter: MongoDB-backed collections run native aggregations; file-backed collections run the
+built-in pipeline evaluator, which supports all ten allow-listed stages (`$match`, `$lookup`, `$sort`,
+`$project`, `$unwind`, `$limit`, `$skip`, `$count`, `$addFields`, `$group`) with two pragmatic limits:
+`$addFields`/computed `$project` values accept literals and `$field` references (not operator
+expressions), and `$lookup` supports the equality form only. Unsupported constructs fail with a clear
+error in the view preview rather than returning wrong results.
+
+```
+[view slug="products" display="table" limit="50" /]
+[view slug="team" display="cards" columns="3" title-field="name" /]
+```
+
+| Attribute     | Description                                       |
+|---------------|---------------------------------------------------|
+| `slug`        | Required. The **view** slug (a saved View, not a collection) |
+| `display`     | `table`, `cards`, `list`, `accordion`, `timeline`, `carousel`, `listgroup` or `block`. Defaults to the display mode stored on the View, then `table` |
+| `limit`       | Maximum number of entries to display (default 25) |
+| `fields`      | Comma-separated field keys to show                |
+| `title-field` | Field used as the card/list title                 |
+| `columns`     | Grid columns for `cards` display (2-4, default 3) |
+| `empty`       | Text shown when there are no entries              |
+| `block`       | Block template for `display="block"` (falls back to the View's stored block), `carousel` or `listgroup` |
+| `action`      | Adds a CTA button per row that runs this CMS Action; styled with `cta-label`, `cta-style`, `cta-icon`, `cta-confirm` |
+| `class` / `item-class` | Your own CSS classes on the wrapper / on every entry, as on `[collection]` |
+
+The display-specific attributes are the same as on `[collection]` (for example `body-field`, `date-field`,
+`layout`, `theme` and `mode` for timelines, `image-field` for carousels, `variant`/`size` for list groups).
+Adding `searchable`, `sortable`, `filterable` or `paginate` switches to the interactive browser shell (search, sort
+and pagination over the View's results, with no filter rail).
+
+---
+
+### `[button]`
+
+Renders a styled Domma button as a link (`<a class="btn">`). Supports both wrapping and self-closing forms.
+
+```
+[button href="/contact" variant="primary"]Get in touch[/button]
+[button href="/download" variant="success" icon="download" size="sm" label="Download" /]
+[button href="https://example.com" variant="outline" target="_blank"]Visit site[/button]
+```
+
+| Attribute    | Description                                                                                                                                                                  |
+|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `href`       | Link destination (required; defaults to `#`)                                                                                                                                 |
+| `label`      | Button text - used in self-closing form; body text is used in wrapping form                                                                                                  |
+| `variant`    | `primary` (default), `secondary`, `success`, `danger`, `warning`, `info`, `outline`, `ghost`, `link`, `outline-success`, `outline-danger`, `outline-warning`, `outline-info` |
+| `size`       | `"sm"` → `.btn-sm` \| `"lg"` → `.btn-lg`                                                                                                                                     |
+| `icon`       | Domma icon name rendered before the label                                                                                                                                    |
+| `icon-after` | Domma icon name rendered after the label                                                                                                                                     |
+| `target`     | Link target, e.g. `"_blank"`                                                                                                                                                 |
+| `class`      | Extra CSS classes appended to `.btn`                                                                                                                                         |
+| `id`         | HTML `id` attribute                                                                                                                                                          |
+
+`[button]` also accepts injected effects (`breathe`, `pulse`, `shake`, `animate`, `ripple`) - see
+[Effect injection](#effect-injection).
+
+---
+
+### `[link]`
+
+Renders a plain anchor with optional icon, target, and class. Prefer this over raw HTML when you need any of these
+extras; use standard Markdown `[text](url)` for simple inline links.
+
+```
+[link href="/about"]About us[/link]
+[link href="https://example.com" target="_blank" icon-after="external-link"]Visit site[/link]
+[link href="/about" icon="arrow-right" label="About us" /]
+```
+
+| Attribute    | Description                                                               |
+|--------------|---------------------------------------------------------------------------|
+| `href`       | Link destination (required; defaults to `#`)                              |
+| `label`      | Link text - used in self-closing form; body text is used in wrapping form |
+| `target`     | Link target, e.g. `"_blank"`                                              |
+| `class`      | CSS classes on the `<a>`                                                  |
+| `icon`       | Domma icon name rendered before the text                                  |
+| `icon-after` | Domma icon name rendered after the text                                   |
+| `id`         | HTML `id` attribute                                                       |
+
+---
+
+### `[cta]`
+
+Renders an action-trigger button linked to a CMS Action:
+
+```
+[cta action="send-welcome" entry="abc123" style="primary" icon="mail"]Send Welcome Email[/cta]
+[cta action="archive" entry="abc123" confirm="Archive this record?" /]
+```
+
+Attributes: `action` (required - action slug), `entry` (entry ID), `style` (btn variant), `icon`, `size`, `confirm` (confirmation prompt text), `label` (self-closing form only).
+
+---
+
+### `[demo]`
+
+Embeds a demo page from this site in an iframe. Self-closing.
+
+```markdown
+[demo src="elements/accordion" /]
+[demo src="effects/ambient" height="600px" title="Ambient Effect" /]
+[demo src="widget" base="/public/showcase" /]
+```
+
+| Attribute | Default | Notes |
+|-----------|---------|-------|
+| `src` | required | Path under `base`, without the `.html`. Nothing renders without it |
+| `height` | `500px` | Any CSS length |
+| `title` | none | Renders a caption bar above the frame |
+| `base` | `/public/demos` | Must be an absolute path on this site |
+
+The frame is **same-origin only**. A `src` carrying a scheme (`https:`), a
+protocol-relative prefix (`//`), or a `base` that is not an absolute path is
+refused and nothing is rendered - use `[embed]` for third-party content, which
+is gated by the host allow-list in `config/embeds.json`.
+
+Was the `demo-viewer` plugin until 0.67.0.
+
+## Effects Shortcodes
+
+The following shortcodes are provided by the built-in Effects system.
+
+| Shortcode                                    | Description                                            |
+|----------------------------------------------|--------------------------------------------------------|
+| `[reveal animation="fade"]...[/reveal]`      | Fade/slide/zoom on scroll                              |
+| `[breathe]...[/breathe]`                     | Continuous gentle scale loop                           |
+| `[pulse]...[/pulse]`                         | Repeating scale pulse                                  |
+| `[shake]...[/shake]`                         | One-shot shake                                         |
+| `[scribe speed="50"]...[/scribe]`            | Typewriter - simple mode (text typed letter by letter) |
+| `[scramble]...[/scramble]`                   | Character-scramble reveal                              |
+| `[counter to="100" /]`                       | Animated number counter (self-closing)                 |
+| `[ripple]...[/ripple]`                       | Click-triggered ripple                                 |
+| `[twinkle count="50"]...[/twinkle]`          | Particle/star overlay                                  |
+| `[ticker-tape palette="festive" /]`          | Falling ticker-tape strips - self-closing for full-page, wrapping form for container-scoped |
+| `[butterflies palette="meadow" /]`           | Flapping butterflies wander and rise - self-closing for full-page, wrapping form for container-scoped |
+| `[strobe preset="club" /]`                   | Sweeping light beams (club/concert/police/searchlight/scanner/mood) - self-closing for full-page, wrapping form for container-scoped |
+| `[animate type="fade-in-up"]...[/animate]`   | CSS-only animation (no plugin needed)                  |
+| `[ambient type="aurora"]...[/ambient]`       | CSS-only animated background                           |
+| `[firework type="burst" colour="rainbow" /]` | CSS firework (self-closing)                            |
+| `[fireworks]...[/fireworks]`                 | Fireworks display container                            |
+| `[celebrate theme="auto" /]`                 | Seasonal canvas celebration (self-closing). `auto` picks whichever seasonal theme is active by date |
+| `[christmas /]`, `[halloween /]`, `[st-patricks /]`, `[valentines /]`, `[guy-fawkes /]`, `[st-andrews /]`, `[st-davids /]`, `[st-georges /]`, `[new-year /]`, `[easter /]`, `[summer-garden /]`, `[chinese-new-year /]`, `[winter /]`, `[autumn /]`, `[graduation /]`, `[birthday /]`, `[anniversary /]`, `[greeting /]`, `[make-it-rain /]`, `[money-rain /]` | Named celebration tags - shorthand for `[celebrate theme="…" /]` that force that theme. Other `[celebrate]` attributes (e.g. `intensity`) still apply |
+| `[christmas snow-only="true" /]`           | Just the falling snow - every decoration off. Or switch pieces off one at a time: `trees`, `wreaths`, `northstars`, `snowmen`, `sleigh`, `elf`, `train`, `firework`, `robin` = `"off"` (names are not case-sensitive; `north-stars` works too) |
+
+### Winter and Make it rain
+
+```text
+[winter intensity="light" /]
+[winter pine="off" icicle="off" /]
+[make-it-rain intensity="heavy" duration="8000" /]
+```
+
+Winter offers snowflakes, frosted pines, snowdrifts, icicles and twinkling winter stars. Its switches are `snowflake`, `pine`, `snowdrift`, `icicle` and `star`. `falling-only="true"` leaves just snow. In automatic mode it fills December-February, with the existing holidays taking priority. Manual selection works at any time of year.
+
+Make it rain is a standalone weather effect with raindrops and ground splashes, available at any time. It accepts `light`, `medium` or `heavy` intensity. `duration` is milliseconds, defaults to 8000 and is capped at 600000; `0` keeps it running until the page closes or the effect is destroyed. It never activates automatically by date. Both effects respect reduced motion and keep the underlying page clickable.
+
+Summer Garden and Easter use the existing illustrated butterflies, meadow colours, wandering upward flight and natural wingbeats. Their `butterfly="off"` switch still works independently of bees and other decorations.
+
+### Sparkler greetings and Chinese New Year
+
+New Year writes Happy New Year in the sky; Christmas writes Merry Christmas; Chinese New Year writes 新年快乐 (Happy New Year). The greeting is traced stroke by stroke behind a glowing tip, sheds sparks, holds, fades and repeats. English greetings wrap onto two balanced lines on smaller screens. Switch it off independently:
+
+```text
+[new-year sparkler-message="off" /]
+[christmas sparkler-message="off" /]
+[chinese-new-year dragon="off" lantern="off" /]
+```
+
+Optional lettering, colour and year settings appear in the editor's Celebrate controls and on each named celebration. Both styles work in both colours:
+
+```text
+[christmas sparkler-style="cursive" sparkler-colour="silver" /]
+[new-year sparkler-style="cursive" sparkler-colour="gold" /]
+[new-year sparkler-greeting="best-wishes" sparkler-year="2027" sparkler-style="cursive" sparkler-colour="silver" /]
+```
+
+The final example writes **Best wishes for 2027!**.
+
+| Parameter | Default | Values |
+|---|---|---|
+| `message` | Theme greeting | Custom text, up to 120 characters; `{year}` inserts `sparkler-year` |
+| `sparkler-style` | `stroke` | `stroke`, `cursive` |
+| `sparkler-colour` | `gold` | `gold`, `silver`; includes the lettering, tip, sparks and shimmer. `sparkler-color` is also accepted |
+| `sparkler-greeting` | `default` | `default` (seasonal message), `best-wishes` |
+| `sparkler-year` | Current year | 1-9999, used by Best wishes and `{year}` in custom messages |
+
+Chinese New Year's seasonal message uses Chinese stroke lettering in either colour. The optional Best wishes greeting is in English. `sparkler-message="off"`, `falling-only="true"` and Christmas's `snow-only="true"` hide the entire greeting regardless of style or colour.
+
+Chinese New Year includes a wingless, flowing Chinese dragon, red lanterns, red and gold confetti, fireworks and the sparkler greeting. Its switches are `confetti`, `dragon`, `lantern`, `firework` and `sparkler-message`. Its automatic window starts on Chinese New Year and lasts seven local calendar days, taking priority over overlapping celebrations. Dates for 2020-2050 use the Hong Kong Observatory's published calendar, with the runtime Chinese calendar as a fallback outside that range.
+
+Summer Garden's bees visit enabled flower heads and pause before flying to the next one. If flowers are off, the bees keep flying. Easter's bunny makes short hops along the lower edge, resting and turning before reaching the edge. The scene's pause and reduced-motion controls apply to these animations too.
+
+### New Year, Easter and Summer Garden
+
+Choose any of these in Insert → Effects → Celebrate, or the page editor's Celebrations submenu. Their own switches also appear when editing a named shortcode.
+
+```text
+[celebrate theme="new-year" intensity="medium" firework="off" /]
+[easter intensity="light" bunny="off" /]
+[summer-garden bee="off" ladybird="off" /]
+[summer-garden falling-only="true" /]
+```
+
+| Theme | Individual switches (`"off"` hides an element) | Automatic dates |
+|---|---|---|
+| `new-year` | `confetti`, `streamer`, `firework`, `balloon`, `midnight-clock` | 31 December through 2 January |
+| `easter` | `blossom`, `flower`, `butterfly`, `easter-egg`, `bunny` | Tuesday before Gregorian Easter through Easter Monday, calculated each year |
+| `summer-garden` | `blossom`, `flower`, `butterfly`, `bee`, `ladybird` | 1 June through 31 August (UK summer) |
+
+Dates include both endpoints in the visitor's local calendar. New Year takes over from Christmas on 31 December. Easter takes priority over any overlapping patron saint celebration. Explicit theme selection works at any time of year, including for gardens in other climates. All three support `light`, `medium` and `heavy` intensity and respect the site's reduced-motion setting.
+
+### `[scribe]` parameters
+
+![Scribe composer with global settings and an action timeline](images/scribe-composer.png)
+
+Both simple text and action scripts accept the same settings. The editors emit an explicit reduced-motion setting so the checkbox remains effective even when the site default differs. Insert → Effects exposes the simple form; Insert → Scribe exposes these settings plus the action timeline.
+
+| Parameter | Default | Values / behavior |
+|---|---|---|
+| `mode` | `typewriter` | `typewriter`, `word`, `sentence`; typing and deletion operate on that unit |
+| `effect` | `none` | `none`, `fade`, `bounce`, `glow`; default for simple text and render/redraw actions |
+| `speed` | `50` | Non-negative milliseconds per typed unit; `0` renders immediately |
+| `delete-speed` | `30` | Non-negative milliseconds per deleted unit |
+| `cursor` | `true` | Show the cursor |
+| `cursor-char` | `\|` | Custom cursor text; ignored for the underline cursor |
+| `cursor-type` | `caret` | `caret`, `block`, `underline` |
+| `cursor-blink` | `true` | Blink while idle; cursor remains steady during typing/deletion |
+| `loop` | `false` | `false` once, `true` forever, or a positive integer for total plays (e.g. `3`) |
+| `loop-delay` | `1000` | Non-negative milliseconds between plays; the last phrase stays visible |
+| `pause-on-hover` | `false` | Pause and continue on hover |
+| `auto-start` | `true` | `false` waits for Play; playback controls appear automatically |
+| `respect-motion-preference` | Site Effects setting | `true` shows the first phrase without motion when reduced motion is preferred; `false` permits typing |
+| `controls` | `false` | Show Play, Pause, and Replay buttons |
+
+```text
+[scribe mode="word" effect="bounce" speed="140" cursor-type="underline" cursor-blink="false" loop="3" loop-delay="1800" pause-on-hover="true" controls="true"]
+Build smoother experiences, one word at a time.
+[/scribe]
+```
+
+Render and redraw actions inherit `effect` unless they specify their own value; `effect="none"` explicitly disables the default entrance effect for that action. Callback integrations use bubbling DOM events on the Scribe element: `scribe:start`, `scribe:complete`, `scribe:character`, `scribe:render`, `scribe:undo`, and `scribe:loop`. `event.detail.value` carries the unit/text/loop count and `event.detail.index` carries the character's unit index. JavaScript callbacks remain available through the Domma JS API.
+
+### `[scribe]` script mode
+
+`[scribe]` supports a sequenced script mode using `[render]`, `[wait]`, and `[undo]` sub-tags:
+
+```
+[scribe loop="true" loop-delay="2000" delete-speed="20"]
+[render]We build things that matter.[/render]
+[wait]1200[/wait]
+[undo all="true" /]
+[render]We design for humans.[/render]
+[wait]1200[/wait]
+[undo all="true" /]
+[/scribe]
+```
+
+Use `[render]...[/render]` to type text, `[wait]Ms[/wait]` to pause, and `[undo /]` to delete (`[undo all="true" /]`
+clears everything typed so far, `[undo count="3" /]` removes the last three units (characters, words, or sentences according to `mode`)). `[redraw]...[/redraw]` is
+shorthand for `[undo all="true" /]` followed by `[render]...[/render]`. `[render]` and `[redraw]` accept an
+`effect="…"` attribute that is passed to the typewriter for that step. `loop="true"` replays the sequence. Only
+`[render]`, `[wait]`, `[undo]` and `[redraw]` are parsed inside a scripted `[scribe]` block - plain text between
+actions is ignored.
+
+```
+[scribe loop="true"]
+[render]We build things that matter.[/render]
+[wait]1200[/wait]
+[redraw]We design for humans.[/redraw]
+[/scribe]
+```
+
+### Effect injection
+
+Instead of wrapping a tag in an effect shortcode, you can add the effect as a flag on the host tag. Effect parameters
+use the effect name as a prefix: `reveal-animation="zoom"` becomes the reveal's `animation` setting.
+
+```
+[card title="Why us" reveal reveal-animation="zoom" reveal-duration="600"]
+Fast, file-based and friendly.
+[/card]
+
+[button href="/contact" pulse]Get in touch[/button]
+```
+
+| Host tag | Effects that can be injected |
+|---|---|
+| `[card]`, `[box]` | `reveal`, `breathe`, `pulse`, `shake`, `twinkle`, `ambient`, `animate`, `ripple` |
+| `[hero]` | `reveal`, `breathe`, `pulse`, `twinkle`, `ticker-tape`, `butterflies`, `strobe`, `ambient`, `animate` |
+| `[banner]` | `reveal`, `pulse`, `shake`, `ambient`, `animate` |
+| `[col]` | `reveal`, `breathe`, `animate`, `ripple` |
+| `[button]` | `breathe`, `pulse`, `shake`, `animate`, `ripple` |
+
+---
+
+## Processing Order
+
+Shortcodes are processed in this order (see `parseMarkdown()` in `server/services/markdown.js`), which determines
+nesting behaviour:
+
+1. `markdown:beforeParse` plugin transforms
+2. `[component]` / `<dm-*>` component tags
+3. `[collection]`
+4. `[view]`
+5. `[block]` and block short tags
+6. `[menu]`
+7. `[dconfig]`
+8. Effects shortcodes (including the named celebration tags)
+9. Plugin shortcodes (registered by enabled plugins)
+10. `[tabs]` / `[tab]`
+11. `[accordion]` / `[item]`
+12. `[carousel]` / `[slide]`
+13. `[countdown]`
+14. `[timeline]` / `[event]`
+15. `[listgroup]` / `[item]`
+16. `[spacer]`
+17. `[theme-switcher]`, `[navbar]`, `[contents]`
+18. `[center]`
+19. `[icon]`
+20. `[demo]`
+21. `[embed]`
+22. `[form]`
+23. `[hero]`
+24. `[table]`
+25. `[badge]`
+26. `[text]`
+27. `[button]`
+28. `[link]`
+29. `[cta]`
+30. `[grid]` / `[row]` / `[col]`
+31. `[card]` / `[box]`
+32. `[banner]`
+33. `[slideover]`
+34. Markdown → HTML (marked)
+35. HTML sanitisation
+36. `markdown:afterParse` plugin transforms
+
+Container tags render their own bodies as they go: effect wrappers, `[tabs]`, `[accordion]`, `[carousel]`,
+`[timeline]`, `[hero]`, `[grid]`/`[col]`, most `[card]` layouts and `[slideover]` run the inline tags (`[badge]`,
+`[text]`, `[button]`, `[link]`, `[cta]`) and `[grid]`/`[card]` over their body before Markdown, so those work inside
+all of them. `[center]` leaves its body as Markdown for the later stages, so anything processed after it works
+inside it. Tags processed before a container (components, collections, views, blocks, menus) are already HTML by
+the time the container sees them, so they can be nested anywhere. `[banner]` runs after `[card]` and `[grid]`, so
+it cannot be nested inside a container that has already rendered its body. Do not nest `[slideover]` inside another `[slideover]`, or a `[box]`
+inside another `[box]`.
+
+### Optional Christmas elf scenes
+
+`[christmas peeing-elf="true" thieving-elf="true" /]` enables two optional scenes. Both are off when omitted. The clothed peeing elf walks in, pauses and leaves; the thief needs a visible Christmas tree with an available gift, takes that exact present, then escapes carrying it. Each scene is limited to one active elf. `snow-only="true"` disables both, even alongside an explicit opt-in.
+
+The same attributes work on `[celebrate theme="christmas" /]`. Regular walking elves remain a separate decoration controlled by `elf="off"`.
+
+### Standalone celebration characters
+
+Render a single character inline, at any time of year:
+
+```markdown
+[celebrate character="mooning-leprechaun"]
+[celebrate character="mooning-elf" size="large" /]
+[celebrate character="elf" size="200" animate="false" /]
+[celebrate character="leprechaun" size="small" facing="left" /]
+```
+
+Sizes describe displayed height: `small` = 96px, `medium` = 160px (default),
+`large` = 240px, `xlarge` = 360px, or a pixel height between 16 and 1024.
+Characters retain their proportions and fit smaller containers. `animate="false"`
+shows a still pose; reduced-motion preferences also stop animation.
+
+Available characters: `elf`, `peeing-elf`, `thieving-elf`, `mooning-elf`,
+`leprechaun`, `mooning-leprechaun`, `bagpiper`, `knight`, `dragon`,
+`welsh-dragon`, `cupid`, `robin`, `snowman`.
+
+A character runs independently of the theme, date and seasonal particles.
+For the full seasonal overlay, `[christmas mooning-elf="true" /]` or
+`[st-patricks mooning-leprechaun="true" /]` opts into a walk-in, wiggle and
+walk-out scene. Both mooners are off by default.
+
+
+### Custom celebration messages and occasions
+
+```text
+[celebrate message="Best wishes for {year}!" sparkler-year="2027" sparkler-style="cursive" sparkler-colour="silver" /]
+[graduation message="Congratulations, Chloé!" sparkler-style="cursive" /]
+[birthday message="Happy Birthday, Sarah!" /]
+[anniversary message="Happy Anniversary, Mum & Dad!" /]
+[autumn /]
+[money-rain duration="8000" /]
+```
+
+`message` replaces the scene greeting, up to 120 characters. It supports names, punctuation and Latin accents with either lettering style and gold or silver. `{year}` uses `sparkler-year`. Without a theme, a message uses the standalone `greeting` scene. It is also available on Christmas, New Year, Chinese New Year, Graduation, Birthday and Anniversary. The Effects editor handles escaping quotes and square brackets; in hand-written shortcodes use `&quot;`, `&#91;` and `&#93;` for these characters.
+
+Graduation tosses caps and diplomas; Birthday includes cake, balloons and confetti; Anniversary includes rings and hearts. Autumn has falling leaves, acorns and mushrooms, and runs automatically September-November after specific holidays. Money Rain is the separately named banknote effect; Make it rain is actual rain.