Theaming Part 1
Child Themes, Layout, theme.json & Template Resolution
In VoltCMS, every site starts with the Base theme (core/themes/base/) and can layer a child theme (user/themes/{name}/) on top of it. Because child themes live inside user/, CMS upgrades never overwrite your custom theme files.
1. Why Child Themes Make Life Easier
Instead of copying an entire theme just to tweak a header or footer, a child theme only holds what you want to change. Anything you leave out automatically falls back to Base.
Quick Start Workflow
You can create a child theme from Admin > Themes > Create a child theme (for example, naming it "My site" with folder my-site), which sets up user/themes/my-site/ with theme.json, assets/css/child.css, and empty templates/ and partials/ folders.
Small Targeted Changes
You can override just one piece—like creating user/themes/my-site/partials/footer.php or adding rules in user/themes/my-site/assets/css/child.css—and then Activate it in Admin > Themes, where VoltCMS validates it before turning it on.
2. Folder Layout & Naming Rules
A child theme folder uses a simple, predictable structure so you always know where files belong:
-
Folder Identifier: The folder name (such as
my-site) must use only lowercase letters (a-z), digits (0-9), and hyphens (-), stay within 39 characters, and cannot be namedbase. -
theme.json(Required): Holds theme metadata and global stylesheet/script lists. -
layout.php(Optional): The outer page shell wrapped around rendered templates. -
templates/(Optional): Page-type and specific templates such ashome.php,page.php,article.php,book.php,content.php,private.php,404.php,error.php, or slug-specific templates likepage-about.php. -
partials/&assets/(Optional): Reusable pieces likeheader.php,footer.php,meta.php, andvendor-css.phplive inpartials/, while static files live underassets/in folders likecss/,js/,img/, andfonts/.
3. Configuring theme.json
theme.json tells VoltCMS who built the theme, what version it is, what CMS version it requires, and which global assets under assets/ should load:
| Key | Rules & Behavior |
|---|---|
name |
Required, 1–60 characters (shown in the admin). |
version |
Required, such as "1.0.0". |
author, description |
Optional text (up to 80 characters for author and 300 characters for description). |
parent |
Omit or set to "base"—only Base can act as a parent. |
requires.cms |
Optional, such as ">=0.3.0" (supports >=, >, <=, <, =); activation is refused if the running CMS version does not satisfy it. |
assets.css / assets.js |
Paths inside assets/ loaded on every page after Base's own files, even if the file lives in Base rather than the child. |
4. How VoltCMS Finds Files & Picks Templates
Whenever VoltCMS needs a layout, template, partial, or asset, it checks locations in a clear, predictable order:
- Active Child Theme First:
user/themes/{active}/{path}. - Base Theme Second:
core/themes/base/{path}. - Built-In Safe Page Last: A minimal fallback page if Base's own files are unusable (symlinks pointing outside the theme folder are ignored).
For a page, article, or book article, VoltCMS checks templates from most specific to most general:
templates/{type}-{slug}.php(for examplepage-about.phporarticle-my-first-post.php, only when the slug usesa-z,0-9,_, and-).templates/{type}.php(such aspage.php,article.php, orbook.php).templates/content.php.
Other screens use home, tag (a tag's page), search, private (password form), 404, and error, and the first matching template found (child first, then Base) has its rendered HTML passed into layout.php as $content.