# Announcing themeable site settings

**URL:** https://meta.discourse.org/t/announcing-themeable-site-settings/374377
**Category:** Development
**Tags:** dev-news, theme-site-settings
**Created:** [July 16, 2025, 1:01am UTC](https://meta.discourse.org/t/announcing-themeable-site-settings/374377 "2025-07-16T01:01:38Z")
**Posts on this page:** 1
**Showing post:** 1

<div class="post-metadata">

### Author: ![martin](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/martin/32/491371_2.png) [@martin](https://meta.discourse.org/u/martin)
#### Post date: [July 16, 2025, 1:01am UTC](https://meta.discourse.org/t/announcing-themeable-site-settings/374377/1 "2025-07-16T01:01:38Z")

</div>

This is a sister topic to the announcement at [Themeable site settings are now available](https://meta.discourse.org/t/themeable-site-settings-are-now-available/374232) so developers are aware.

> [@Themeable site settings are now available](https://meta.discourse.org/t/themeable-site-settings-are-now-available/374232/1):
>
> ### 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:
> 
> ```plaintext
> "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](https://github.com/discourse/discourse/pull/32233)

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

---

_[View the full topic](https://meta.discourse.org/t/announcing-themeable-site-settings/374377)._