Site options vs config options

On some projects we may need global options to control the behaviour of the site. For my latest project I needed some theme options to set some styles, fonts etc. That’s because I may set up similar sites in the future with the same base.

We can approach this in at least two different ways. Site options or config options. I’ve tried both and I realize now that I’ve used site options too much.

Site options

With this I mean the site page form in the panel.


  • Users without code experience can set up whatever they need, because it’s in the panel.
  • It’s perfect for images, because they are easy to just drag in and add to an image field. It’s also simple to get in a template/snippet.
  • We don’t need the code editor to change these options.

In conclusion

Use it when your users needs to have access to the options. Also use if your options are images and you find them easier to handle in the panel.

Config options

With this I mean config.php in the config folder.


  • When we build our site with code, it’s easier to open a config file than logging in to the panel.
  • It’s less code and therefor less work and less to maintain. We don’t need to edit a blueprint file etc.

In conclusion

Use it when your users does not need to have access to your options. It’s especially good for types that are not images.

If you are going to use images as options without the panel, you need to find a simple way for it. One way is to use predefined filenames that never changes, like logo.png or hero.jpg. With such names you don’t even need an option in the first place.

Final words

Config options may be better than you think. Or the other way around, you may be overdo things with site options. Do the unexperienced users really need all that site options? Maybe you can cut half of it? I learned the hard way that I can cut most of it and only keeping it in the config options.



It was a long time habit of mine to make it possible for a user to customize their site in a lot of aspects. I think its caused by a long WordPress background and themes in general. :wink:

There was a thread here some time ago where somone wanted a better way to implement themes within kirby. Getting rid of the theme thinking made my life sooo much easier.

So all for the config options!


Yes, I also came from the WP world, where there is almost no such thing as editing files manually.

Because that I will have similar sites I need to make configurable. I’ll give a few examples.

CSS variables

Below I have a snippet that includes some css varables that I then use in a CSS file. I have shorten it down a bit.

1st step

It was even more complicated than below, because I used an array that I looped which made it less readable.

It may look simple at first sight but the values comes from a controller so there are a few abstraction layers before it actually does something useful. I did that so I could preview with different data in Component Kit but in the end it was too much work with too little gain.

:root {
  --bar-background: <?= $bar_background; ?>;
  --bar-background-active: <?= $bar_background_active; ?>;
  --bar-background-hover: <?= $bar_background_hover; ?>;
  --bar-color: <?= $bar_color; ?>;

2nd step

Now I get the data directly from the config file. It’s easier to understand where the data came from. Also I did not need to have anything in the controller.

:root {
  --bar-background: <?= c::get(''); ?>;
  --bar-background-active: <?= c::get(''); ?>;
  --bar-background-hover: <?= c::get(''); ?>;
  --bar-color: <?= c::get(''); ?>;

3rd step

Then I thought, what the heck. I don’t need any config values at all. I just need a snippet that is unique for each site.

:root {
  --bar-background: red;
  --bar-background-active: rgba(0,0,0,.2);
  --bar-background-hover: rgba(255,255,255,.1);
  --bar-color: #fff;

Folder structure

I don’t show all folders, just the relevant stuff.

1st step

All that is unique for the site I placed in site/plugins/theme.






I thought it became a bit messy so I changed the structure.

2nd step

The idea of this structure is that I have 5 different kind of things:

  • Cache - Resized thumbnails and cached content
  • Content - The content
  • Kirby - Kirby and the panel
  • Core - What is called site by default. Things that can be used on multiple sites.
  • Theme - Custom stuff for the site





So if I want to copy the unique files to a new site, all I need to copy is the theme folder, nothing else. If I made an update to the shared files I only need to update the core folder.

I have a config folder in both the core and the theme because some options are the same for every possible site. The same thing with assets. I have two CSS files which I merge with a route.

The thing is, me thinks, Kirby makes it very damn easy and beautiful to customize almost everything.

The dangers of flexibility and versatility on my type of personality. Read: obsessive over some stuff. :laughing: