We’ve added a new way for theme developers to control the experience of a site. Themeable site settings allow themes to override a limited group of site settings defined by Discourse core. 
How are themeable site settings different?
We already have concepts of theme settings and theme modifiers, so how are themeable site settings different? Here is a quick summary:
- Theme settings - These are custom settings used to control UI and functionality within your theme or component and provide configuration options. These cannot change core Discourse functionality.
- Theme modifiers - Allows a theme or a component to modify selected server-side functionality of core Discourse as an alternative to building a plugin.
Themeable site settings (new) - Allows a theme (not components) to override a small subset of core site settings, which generally control parts of the UI and other minor functionality. This allows themes to have a greater control over the full site experience.
Themeable site settings have identical data types and values to the site settings which they overide. For all intents and purposes, the value of the site setting in the database becomes irrelevant, since each theme controls this value individually now.
How can admins view and change themeable site settings?
Admins can view and change themable site settings in two places. First, on each individual theme page there is now a “Settings the theme can override” section like so, above the other section which shows theme settings defined by the theme:
The dot indicates the value has been changed from whatever the default value of the site setting is. Pressing “reset” will change the theme site setting value to match the site setting default value.
The second place admins can view these settings is at a new page, /admin/config/theme-site-settings :
From here admins can see all themeable site settings, what the default site setting value is, and which themes are overriding this value. When you hover over a theme name, the UI will show the value that this theme has set.
What will happen to my existing site setting changes?
If you have changed enable_welcome_banner or search_experience from the default values on your site, we will automatically migrate these values to every theme you have installed on your site, so nothing will change in the UI for your members.
Where are they defined?
Themeable site settings are defined in the core config/site_settings.yml file. Each themeable site setting has the themeable: true option defined.
For the moment, only two site settings are themeable – enable_welcome_banner and search_experience – but in future we will likely make more site settings themeable.
How can theme authors control default values?
Theme authors can define theme site setting overrides in the about.json file under a theme_site_settings key like so:
"theme_site_settings": {
"enable_welcome_banner": false
}
Any value here will be saved to the database and associated with the theme. Once a value has been saved, changes to the theme_site_settings in the about.json file when a theme updates will not affect the currently saved database value, since we cannot know whether the admin has changed the setting in the interim.
What are the limitations of themeable site settings?
Themeable site settings are only really intended to control elements of the UI, and when retrieving their value we require a theme ID, so these limitations apply:
- Themeable site settings cannot be used in Sidekiq jobs
- Themeable site settings cannot be used in markdown rules
- Themeable site settings will be cached separately to client site settings using theme ID as a key
- Themeable site settings will override keys on the
siteSettingsservice on the client using the application preloader SiteSetting.client_settings_jsonwill not include themeable site settings, instead you can callSiteSetting.theme_site_settings_jsonwith a theme ID
As a general rule, theme site settings will only be for simple settings that control parts of the UI, nothing server-side.