Appearance
Customising an Omeka S theme well comes down to one rule: never edit core files in place. Copy the stock theme into a new, uniquely named folder under themes/, override only the specific templates you need by mirroring their paths inside your theme's view/ directory, and keep every change in Git with a short note explaining why. That keeps your work safe through updates and legible to whoever maintains the collection after you.
How does Omeka S theme resolution actually work?
Omeka S uses a fallback chain. When it renders a page it looks first in your active theme, then in the relevant module, then in core. So to change the item display page you do not touch the original file — you create the same path inside your theme:
bash
# from your Omeka S install root
cp -r themes/default themes/mycollection
mkdir -p themes/mycollection/view/omeka/site/item
# now override just the item "show" page
cp application/view/omeka/site/item/show.phtml \
themes/mycollection/view/omeka/site/item/show.phtmlEdit the copied show.phtml. Everything you did not copy keeps inheriting from core, so a future update still patches those pages for you.
What belongs in config/theme.ini?
The config/theme.ini file is the theme's contract with the admin UI. The [info] block names and versions the theme; the [config] block declares settings that appear as editable form fields. A minimal example:
ini
[info]
name = "My Collection"
version = "1.0.0"
author = "Elara Reed"
omeka_version_constraint = "^4.0.0"
[config]
elements.logo.name = "logo"
elements.logo.type = "Omeka\Form\Element\Asset"
elements.logo.options.label = "Site logo"Now an admin uploads a logo through the interface — no code edit, no redeploy. Push as much branding as you reasonably can into theme settings so editorial staff stay self-sufficient.
Where should custom CSS and assets live?
Keep them inside your theme, never in core. A clean layout:
themes/mycollection/
├── asset/
│ ├── css/custom.css # your overrides only
│ └── img/
├── config/theme.ini
├── view/ # template overrides mirror core paths
└── theme.jpg # thumbnail shown in adminPutting overrides in a separate custom.css rather than editing the bundled stylesheet means a git diff shows precisely what you changed. Avoid !important cascades; prefer adding a scoping class in your overridden template and styling that.
Which templates are safe to override first?
Start with the highest-leverage, lowest-risk files:
| Template | Path under view/ | What it controls |
|---|---|---|
| Layout | layout/layout.phtml | Global header, footer, <head> |
| Item show | omeka/site/item/show.phtml | Single-item page |
| Item browse | omeka/site/item/browse.phtml | Search/result lists |
| Page | omeka/site/page/show.phtml | Static and exhibit pages |
Override the layout for site-wide chrome, then the item show page for how your metadata reads. Resist overriding browse pagination logic unless you genuinely need it — that is where subtle breakage hides.
How do I keep customisations reproducible across a whole collection?
Treat the theme as code. Commit the folder, tag releases that match your Omeka S version, and maintain a short CHANGELOG.md. In a top-of-file comment in each overridden template, record the date and reason. When a colleague asks "why does the item page hide the Source field?", the answer is one git blame away rather than archaeology.
A working checklist
text
[ ] Copied stock theme to a uniquely named folder
[ ] Theme tracked in Git from commit one
[ ] Overrides mirror core paths under view/
[ ] CSS overrides isolated in custom.css
[ ] Branding exposed via theme.ini [config]
[ ] omeka_version_constraint matches install
[ ] CHANGELOG notes every overridden template + reason
[ ] Tested on a staging copy before going liveKey Takeaways
- Copy the stock theme; never edit Default or core templates in place.
- Override single templates by mirroring their core path under
view/. - Keep custom CSS isolated in
custom.cssfor clean diffs. - Expose branding through
theme.iniso admins stay self-sufficient. - PHTML changes need no rebuild — just refresh the browser.
- Version the theme in Git and document every override for defensibility.
- Set
omeka_version_constraintso the theme refuses to load against an incompatible core.
Frequently Asked Questions
Should I edit the Default theme directly?
No. Copy the theme into a new folder under themes/ with a unique name and edit that. Editing Default in place means the next module or core update can overwrite your work, and you lose a clean fallback.
Where do I override a single template without copying everything?
Mirror the file's path inside your theme's view/ directory. Omeka S resolves templates theme-first, so a file at view/omeka/site/item/show.phtml overrides only the item show page and leaves everything else inheriting from the parent.
How do I add custom CSS that survives updates?
Put your styles in asset/css/ in your own theme and enqueue them through the theme, not by hand-editing core CSS. Keep your overrides in a separate file like custom.css so a diff shows exactly what you changed.
Can I expose theme options to non-technical site admins?
Yes. Declare settings in config/theme.ini under [config] and render them with Omeka's form elements. Admins then set logos, colours and footer text in the UI without touching code.
Do I need to recompile anything after editing a .phtml file?
No. PHTML templates are interpreted at request time, so a browser refresh shows changes immediately. Only Sass or a build step (if you add one) needs recompiling; plain CSS does not.
How do I keep theme changes reproducible across a collection?
Version the theme folder in Git, write a CHANGELOG, and document which templates you overrode and why. That record is what makes a customisation defensible months later.