CodePress/guide/en/admin-beheerder/thema-beheer.md

Theme management

Managing themes

1. Go to Theme in the admin menu
2. Edit — Click the pencil icon to edit theme files (see Theme editor)
3. Activate — Click the checkmark to activate a theme (stored in config.json)
4. Compile SCSS — Click the palette icon to force-compile SCSS to assets/css_compiled/theme.css
5. Delete — Trash icon (only non-active, non-default themes)
6. New theme — Create a custom theme, optionally based on an existing theme

Theme status badges

In the theme overview you see per theme:

• Active (green) — this theme is selected in config.json
• SCSS ok (green) — assets/css_compiled/theme.css is newer than assets/scss/theme.scss
• SCSS stale (yellow) — SCSS source was changed after the last compile; click the palette icon to compile

Theme editor

Via Edit (pencil icon) in the theme overview you open the theme editor (/admin/theme-edit?theme=<name>). It works the same as the plugin editor:

File browser sidebar

• Shows the nested file tree of the theme, with a clickable theme root at the top
• assets/css_compiled/ is hidden (runtime artefact, read-only)
• Click a file to open it in the CodeMirror editor
• Click a folder to open the folder detail pane on the right (new file, new folder, upload, delete)
• Folders containing the active file are auto-expanded
• Per folder there are action buttons: new file, new folder — they operate on the selected folder
• Per file there are action buttons: rename/move (pencil), delete (trash) — appear on hover

Drag-and-drop

• Drag a file or folder onto another folder to move it
• Valid drop targets are highlighted during dragging
• The move is performed via an AJAX call — the page reloads automatically on success
• theme.json cannot be moved

Editable file types

.twig, .json, .scss, .css, .js, .html, .md, .php

Create a new file / folder

• Select the target folder in the sidebar (click the folder name), or use the root
• Click New file or New folder (in the folder-detail pane or at the top)
• For a new file: enter a path within the theme (e.g. partials/header.twig or assets/scss/_variables.scss)
• Subfolders are created automatically
• Allowed: twig, json, scss, css, js, html, md, php
• A stub is auto-generated (e.g. {% extends 'base.twig' %} for .twig)

Upload a file

• Click Upload to upload files to the theme's assets/
• Allowed: images, video, audio, PDF, ZIP, CSS, SCSS, JS, JSON, HTML, MD, TWIG, fonts
• Path-traversal protection: target dir must stay within assets/

Move / delete a file

• Move: drag the file onto another folder (drag-and-drop), or click the pencil icon next to the file to go to the move form
• Delete: click the trash button next to the file in the sidebar, with confirmation; theme.json cannot be deleted

Folder management

• Click a folder in the sidebar to open the folder-detail pane on the right
• New file / new folder / upload into this folder: use the buttons in the folder-detail pane
• Delete folder: delete button in the folder-detail pane (only empty folders)
• The theme root is also selectable (click the theme name at the top of the tree)

Compile SCSS from the editor

• At the top of the editor there is a Compile SCSS button (only if assets/scss/theme.scss exists)
• Shows the compile status: up-to-date (green) or stale (yellow)
• Forces compilation via ThemeManager::compileCss(true)

Insert media in the editor

• The media button in the editor toolbar opens the media modal
• In theme context it scans themes/<name>/assets/ (via /admin/media-list?theme=<name>)
• Snippet format depends on file type: markdown → ![alt](url), html/php → <img src=...>, others → raw URL

Security

• All actions require a CSRF token
• Path-traversal protection via realpath() + prefix check on the theme dir
• theme.json can be edited but not deleted/moved
• Default theme can be edited but not deleted
• Active theme cannot be deleted (activate another theme first)

Theme structure

themes/default/
├── theme.json              # { title, config.default_template, template: layout→.twig }
├── README.md               # Theme documentation (per theme)
├── base.twig               # Main layout (head, header, nav, breadcrumb, footer)
├── full_content.twig       # Layout: full width
├── left_sidebar.twig       # Layout: sidebar on the left
├── right_sidebar.twig      # Layout: sidebar on the right
├── custom1.twig            # Layout: custom
├── guide.twig              # Layout: guide with sidebar (Navigation plugin)
├── partials/               # header.twig, navigation.twig, footer.twig
└── assets/
    ├── scss/theme.scss     # SCSS source (only CSS source — manual css/theme.css must not exist)
    ├── css_compiled/       # Generated by scssphp (read-only, do not edit manually, hidden in editor)
    ├── css/                # External CSS (bootstrap.min.css, bootstrap-icons.css, mobile.css)
    ├── js/                 # app.js, bootstrap.bundle.min.js
    ├── fonts/              # bootstrap-icons.woff, woff2
    └── img/                # favicon, icon, world-map

New themes created via admin automatically get this uniform structure (with README.md, base.twig, full_content.twig, partials/header.twig, partials/footer.twig, assets/scss/theme.scss, and all assets subfolders).

theme.json

{
    "title": "default",
    "config": {
        "default_template": "full_content"
    },
    "template": {
        "full_content": "full_content.twig",
        "left_sidebar": "left_sidebar.twig",
        "right_sidebar": "right_sidebar.twig",
        "custom1": "custom1.twig",
        "guide": "guide.twig"
    }
}

• title — Display name in admin
• config.default_template — Default layout for pages without a layout: frontmatter
• template — Mapping from layout name to .twig file

SCSS compilation

• ThemeManager compiles assets/scss/theme.scss at runtime to assets/css_compiled/theme.css via scssphp
• css_compiled/ is read-only — do not edit manually (hidden in the theme editor)
• assets/css/theme.css must not exist; otherwise ThemeManager::getCssUrl() ignores the SCSS
• Force compilation via the Compile SCSS button in admin (or remove assets/css_compiled/theme.css and .mtime)

Layouts

Layouts are chosen via the frontmatter layout: key in content files. Unknown layouts fall back to config.default_template from theme.json.

guide.twig

Special layout for guides. Injects the Navigation plugin into the sidebar for sidebar navigation. Automatically used for pages in the guide/ folder.