Skip to content

Blocks and theming

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.

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.

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 with intro above and outro below.
  • rich(html, cls) outputs rich text, or nothing if it’s empty.
  • ctaButtons(), colsClass() and iconSvg() 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.

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.

  • 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, surface and so on, listed in SKIP_KEYS in src/routes/search.js) are skipped; add to that list if your block has other non-prose keys.

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.

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.

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:

  1. fontFacesToCss(): @font-face rules from site_config.fonts, keeping only faces that pass isValidFontFace.
  2. tokensToCss(): the tokens on :root (after cleanTokens), with the color-dark values applied under [data-theme="dark"], and under prefers-color-scheme: dark when the visitor hasn’t chosen a theme.
  3. 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.