Maintenance

For developers

Build commands, file map, design tokens, tests and the locales workflow for developers customizing Miyus from source.

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

Custom code is overwritten on theme update

If you modify theme files directly and then upload an updated miyus.zip through Ghost Admin, your changes are erased. Fork the repo, commit your changes to your fork, and rebuild your own zip. Don't edit files in place on a production install. For small CSS tweaks, prefer Ghost's Settings → Code injection, which survives theme updates. See Code injections for the CSS variables Miyus exposes for exactly this.


Build requirements

  • Node.js 22 or later
  • npm or Yarn
  • Ghost v6.23.0 or later for the running site that will host the built theme

Build commands

All commands run from the theme root. The build is Rollup-based: JavaScript is bundled from assets/js/index.js (Babel + Terser) and CSS is compiled through PostCSS (postcss-import + postcss-preset-env), both into assets/built/. The default fonts are copied into assets/fonts/ before every build.

CommandWhat it does
npm installInstall dependencies.
npm run devRollup in watch mode with livereload. Rebuilds on every CSS/JS/Handlebars change. Pair it with a local Ghost install pointed at the theme directory.
npm run buildProduction build to assets/built/ (minified, with sourcemaps).
npm testBuilds, then runs GScan (Ghost's theme checker), the locale parity check and the test suite.
npm run zipTests, then packages miyus.zip (assets, partials, locales, templates, package.json, licence, readme) for upload.

The archive you receive from the customer portal is built the same way; the source folders scripts/ and tests/ are not part of it.


File map

Templates (root)

FilePurpose
default.hbsMaster layout: shared head (partials/head-assets.hbs), skip link, header/footer partials.
index.hbsHomepage: hero, featured links, Editors' Picks, tag sections, latest posts. On page 2 and later the feed title is the page heading.
post.hbsArticle page: feature image, content, comments, related posts (latest posts for an untagged post).
page.hbsStandard page template.
custom-contact.hbsThe selectable Contact template (Formspree form + custom-form mode).
custom-authors.hbsThe selectable Authors directory template.
tag.hbs, author.hbsTag / author archives. Both use the tag accent colour / author cover as a hero backdrop.
error.hbsError pages. Standalone, but shares the head with the layout.

Key partials

PartialPurpose
partials/head-assets.hbsViewport, the pre-paint colour-scheme boot, the computed colour tokens, self-hosted fonts and the built assets.
partials/header.hbsLogo (light + dark), primary navigation, search, theme toggle, Subscribe/Account button.
partials/navigation.hbsRenders every {{navigation}} call. Marks -/-- sub-items and strips the marker server-side (partials/nav-label.hbs, partials/nav-label/).
partials/nav-link-body.hbsA menu link's inside: optional Ghost navigation icon, then the label.
partials/footer.hbsSecondary nav, social links (9 networks), copyright.
partials/hero.hbs, partials/hero-cover.hbsHomepage hero with the responsive cover image and the members signup form.
partials/card.hbs, partials/featured-card.hbsPost cards (eager=true for the first visible row).
partials/feature-image.hbsResponsive feature image for posts and pages.
partials/featured-links.hbsThe featured pages/tags row under the hero.
partials/featured.hbsEditors' Picks (3 most recent featured posts).
partials/tag-sections.hbsTag-based homepage sections (only for tags with posts).
partials/related-posts.hbsThe "Ready for More?" band.
partials/content-cta.hbsGated-content paywall box for members content.
partials/accent-style.hbsPer-page tag accent colour override, injected into the head.
partials/author-card.hbsAuthor directory card (image, bio, location, socials).

Assets

PathPurpose
assets/css/index.cssPostCSS entry, imports everything below.
assets/css/vars.cssDesign tokens: --body-font, --title-font, --global-border-radius, sizes, colours, code and table tokens.
assets/css/color-scheme.cssDark-mode palette, including the dark surfaces for Ghost's editor cards.
assets/css/components/, assets/css/ghost/Component and per-surface styles (ghost/header.css holds the dropdown and drawer rules).
assets/js/index.jsJS entry (Rollup input).
assets/js/header-nav.js, nav-label.jsDropdown disclosures built from the flat menu.
assets/js/mobile-menu.jsPhone drawer: body class, inert, Escape.
assets/js/sticky-header.jsThe "Fixed header" setting.
assets/js/color-scheme.js, comments-scheme.jsDark-mode toggle, persistence, and the comments thread.
assets/js/contact-form.jsContact form submission and status.
assets/js/lightense.jsClick-to-zoom lightbox for gallery images.
assets/fonts/Fraunces and Outfit (latin, latin-ext), declared in partials/fonts.hbs.
rollup.config.jsBuild configuration.

Tests

tests/ holds a Vitest suite: template-contract tests render the real partials with Ghost-shaped helper stubs (scripts/), and DOM tests exercise the navigation, drawer, toggle and contact modules in happy-dom. npm test runs them with GScan and the locale check.


Locales workflow

Translations live in locales/ as flat JSON files (en.json, de.json), consumed by Ghost's {{t}} helper. npm run lint:i18n (part of npm test) fails when a template uses a phrase a locale file lacks, or a locale file carries a phrase no template uses, for every locale file.

  1. When you add a {{t "..."}} call to a template, add the same English phrase as a key to locales/en.json (the key doubles as the fallback text).
  2. Add the translated value for the same key to every other locale file (de.json, and any you've added).
  3. Run npm run lint:i18n; it lists any key missing from or unused in each file.

To add a new language, copy en.json to locales/<code>.json and translate the values, then set the matching code as the site's Publication Language. See Translation.