Child theme tutorial

Build a child theme#

Start with a clean local VoltexaHub install: run composer install, copy .env.example to .env, configure a disposable local database, run php artisan key:generate, then php artisan forum:install [email protected]. Set FORUM_ADMIN_PASSWORD in the process environment or enter a password at the prompt. Run npm ci && npm run build. Never commit .env, database files or generated accounts.

1. Run php artisan forum:make-theme sunrise. This creates themes/sunrise/theme.json, assets/custom.css, and an empty views/ directory. IDs are lowercase, start with a letter, and are at most 32 characters; the command refuses an existing directory.
2. Edit themes/sunrise/assets/custom.css. The generated stylesheet changes the accent in light and dark modes. Child assets load after the base theme without rebuilding.
3. Activate it in Administration → Themes or run php artisan forum:theme sunrise. Load the home page and confirm <html data-theme="sunrise"> and the declared /theme-assets/sunrise/custom.css stylesheet. Check a discussion page and both appearance modes.
4. To customize structure, copy one file from themes/default/views/ into themes/sunrise/views/ and declare its current revision in view_revisions in theme.json. Read the view reference; keep authorized data and form contracts intact. A view not copied inherits from Default.
5. Recover from a broken public override through Administration → Themes or php artisan forum:theme default. Admin pages do not boot the public theme.

Do not edit core or default theme files for a custom theme. Package the themes/sunrise directory, then activate it on the destination after installing the application. Review override warnings when upgrading VoltexaHub.