Code injection

Want to nudge a colour, hide a section, or tighten some spacing without forking the theme? Meridian gives every major part of the page a stable handle you can target with a few lines of CSS. You paste that CSS once into Ghost's Code Injection and it sticks, even when you update the theme.

The naming convention

Meridian labels its building blocks with a small, predictable set of HTML attributes — a naming convention you can reason about. Once you know the four words below, you can usually guess the hook for something instead of looking it up:

• data-region marks a big structural area, like the site header, the article body, or the homepage hero. There's usually one of each per page.
• data-component marks a reusable unit that can appear many times, like a post card, a story link in a rail, or the pagination bar.
• data-variant tells apart flavours of the same component — for example a post card rendered as the big hero versus a compact dense list item.
• data-part marks a piece inside a component or region: the title, kicker, excerpt, meta (byline/date), image, or read-time. These names are the same everywhere, so the headline of any story preview is [data-part="title"], whether it's an <h1> or a <p>. A few parts live outside story previews: rank (the position number in numbered rails), logo (the brand logo image), and wordmark (the home link that wraps the logo, or the site title when there's no logo). One marks image-less video stories: video-badge (the small Video label).
• data-layout is a fifth, rarer word: it marks an arrangement that cuts across components. Today it has one value, text, stamped on any post card, story card or section row rendered as a text card, so one selector finds every text card on the page. Pictured cards carry no data-layout.

You compose these by nesting — region, then component (with its variant), then part — and you can scope the whole thing to one page type with a Ghost body class (shown in the next section).

To target any of them, use an attribute selector in CSS:

<style>
  /* A structural region */
  [data-region="post-body"] { font-size: 1.05rem; }

  /* Every post card on the site */
  [data-component="post-card"] { /* ... */ }

  /* Only the hero-style post card */
  [data-component="post-card"][data-variant="hero"] { /* ... */ }

  /* The headline inside any post card, whatever element it uses */
  [data-component="post-card"] [data-part="title"] { /* ... */ }
</style>

What not to target

Meridian uses other data-* attributes internally (they wire up JavaScript or belong to Ghost itself) and those are not part of this styling API. Only the five above (data-region, data-component, data-variant, data-part, data-layout) are a promise. Leave the rest alone, because they can change or disappear in any update:

• Theme machinery (drives Meridian's own scripts): data-breaking-ticker, data-ticker-*, data-header-nav, data-nav-*, data-primary-nav, data-drawer-nav-*, data-footer-nav-*, data-post-toolbar, data-reading-progress, data-toc-mount, data-favicon-fallback, and the like.
• Page state on <html>: data-color-scheme, data-palette, data-font-size. For dark-mode tweaks, use the .dark class instead (shown later).
• Ghost & libraries (owned by Ghost, not the theme): data-portal, data-members-*, data-ghost-search, data-pswp-*.

A quick test: if the name reads like the four-word grammar — an area, a unit, a flavour, or a piece — it's fair game. If it reads like a wiring label (-toolbar, -mount, -track, portal), don't style against it.

Scope a change to one kind of page

Ghost adds a class to the <body> of every page that tells you what kind of page it is: home-template, post-template, page-template, tag-template and author-template (plus paged on pages 2, 3, and so on). The 404 page gets no template class, so scope a change there with its own hooks, [data-region="error-hero"] and [data-region="error-browse"]. Combine a body class with a hook to scope a change to just one place:

<style>
  /* The hero headline, but only on the homepage */
  .home-template [data-component="post-card"][data-variant="hero"] h1 { /* ... */ }

  /* Pagination, but only on tag archives */
  .tag-template [data-component="pagination"] { /* ... */ }
</style>

Reach the elements inside a region

The hooks mark the containers. To style something inside one, add a selector after the hook. For the parts of a story preview, prefer the data-part hook over a bare element selector — the heading level varies between layouts, but the part name doesn't:

<style>
  [data-component="post-card"] [data-part="title"] { letter-spacing: -0.01em; }  /* card headlines */
  [data-component="post-card"] [data-part="image"] { border-radius: 4px; }       /* card images   */
  [data-component="post-card"] [data-part="meta"] time { font-style: italic; }   /* the date line */
</style>

Inside the article body, Meridian renders the content Ghost's editor produces, which already has its own stable classes. Target those directly under [data-region="post-body"]:

<style>
  [data-region="post-body"] .kg-image-card { /* images   */ }
  [data-region="post-body"] .kg-button-card { /* buttons  */ }
  [data-region="post-body"] blockquote { /* pull-quotes */ }
</style>

Targeting parts of a story

Every story preview — the linked headline blocks in feeds, rails, grids, carousels, and "more to read" lists — is built from the same handful of parts, each with a data-part hook:

Because the names never change, you can restyle a part everywhere it appears with a single rule — no matter which heading level or element the layout happens to use:

<style>
  /* Every story headline on the site */
  [data-part="title"] { font-variation-settings: "wght" 620; }
</style>

…or scope it to one region. To recolour just the headlines in the homepage "More to read" rail, combine the region with the part:

<style>
  [data-region="most-read-rail"] [data-part="title"] {
    color: var(--color-accent-readable);
  }
</style>

(--color-accent-readable is your accent, with its lightness kept within a per-mode limit so it always reads as text; --color-accent is the exact colour, for fills. See Brand & colours below.)

Not every preview has every part — a text-only rail row has no image or excerpt — but when a part is present, it always carries the same hook.

A few parts live outside story previews, for the same convenience: [data-part="rank"] is the position number in numbered rails (the "More to read" list, some section rows), while [data-part="logo"] (the brand logo image) and [data-part="wordmark"] (the home link around the logo, or the site title when there's no logo) appear in the masthead, the Compact header, and the hamburger menu. The menu is its own region ([data-region="menu"]), so you can size each place's logo on its own (see the logo snippets below).

Hook reference

Every targetable part of Meridian, grouped by where it lives. Pair any of these with a body class above to scope it to one page type.

Site-wide chrome

Homepage

Posts & pages

Recommendation rails (below a post)

Post cards

A post card is the linked story preview that appears in feeds, rails, and grids. Target all of them with [data-component="post-card"], or one style with a data-variant:

Text cards

A story with no feature image renders as a text card. Text cards keep every hook above and add data-layout="text" on the card's root, so one selector reaches all of them; pictured cards carry no data-layout.

In a row of pictured cards a text card stretches to the row and its summary fills the space (the theme measures how many whole lines fit). That machinery uses its own names (data-text-fill, text-fill-excerpt, --text-fill-lines, --text-fill-min), which are not styling hooks: style the summary through [data-layout="text"] [data-part="excerpt"] instead.

The rule at the top (or start) of a text card is a border. Some card styles draw it on the card's root and others on the card's link (Dense + thumb, Thumb row, Grid, Editor's Picks and the asymmetric section row), and some cards also have a hairline along the bottom. Recolour only the top and start edges on both, so the hairlines keep their colour:

<style>
  /* Accent-coloured rule on every text card */
  [data-layout="text"],
  [data-layout="text"] > a {
    border-top-color: var(--color-accent);
    border-inline-start-color: var(--color-accent);
  }
</style>

Other story previews & their parts

Not every story preview is a post card. Compact list rows and a few hand-built cards carry their own component hook, and every preview exposes the same parts:

Archives, members & CTAs

Membership page

The Membership page — the page at the URL join — ships two layouts, and both expose these hooks.

Common snippets

Paste any of these into Settings → Code injection → Site Header and click Save. They're grouped by what they change; click a snippet to expand it. Mix and match — keep the ones you want and delete the rest.

Brand & colours

Typography

To switch the heading or body typeface, use the font settings in Design & branding or Meridian's Font heading and Font body settings in Site-wide settings rather than CSS.

Header, logo & navigation

Hiding things

Layout & spacing

Dark mode

Mobile

Need something else? See the full handle reference above, or the Sections and Membership CTA guides for component context.

Targeting with JavaScript

The same handles work from JavaScript, which you can add in Settings → Code injection → Site Footer:

<script>
  document.querySelectorAll('[data-component="post-card"]').forEach((card) => {
    // do something with each card
  });
</script>

Running a script on every page

While a reader watches a video, Meridian's persistent player loads the next pages without a full reload, so a script that only runs at page load would miss them. Listen for meridian:load instead of DOMContentLoaded. It fires for every page a reader is shown, once the theme has set the page up:

• the first load;
• each soft navigation while the player is engaged;
• a page the browser restores from its back/forward cache when the reader presses Back or Forward.

meridian:unload fires when that page goes away (a soft navigation replaces it, the reader leaves, or the browser puts it into the back/forward cache), so each meridian:load is followed by one meridian:unload. Set things up in one and tear them down in the other:

<script>
  let observer;

  document.addEventListener('meridian:load', (event) => {
    // event.detail.initial: true on the first page load
    // event.detail.restored: true when the browser restored the page from its back/forward cache
    // event.detail.path: the page's path
    observer = new IntersectionObserver((entries) => { /* … */ });
    document.querySelectorAll('[data-component="post-card"]').forEach((card) => observer.observe(card));
  });

  document.addEventListener('meridian:unload', () => {
    observer?.disconnect();
  });
</script>

A restored page still holds everything your script added to it last time, so if your handler changes the page itself (inserts an element, adds a class), check first whether the change is already there.

A listener added in Site Footer always sees the first meridian:load: the theme fires it after its own scripts have run. A third event, meridian:pageview, fires after each soft navigation, so analytics can count the pages the player loaded. All three are a supported part of Meridian, like the handles.

If you customised 1.10

Updating from 1.10 keeps every data-region, data-component, data-variant, data-part and data-layout value, every component class (.btn, .archive-chip, .chip-live and the rest) and every CSS variable name, so CSS written against them keeps working. Four kinds of customisation are worth a look.

Markup that changed shape

A rule written against a handle keeps matching. A rule that reaches past the handle to a bare element, a direct-child step (>) or an ARIA role may need its tail updated:

The footer column ids (footer-col-0, footer-col-1, …) count columns, so they shift by one when rows placed before your first heading become a Quick Links column. They were never a handle; select columns through [data-region="footer-nav"] instead.

Variables whose values changed

The names are all still there. These now hold different values, mostly to clear WCAG AA contrast:

A rule of yours that sets any of these still wins, as it did in 1.10.

Classes that left the stylesheet

Meridian's stylesheet holds only the utility classes its own templates use, so the set changes from release to release; the supported styling API is the handles, the component classes and the variables on this page. If an HTML card or a snippet of yours used one of these 1.10 classes, it no longer has an effect:

text-accent, !text-accent, hover:text-accent, group-hover:text-accent, text-accent-safe, bg-accent-safe, bg-accent-on-dark, border-accent-safe, border-accent-safe/50, border-accent-on-dark, accent-accent-safe, accent-accent-on-dark, decoration-accent/30, hover:bg-accent-ink, hover:border-accent, hover:border-accent-ink, focus:border-accent, focus:outline-accent, focus-visible:outline-accent, focus-visible:ring-accent, selection:bg-accent, selection:text-paper, btn-tertiary, border-l-[3px], md:border-l, md:pl-10, md:px-2, md:py-1, px-[9px], py-[5px], ring-1, ring-rule, dark:bg-paper-3, sm:cursor-default, sm:pointer-events-none.

For accent text, use style="color: var(--color-accent-readable)" or a rule of your own; for anything else, write the CSS in Site Header against a handle.

Scripts

A script that ran once at page load keeps working. To also cover the pages the video player loads, and pages restored when a reader presses Back, move it to meridian:load (see Running a script on every page).

Troubleshooting

See also: Social Links for adding more social icons, and For developers if you'd rather fork the theme and edit the source.