Practical guide · about nine minutes

Customize a Publii theme without losing the update path.

A theme override keeps changed files separate from the installed theme. That protects your copy from being overwritten, but it does not automatically merge future upstream changes into files you replaced. The reliable workflow is: override only what you need, record the baseline, review upstream diffs, test, then publish.

Choose the right layer Use the update workflow

This is an independent implementation guide, not official Publii support. Back up the site first and test a generated preview before changing production.

Theme setting

Use an existing colour, typography, layout, or feature control when the theme already exposes the result you need.

Tools → Custom CSS

Use a small, theme-agnostic visual adjustment. Remember that this CSS remains if you later switch themes and may no longer fit.

theme-name-override

Use theme-specific CSS, Handlebars, JavaScript, configuration, or assets while keeping the installed theme as the baseline.

Separate theme variant

Use a new theme identity when the design, content model, or template surface changes enough that you intend to maintain it independently.

Minimal override, explicit merge

The update-safe workflow

Back up and record the exact baseline

Before changing anything, record the site, installed theme name, theme version, Publii version, source or marketplace URL, date, and the files you plan to replace. Keep a copy of the pristine theme version so a future comparison has a real starting point.

Theme: simple
Baseline version: 2.3.1.0
Publii version: 0.47.9
Override files: assets/css/main.css, index.hbs

Mirror only the files you must replace

Inside the site's input/themes directory, create theme-name-override. Copy each changed file into the same relative path. If the original is simple/assets/css/main.css, the override belongs at simple-override/assets/css/main.css.

input/themes/simple/assets/css/main.css
input/themes/simple-override/assets/css/main.css

Do not copy the entire theme “just in case.” Publii falls back to the original for files absent from the override, so a smaller override reduces the future merge surface.

Change source files, not generated output

For theme-specific CSS, work in the appropriate source file such as assets/css/main.css. Do not treat a generated style.css file as the authoritative customization source. For templates, preserve valid Handlebars structure; Publii's documentation warns that an intentionally empty .hbs override still needs at least one whitespace character.

Add short comments around custom sections and commit the override plus its baseline note to private or public version control as appropriate. Do not commit site content, deployment credentials, private configuration, or customer data.

Review the upstream change before updating

When a new theme version appears, keep three copies available: the pristine old version, pristine new version, and your override. Compare old upstream against new upstream for every overridden file. Then decide which upstream fixes must be carried into your replacement.

git diff --no-index -- simple-2.3.1/assets/css/main.css simple-2.4.0/assets/css/main.css

An override prevents your file from being overwritten; it also means Publii continues using that replacement instead of the updated original. Compatibility therefore needs review whenever upstream changed the same file.

Preview the real content states, then publish

Generate a preview and check the pages the override can affect: homepage, posts, pages, tags, search, navigation, empty states, long titles, missing images, and common phone and desktop widths. Check keyboard navigation, visible focus, reduced motion, browser errors, and broken asset paths.

Keep the previous working override and a rollback note until production is confirmed. Updating the installed theme and publishing the site are separate decisions; do not make production the first compatibility test.

Before the update

Site and override backed up
Old and new pristine theme versions retained
Baseline version and overridden-file inventory current
Upstream diffs reviewed file by file
No secrets or site content copied into source control

Before publishing

Preview generated without errors
Changed and adjacent templates checked
Phone and desktop widths checked
Keyboard and focus behaviour checked
Prior override and rollback steps retained

Primary documentation and demand evidence

Sources

Official Publii theme-overrides guide — folder naming, mirrored paths, fallback behaviour, and override limitations. The page reports that it was last updated in 2019, so current compatibility must still be tested.
Official theme installation guide — explains that reinstalling can overwrite custom theme changes and recommends overrides.
Official theme structure reference — identifies the source files and directories that make up a theme.
Archived Publii forum question — the exact problem of modifying a marketplace theme without losing updateability; the archived forum now points new support discussions to GitHub.

Need one focused change separated cleanly?

The fixed scopes cover a £25 brand pass, £45 responsive homepage section, or £75 theme variant with up to two focused template changes and a tested installable ZIP. They are starting scopes, not automatic quotes; the exact files, acceptance checks, delivery format, and price are agreed before work starts, and payment is due after review.

Check scope and fit Describe the public change