Announcing themeable site settings

[martin (Martin Brennan)]

This is a sister topic to the announcement at Themeable site settings are now available so developers are aware.

@martin

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 siteSettings service on the client using the application preloader
• SiteSetting.client_settings_json will not include themeable site settings, instead you can call SiteSetting.theme_site_settings_json with 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.

The initial PR is here https://github.com/discourse/discourse/pull/32233

Developer docs are here https://meta.discourse.org/t/controlling-site-settings-with-themes/374376