For developers

Build commands, file map, design tokens, 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 (a current LTS release)
npm or Yarn
Ghost v5.0.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/.

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 run zip`	Build, then package `miyus.zip` (assets, partials, locales, templates, `package.json`, license, readme) for upload.
`npm run test`	Runs a production build, then GScan — Ghost's official theme compatibility checker.

File map

Templates (root)

File	Purpose
`default.hbs`	Master layout — head, Google Fonts preloads, header/footer partials, dark-mode bootstrapping.
`index.hbs`	Homepage: hero, featured links, Editor's Picks, tag sections, latest posts.
`post.hbs`	Article page: feature image, content, member CTA, related posts.
`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 color / author cover as a hero backdrop.
`error.hbs`	Error pages.

Key partials

Partial	Purpose
`partials/header.hbs`	Logo (light + dark), primary nav with the `--` dropdown convention, search, theme toggle, Subscribe/Account button.
`partials/footer.hbs`	Secondary nav, social links (9 networks), copyright.
`partials/hero.hbs`	Homepage hero — title/description fallbacks and the members signup form.
`partials/card.hbs`, `partials/featured-card.hbs`	Post cards.
`partials/featured-links.hbs`	The featured pages/tags row under the hero.
`partials/featured.hbs`	Editor's Picks (3 most recent featured posts).
`partials/tag-sections.hbs`	Tag-based homepage sections.
`partials/content-cta.hbs`	Gated-content upgrade box for members content.
`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, colors.
`assets/css/color-scheme.css`	Dark-mode palette (fixed dark values, including the dark secondary background).
`assets/css/components/`, `assets/css/ghost/`	Component and per-surface styles.
`assets/js/index.js`	JS entry (Rollup input).
`assets/js/color-scheme.js`	Dark-mode toggle + `prefers-color-scheme` detection and persistence.
`assets/js/lightense.js`	Click-to-zoom lightbox for content images.
`assets/js/menuOpen.js`	Mobile menu.
`rollup.config.js`	Build configuration.

Locales workflow

Translations live in locales/ as flat JSON files (en.json, de.json), consumed by Ghost's {{t}} helper. Unlike some of our other themes, Miyus has no automated parity check — keep the files in sync by hand:

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).
Add the translated value for the same key to every other locale file (de.json, and any you've added).
A key missing from a locale silently falls back to the English text — easy to miss, so diff the key sets of en.json and the other files before zipping.

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.