Theming

Building Your First Theme

developers theming

This walks through the smallest theme that actually works — enough to see your own homepage rendering, which is the fastest way to understand how the pieces fit together before diving into the full Theme Structure reference.

What you'll need

Access to your SynaptikCMS files, a text editor, and about 15 minutes.

Step 1 — Create the folder

Inside /theme/, create a folder for your theme. Its name becomes the theme's identifier, so avoid spaces and never name it default (that name is reserved for the bundled fallback theme):

/theme/my-first-theme/

Step 2 — The manifest

Every theme needs a theme.json:

{
    "synaptik_theme": true,
    "name": "My First Theme",
    "version": "1.0.0",
    "description": "A minimal starting theme.",
    "author": "Your Name"
}

"synaptik_theme": true is what tells the CMS this folder is a real theme, distinct from anything else that might be sitting under /theme/.

Step 3 — A stylesheet

Themes require exactly one CSS file, at exactly this path: css/style.css. It can start empty — even an empty file is enough for the theme to be detected and selectable in Admin → Appearance → Themes.

/* theme/my-first-theme/css/style.css */
body { font-family: system-ui, sans-serif; max-width: 720px; margin: 0 auto; padding: 20px; }

Step 4 — Header, footer, and a homepage

At minimum, add header.php, footer.php, and home.php. Without them, the CMS silently borrows the default theme's versions — your CSS would load, but against someone else's HTML.

<!-- theme/my-first-theme/header.php -->
<!DOCTYPE html>
<html lang="<?php echo htmlspecialchars($settings['site_language'] ?? 'en'); ?>">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title><?php echo $metaTitle; ?></title>
    <?php echo render_meta_tags($settings, $metaTitle, $metaDescription); ?>
    <?php echo render_header_scripts($headerScripts); ?>
</head>
<body>
<?php render_adminbar(); ?>
<main>

<!-- theme/my-first-theme/footer.php -->
</main>
<?php echo render_search_ui(); ?>
</body>
</html>

<!-- theme/my-first-theme/home.php -->
<h1><?php echo htmlspecialchars($settings['site_title'] ?? 'My Site'); ?></h1>
<?php foreach (($data['article'] ?? []) as $article): ?>
    <?php echo render_article_card($article); ?>
<?php endforeach; ?>

That's a working theme — a real <head> with SEO tags and every required system script, an admin bar that appears only when you're logged in, working search, and a homepage listing your articles using the CMS's own default card rendering (which you can override later, see Partials & functions.php).

Step 5 — See it without going live

Go to Admin → Appearance → Themes, and use Live Preview on your new theme — it renders your actual site with this theme, visible only to you, without switching anything for real visitors. See Live Theme Preview for how that works under the hood. Once you're happy, Activate it.

Where to go from here

A real theme needs single-item views (content-articles.php, content-pages.php, content-projects.php) and a list view (content-list.php) too — missing ones just keep falling back to the default theme, so you can build these out incrementally rather than all at once. From here:

Theme Structure — the full file layout and pre-publish checklist.
Templates — every template file and what's injected into it.
Rendering Functions — every render_* helper available to you.
Front-End CSS Tokens — the CSS variables your stylesheet can hook into for search, galleries, and shortcodes to look right.