For developers

This page is the short reference for developers customizing Meridian from source. Most site editors won't need anything here — uploading the pre-built meridian.zip is enough. If you want to fork the theme, change design tokens, or rebuild after edits, read on.

Build requirements

• Node.js v22.12.0 or later
• Yarn (any recent v1.x)
• Ghost v6.23.0 or later for the running site that will host the built theme. Ghost 6.0 to 6.22 refuses the upload: the gscan those versions bundle (5.0.0 to 5.3.3) reports the unknown {{contrast_text_color}} helper (the fallback for text on the accent fill, first shipped in 6.23.0) as a fatal "Templates must contain valid Handlebars" error. {{split}} (menu labels) needs 6.5.0. The engines.ghost major is all the current gscan compares, so keep the floor in package.json, this page and the README in step by hand.

Build commands

All commands run from the theme root.

Tests

Meridian ships a test suite alongside the linters, run by yarn vitest:

• JavaScript units (assets/js/**/*.test.js): the navigation model (label prefixes, grouping, overflow maths), the header More engine, the sticky article bar, the reader-controls host, the soft-navigation router's scroll handling and the lifecycle events. DOM tests run in happy-dom.
• Template tests (scripts/**/*.test.js): the Handlebars partials rendered on a small set of Ghost-shaped helper stubs (scripts/ghost-helper-stubs.js, scripts/render.js) that mirror Ghost's own helpers, including the {{navigation}} helper and the older {{split}} that Ghost 6.23 to 6.53 ship. They cover the card resolver in every variant, the feature-row fallback, the desk chips, the membership band audience rules, the <title> and the breadcrumb.
• Compatibility guards (scripts/compat/): snapshots of the settings, hooks and CSS custom properties that shipped in 1.10.2, plus hashes of the inline <head> scripts. A release that drops a setting, a data-* value or a token (from the source or from the built stylesheet), or changes an inline script, fails here.
• Runtime contracts (scripts/runtime-contracts.test.js): readers' saved-state keys and bookmark shape, and every Alpine component a template names.
• Golden files (scripts/fixtures/golden/): the pictured card markup from before 1.11, so it can only change deliberately.
• Upgrade gate (scripts/upgrade/, run by yarn test:upgrade, kept out of yarn test): unpacks the last release tag on origin/stable (override with MERIDIAN_BASELINE=v1.x.y) and renders it next to the working tree. It fails when a menu link, a story, a component class, a documented recipe class or the override strength of a CSS variable that the previous release had goes missing, unless scripts/upgrade/allowed-changes.json records the change and why. A pull request into stable runs it in CI (.github/workflows/upgrade-check.yml).
• Package check: after yarn zip, node scripts/check-zip.mjs confirms the archive holds no scripts, tests, configs or demo templates and that its package.json is valid.

Design tokens

Meridian's design system lives as CSS variables in assets/css/index.css under the @theme block. The token families:

The accent derivation

The four derived accent tokens are computed in CSS with relative colour syntax, inside an @supports block that tests the exact expression shapes the derivation uses (oklch(from red min(l, 0.47) c h) and color(from red srgb-linear calc(clamp(0, (0.18 - r) * 1e6, 1)) g b)), so an engine that understands only the simplest relative colours keeps the fallbacks. The block sits in the theme cascade layer, so any unlayered Code injection rule that sets one of these variables wins over it. --color-accent-readable clamps the accent's OKLCH lightness to a per-palette maximum in light mode (min(l, max)) and a per-palette minimum in dark mode (max(l, min)), and only the lightness moves. The bounds guarantee AA for every accent, so an accent beyond a bound moves even if it already passed (the default #a4271c, at L 0.474, is clamped to Newsprint's 0.47). --color-accent-contrast picks black or white at the luminance crossover (Y = 0.179128), and --color-accent-hover mixes 18% toward the inverse of that text colour. Browsers without relative colour syntax keep the fallbacks: the raw accent, and Ghost's own {{contrast_text_color}} pick.

The per-palette lightness bounds are constants in index.css. They are solved, not guessed: scripts/check-contrast.mjs reimplements the derivations in JavaScript, sweeps 117 accents (the theme default, Ghost's defaults and presets, a hue wheel at four shades, the extremes and a few real sites) across all five palettes in both schemes, and fails if a text pair drops below WCAG 2.2 AA (4.5:1 for text, 3:1 for the focus ring) or if the constants in the CSS drift from the ones it solved. It also lints the templates: every accent fill must pair with text-accent-contrast. Run it with yarn lint:contrast; node scripts/check-contrast.mjs --emit-fixtures writes the reference outputs the docs' accent tester checks itself against.

Adding a new background preset means: add a new CSS rule against the data-palette attribute on <html>, override the relevant token family, add the palette's three lightness bounds, and run the checker until it is green. (Accent has no <html> attribute: it flows through Ghost's --ghost-accent-color variable.)

File map

The repo's root templates and key partials at a glance:

Templates (root)

Key partials

Assets

Lifecycle events

Three events on document are a supported API for Code injection scripts: meridian:load (after the theme has initialised a page: on first load, after every soft navigation while the persistent player is engaged, and when the browser restores a page from its back/forward cache), meridian:unload (before a page is torn down or put into that cache; it always pairs with the meridian:load before it) and meridian:pageview (for analytics). Usage and examples are in Code injection → Running a script on every page.

i18n workflow

The yarn lint:i18n parity check is enforced: never add a {{t "..."}} call to a template without also adding the matching key to locales/en.json and every other locale.

The mechanics

1. scripts/check-i18n.mjs walks every *.hbs file in the theme.
2. It extracts every {{t "..."}} and subexpression (t "...") call.
3. It diffs the extracted key set against locales/en.json, then checks every other locale against en.json: missing keys, extra keys, empty values, and % / {brace} placeholders that went missing in translation.
4. It fails the build on any drift.

The discipline

• Add a translation key first, then reference it in the template.
• Use Ghost's interpolation syntax ({{t "Members of {site}" [email protected]}}) instead of string concatenation, so word order is correct in non-English locales.
• Pluralization uses Ghost's {{plural}} helper around t calls, with one key per form (for example empty=(t "No stories") singular=(t "% story") plural=(t "% stories")).
• Never hardcode user-visible English in a template.

See also: Publication Language for the reader-facing side of the same system.

CSP & the inline scripts

With ads off (the default), Meridian ships one inline <script> block in <head>: the FOUC-prevention script that reads localStorage + prefers-color-scheme to apply the saved appearance class before the page paints. Turning on Enable ads with Ad consent mode adds a second inline block: the Consent Mode v2 deny-by-default baseline, emitted before {{ghost_head}}. With Enable persistent player on (the default), the end of <body> also carries an inline <script type="speculationrules"> block that sets up link prefetching. Every other theme script is loaded from assets/built/ (the AdSense loader, when a publisher ID is set, is an external src script, not inline).

If your site enforces a strict Content Security Policy that disallows script-src 'unsafe-inline', you'll need to whitelist each inline script's SHA-256 hash: one for the appearance script, one more for the consent baseline when ads and consent mode are on, and one for the speculation rules when the persistent player is on. This command prints them all:

curl -s https://your-site.example.com/ \
  | perl -0777 -ne 'while (/<script(?: type="speculationrules")?>([\s\S]*?)<\/script>/g) { open my $h, "|-", "openssl dgst -sha256 -binary | base64" or die; print $h $1; close $h }'

Each output line is a hash to add to your script-src directive (prefixed with 'sha256-'). The list also includes any inline <script> you added through Code injection, which a strict policy needs as well.

The scripts' behaviour is intentionally stable across releases, but a hash will change if the script bytes change, so re-run the command after every theme update on a strict-CSP site, and after changing the Color scheme setting, which is written into the appearance script. Meridian 1.11 changed none of these scripts, so hashes from 1.10 carry over.