Theaming Part 1

Part 1 of 3 • Plain-English Theme Guide

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 named base.
  • 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 as home.php, page.php, article.php, book.php, content.php, private.php, 404.php, error.php, or slug-specific templates like page-about.php.
  • partials/ & assets/ (Optional): Reusable pieces like header.php, footer.php, meta.php, and vendor-css.php live in partials/, while static files live under assets/ in folders like css/, js/, img/, and fonts/.

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:

  1. Active Child Theme First: user/themes/{active}/{path}.
  2. Base Theme Second: core/themes/base/{path}.
  3. 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:

  1. templates/{type}-{slug}.php (for example page-about.php or article-my-first-post.php, only when the slug uses a-z, 0-9, _, and -).
  2. templates/{type}.php (such as page.php, article.php, or book.php).
  3. 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.