Blocks and theming
How blocks work
Section titled “How blocks work”A page is a JSON array of blocks, each { "type": "hero", "props": { … } }. Two files define every block type, and they must agree:
src/blocks-manifest.js:BLOCK_MANIFEST, the editing schema. The page editor (public/js/page-editor.js) builds each block’s form from it.src/templates/blocks.js:RENDERERS, which turns a block’s props into HTML on the server, at request time.
Styles for blocks are in public/css/blocks.css.
Adding a block type
Section titled “Adding a block type”1. Describe its fields
Section titled “1. Describe its fields”Add an entry to BLOCK_MANIFEST. The key is the block’s type:
quoteGrid: { label: 'Quote grid', fields: [ { key: 'intro', label: 'Intro (optional)', type: 'richtext' }, { key: 'columns', label: 'Columns (1–3)', type: 'number', default: 2 }, { key: 'items', label: 'Quotes', type: 'list', itemFields: [ { key: 'quote', label: 'Quote', type: 'richtext' }, { key: 'name', label: 'Name', type: 'text' }, ] }, { key: 'outro', label: 'Closing text (optional)', type: 'richtext' }, ],},Field types are text, textarea, richtext (the WYSIWYG editor), number, boolean, select (options as strings or { value, label }), media (a URL with a Browse… button for the media library), date and list (repeatable, with its own itemFields). A new block starts with each field’s default, or empty, or a select’s first option.
A field can be shown only when another prop allows it, with showIf: { prop: 'columns', gte: 3 }, { prop: 'grouped', truthy: true }, { prop: 'grouped', falsy: true } or { prop: 'x', equals: 'y' }. Inside a list, showIf looks at the block’s props, not the item’s. The Comparison table and Tabbed content blocks use this.
By convention, structured blocks have an optional intro and outro rich-text field, and the editor gives every block a Background (the surface prop) without you declaring it.
2. Render it
Section titled “2. Render it”Add a function with the same key to RENDERERS. It gets (props, env), can be async (to query env.DB), and returns HTML:
quoteGrid(p) { const items = (Array.isArray(p.items) ? p.items : []).map((it) => ` <figure class="card"> ${rich(it.quote)} ${it.name ? `<figcaption>${escapeHtml(it.name)}</figcaption>` : ''} </figure>`).join(''); return structured('quote-grid', p, p.surface || 'default', `<div class="grid${colsClass(p.columns ?? 2, 3)}">${items}</div>`);},The helpers in blocks.js:
section(type, surface, inner, opts)wraps content in a full-width band,<section class="block block-<type> surface-<surface>">, with an optional background image and overlay.structured(type, props, surface, inner)does the same withintroabove andoutrobelow.rich(html, cls)outputs rich text, or nothing if it’s empty.ctaButtons(),colsClass()andiconSvg()for buttons, column classes and the named icons.
Follow the escaping rule: every plain-text or URL prop goes through escapeHtml or escapeAttr, and every link or iframe address also goes through safeUrl from src/templates/base.js first (escapeAttr(safeUrl(p.href))), so a javascript: or //other-host link becomes #. Rich-text props are written by trusted CMS users and are output as they are.
A block that throws while rendering is logged and left out; the rest of the page still renders. An unknown block type is skipped on the site, and shown with a warning in the editor.
3. Style it
Section titled “3. Style it”Add rules for .block-<type> to public/css/blocks.css. Use only the surface variables (--c-bg, --c-text, --c-heading, --c-link, --c-panel and the rest, listed below) or the theme’s --color-*, --radius-* and --font-* variables, never fixed colours, so the block follows the palette and dark mode.
What you get for free
Section titled “What you get for free”- The block appears in the editor’s Add a block picker, sorted by label.
- Markdown export labels its fields from the manifest (
src/export-md.js), with no changes. - Site search indexes its text. Keys that aren’t prose (
src,href,url,image,columns,surfaceand so on, listed inSKIP_KEYSinsrc/routes/search.js) are skipped; add to that list if your block has other non-prose keys.
Interactive blocks
Section titled “Interactive blocks”If a block needs JavaScript in the browser, do what Tabbed content and Gallery do: render every piece of content on the server, then have renderBlocks append a small script once per page when that block type is present. Make sure the content still reads sensibly without the script. The HTML and PDF exports strip scripts, and src/export-html.js only knows how to reveal the tab panels and gallery captions that those two blocks hide.
The named icons are defined twice, as ICON_NAMES in the manifest and ICONS in blocks.js. Keep them in step.
Surfaces
Section titled “Surfaces”A surface is a named colour scheme a block can sit on. Each surface maps a set of roles to colour token names, and becomes a CSS class:
.surface-soft { --c-bg: var(--color-brand-soft); --c-heading: var(--color-brand-dark); /* … */}The roles are defined in SURFACE_ROLES in src/tokens.js:
| Role | Variable |
|---|---|
| Background | --c-bg |
| Body text | --c-text |
| Headings | --c-heading |
| Subtle / muted text | --c-subtle |
| Feature / accent | --c-feature |
| Links | --c-link |
| Card background, card border | --c-panel, --c-panel-border |
| Hairline / divider | --c-hairline |
| Button background, button text | --c-btn-bg, --c-btn |
| Active tab background, text | --c-tab-bg, --c-tab |
Because roles point at tokens rather than fixed colours, and the tokens change in dark mode, every surface adapts to dark mode on its own.
The built-in surfaces (default, muted, soft, green, brand, dark) are SURFACE_KEYS, with labels in SURFACE_LABELS and role maps in defaultSurfaces, all in src/tokens.js. Changes made in the admin’s Palette designer are stored as JSON in site_config under surfaces, and override the defaults role by role.
The page editor’s Background menu comes from a separate list, SURFACES in src/blocks-manifest.js (and CARD_SURFACES for feature-grid cards). To add a built-in surface, add it to SURFACE_KEYS, SURFACE_LABELS and defaultSurfaces and to SURFACES. Custom surfaces created in the Palette designer aren’t in either list: customSurfaceOptions in src/routes/admin-pages.js reads them from site_config and appends them to the block-level Background menu (window.__SURFACES) and to every manifest field or item field keyed surface. An article’s Hero colour offers them too.
Design tokens and the theme CSS
Section titled “Design tokens and the theme CSS”defaultTokens in src/tokens.js is the one place the design defaults are defined:
| Group | Tokens | CSS variables |
|---|---|---|
color |
brand, brand-light, brand-dark, brand-soft, accent (and its variants), slate, slate-soft, bg, surface, surface-dark, ink, muted |
--color-* |
color-dark |
The same names, for dark mode | overrides --color-* |
font |
sans, display, mono |
--font-* |
radius |
sm, md, lg, pill |
--radius-* |
size |
container |
--size-container |
weight |
heading |
--weight-heading |
Edits in the admin’s Branding page are stored as rows in theme_tokens (grp, name, value), overlaid on these defaults by getThemeTokens in src/db.js. Every request for /theme.css (cached for 60 seconds) concatenates:
fontFacesToCss():@font-facerules fromsite_config.fonts, keeping only faces that passisValidFontFace.tokensToCss(): the tokens on:root(aftercleanTokens), with thecolor-darkvalues applied under[data-theme="dark"], and underprefers-color-scheme: darkwhen the visitor hasn’t chosen a theme.surfacesToCss(): a.surface-<key>class per surface. Surface keys and the token names they point at must be plain names ([a-z0-9-]), or they’re skipped or fall back to the default.
Token values are written into CSS unescaped, so they’re checked instead. isValidTokenValue(group, value) in src/tokens.js holds a strict pattern per group: hex, rgb()/hsl(), a colour name or var(--x) for color and color-dark; a comma-separated list of family names for font; lengths, calc()/clamp()/min()/max() and var() for radius and size; and 100–900, normal, bold, bolder or lighter for weight. None of them allow ; { } < > \ @ or url(. Branding refuses a save with any bad value, and tokensToCss drops bad values again when it generates CSS, so a value stored before the checks can’t break out. A font face needs a plain family name, a /media/….woff2|woff|ttf|otf file, a numeric weight (or a range for a variable font) and normal or italic.
The theme switch in the header (public/js/site.js) sets data-theme on <html> and remembers the choice in localStorage; a small inline script in src/templates/base.js applies it before the page paints.
To add a built-in token, add it to defaultTokens. It appears in Branding straight away, and a new colour can be used in the palette. Keep to the existing groups: isValidTokenValue rejects every value in a group it doesn’t know, so a new group needs a pattern there too.
