Updating The Theme

Skill level: Intermediate (uses git)

When a new version of Margo is released, CHANGELOG.md in the theme lists what changed. The version you have is in package.json ("version").

Keep Updates Easy

The way you customize decides how easy updates are:

Change content and config, not components. Updates mostly touch components and styles, so a site customized through src/content/, src/config/, src/i18n/, and a few color tokens in theme.css is the easiest to update.
Use page blocks and layouts instead of editing section components when you only need different content or a different look.
Commit often with clear messages, so you know which changes are yours.

Apply An Update With Git

Commit all your work, so your project is clean.
Create a branch for the update:
Terminal window
```
git checkout -b theme-update
```
Unzip the new version. Copy the files from its theme folder over your project, except src/content/, src/config/, src/i18n/, and src/assets/images/, which hold your content, settings, menus, and photos. Check CHANGELOG.md for new content fields, i18n keys, or config keys and add them by hand.

Copying also replaces files you may have customized: src/styles/theme.css (your colors), src/lib/brandMark.ts (if you changed the built-in logo mark), route files you edited in src/pages/[...lang]/, public/images/ (your favicons and social image), package.json and package-lock.json (re-add any dependency you installed yourself), and wrangler.toml, netlify.toml, vercel.json, or vercel.sh. Restore your versions of those in the next step, or skip them while copying.
Review the changes in the Source Control panel. Where a file has both your changes and the theme’s, keep both.
Run the checks:
Terminal window
```
npm ci
npm run astro-check
npm run build
```
Look through the site in every language you keep, then merge the branch into your main branch.

Updating Dependencies

npm outdated lists newer versions of the theme’s tools. Major updates of Astro or Tailwind CSS can need code changes; wait for a Margo release that includes them unless you are comfortable fixing build errors.