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.
| Command | What it does |
|---|---|
npm install | Install dependencies. |
npm run dev | Rollup 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 build | Production build to assets/built/ (minified, with sourcemaps). |
npm test | Builds, then runs GScan (Ghost's theme checker), the locale parity check and the test suite. |
npm run zip | Tests, 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)
| File | Purpose |
|---|---|
default.hbs | Master layout: shared head (partials/head-assets.hbs), skip link, header/footer partials. |
index.hbs | Homepage: hero, featured links, Editors' Picks, tag sections, latest posts. On page 2 and later the feed title is the page heading. |
post.hbs | Article page: feature image, content, comments, related posts (latest posts for an untagged post). |
page.hbs | Standard page template. |
custom-contact.hbs | The selectable Contact template (Formspree form + custom-form mode). |
custom-authors.hbs | The selectable Authors directory template. |
tag.hbs, author.hbs | Tag / author archives. Both use the tag accent colour / author cover as a hero backdrop. |
error.hbs | Error pages. Standalone, but shares the head with the layout. |
Key partials
| Partial | Purpose |
|---|---|
partials/head-assets.hbs | Viewport, the pre-paint colour-scheme boot, the computed colour tokens, self-hosted fonts and the built assets. |
partials/header.hbs | Logo (light + dark), primary navigation, search, theme toggle, Subscribe/Account button. |
partials/navigation.hbs | Renders every {{navigation}} call. Marks -/-- sub-items and strips the marker server-side (partials/nav-label.hbs, partials/nav-label/). |
partials/nav-link-body.hbs | A menu link's inside: optional Ghost navigation icon, then the label. |
partials/footer.hbs | Secondary nav, social links (9 networks), copyright. |
partials/hero.hbs, partials/hero-cover.hbs | Homepage hero with the responsive cover image and the members signup form. |
partials/card.hbs, partials/featured-card.hbs | Post cards (eager=true for the first visible row). |
partials/feature-image.hbs | Responsive feature image for posts and pages. |
partials/featured-links.hbs | The featured pages/tags row under the hero. |
partials/featured.hbs | Editors' Picks (3 most recent featured posts). |
partials/tag-sections.hbs | Tag-based homepage sections (only for tags with posts). |
partials/related-posts.hbs | The "Ready for More?" band. |
partials/content-cta.hbs | Gated-content paywall box for members content. |
partials/accent-style.hbs | Per-page tag accent colour override, injected into the head. |
partials/author-card.hbs | Author directory card (image, bio, location, socials). |
Assets
| Path | Purpose |
|---|---|
assets/css/index.css | PostCSS entry, imports everything below. |
assets/css/vars.css | Design tokens: --body-font, --title-font, --global-border-radius, sizes, colours, code and table tokens. |
assets/css/color-scheme.css | Dark-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.js | JS entry (Rollup input). |
assets/js/header-nav.js, nav-label.js | Dropdown disclosures built from the flat menu. |
assets/js/mobile-menu.js | Phone drawer: body class, inert, Escape. |
assets/js/sticky-header.js | The "Fixed header" setting. |
assets/js/color-scheme.js, comments-scheme.js | Dark-mode toggle, persistence, and the comments thread. |
assets/js/contact-form.js | Contact form submission and status. |
assets/js/lightense.js | Click-to-zoom lightbox for gallery images. |
assets/fonts/ | Fraunces and Outfit (latin, latin-ext), declared in partials/fonts.hbs. |
rollup.config.js | Build 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.
- When you add a
{{t "..."}}call to a template, add the same English phrase as a key tolocales/en.json(the key doubles as the fallback text). - Add the translated value for the same key to every other locale file (
de.json, and any you've added). - 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.