Config options

A reminder that Kirby config options docs can be found at https://getkirby.com/docs/guide/configuration, but here we will explain what is in the Zero One theme config.

Multi-environment Setup (Recommended)

Kirby allows you to split your configuration into multiple files based on the current environment. While this setup is optional, we strongly recommend using it for all Zero One projects.

Instead of placing all custom configuration options inside site/config/config.php, you can organize them into separate files:

# Example setup

site/config/
├── config.php
├── config.localhost.php
├── config.staging.your-domain.com.php
├── config.your-domain.com.php 
└── config.www.your-domain.com.php

Learn more in the Kirby official guide.

This approach provides several advantages:

• Keeps your configuration cleaner and easier to maintain.

• Separates local, staging, and production settings.

• Makes troubleshooting easier.

• Prevents your main configuration file from becoming cluttered with customizations.

• Makes future Zero One updates easier to apply.

Important: Some Zero One updates may occasionally require changes to the default config.php file. If all your custom settings are stored there as well, updating becomes more difficult and increases the risk of merge conflicts or accidentally overwriting your changes.

For this reason, we recommend keeping config.php as minimal as possible and storing most customizations inside environment-specific configuration files whenever possible.

How Multi-environment Configuration Works

When using a multi-environment setup, Kirby first loads the main:

site/config/config.php

and then loads the matching environment configuration file, for example:

site/config/config.localhost.php

or

config.www.your-domain.com.php

The environment-specific configuration extends the main configuration and can override any option defined in config.php.

Example

Main configuration:

site/config/config.php

return [

    'debug' => false,

    'cache' => [
        'pages' => true
    ],

];

Local development configuration:

site/config/config.localhost.php

return [

    'debug' => true,

];

In this case, Kirby will use:

'debug' => true

because the environment-specific configuration overrides the value from config.php.

However, the cache configuration is still inherited from config.php:

'cache' => [
    'pages' => true
]

Think of config.php as your project's base configuration, while environment-specific files contain only the settings that differ between environments.

Where Should I Put New Config Options?

Most code examples throughout this documentation show only the configuration snippet that needs to be added. Before copying any option, it's important to understand where it belongs.

While Kirby allows you to place all options directly in site/config/config.php, we strongly recommend using a multi-environment setup instead (explained above). This keeps your configuration organized, makes maintenance easier, and helps prevent your custom settings from being overwritten when following future Zero One updates.

For example, when the documentation shows:

site/config/config.your-domain.com.php

return [
    'panel' => [
        'slug' => 'your-secret-login'
    ],
    
    // The rest of your config options
    
];

you should usually add that option to your environment-specific configuration file rather than the main config.php.

Recommended Setup

Instead of storing all configuration in:

site/config/config.php

use environment-specific files such as:

site/config/
├── config.localhost.php
├── config.staging.your-domain.com.php
├── config.your-domain.com.php 
└── config.www.your-domain.com.php

This approach keeps your project cleaner, easier to manage, and safer to update.

Always Place Options Inside the Return Array

Configuration options must be added inside the return array:

✅ Correct

config.www.your-domain.com.php

return [

    'panel' => [
        'slug' => 'your-secret-login'
    ],

    // Your existing config options

];

❌ Incorrect

config.www.your-domain.com.php

return [

    // Your existing config options

];

'panel' => [
    'slug' => 'your-secret-login'
];

Always Remember the Comma

Each option in the configuration array must be separated by a comma.

✅ Correct:

site/config/config.your-domain.com.php

return [
    'debug' => false,

    'languages' => true,

    'panel' => [
        'slug' => 'your-secret-login'
    ],

];

❌ Incorrect:

site/config/config.your-domain.com.php

return [

    'debug' => false

    'languages' => true,

];

Missing commas will result in a PHP syntax error, and your website may stop working.

---

Debug

Debug is set to true on localhost and, of course, to false on the server.

Important note: When debugging is turned on, robots.txt will tell the crawlers not to index your website. So, make sure to turn off debugging mode when your website is live.

Custom panel CSS

There is an import for the custom panel CSS file. Zero One uses it to customize Editor user role permissions. That file is assets/css/panel.css and you can customize it further.

Smartypants

Smartypants are on by default in Zero One. Learn more about it at https://getkirby.com/docs/reference/system/options/smartypants

Autoresize

From Zero One version 5.0.2, the Kirby Autoresize plugin is removed, and its config options. Now you can change image upload optimization settings in these files:

• site\plugins\zero-one\blueprints\files\image.yml

• site\plugins\zero-one\blueprints\files\default.yml

Robots

There is also some settings code for Kirby 3 Robots.txt plugin from Bruno Meilick. You can add your custom rules, so check the plugin documentation.

Hooks

There is also a little site.update:after hook which is needed to write CSS code from the Site Styling Custom CSS input to assets/css/site.css.

Plugins

We also disallowed version info for some plugins that shouldn't have that information.

And that's it; the rest is up to you. 🙂