skills.rest
discourse
discourseOFFICIAL
Explore all skills by this author →
WebsiteGitHub

discourse-site-settings

Guides adding and reviewing Discourse site settings in YAML configuration files.

47.8k|9.0k|Updated Jan 12, 2013
Search Tags:#discourse#Rails#site settings#YAML configuration#Plugin Development#admin settings#I18n
One-click install
npx skills add https://github.com/discourse/discourse --skill discourse-site-settings
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: discourse-site-settings
Source: https://github.com/discourse/discourse/tree/main/.skills/discourse-site-settings
Command: npx skills add https://github.com/discourse/discourse --skill discourse-site-settings

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Adding or modifying Discourse site settings involves many conventions across YAML config files, i18n locale files, validators, and admin UI grouping. This Skill ensures settings follow Discourse naming, typing, default, and dependency conventions so they work correctly in core and plugins.

Core Features & Use Cases

  • Setting Definition Guidance: Covers config/site_settings.yml and plugin config/settings.yml, including types like bool, enum, list, group_list, category_list, and json_schema.
  • Naming and Description Conventions: Enforces suffix conventions (*_groups, *_categories), admin-facing descriptions, and {{setting:name}} tokens for cross-references.
  • Category Scope Patterns: Provides the two-setting category-scope pattern with CategoryScopeSiteSetting enum, depends_on_values, and inline dependent display.
  • Use Case: When adding a new plugin setting that filters topics by category, use this Skill to define the scope enum and category_list pair with correct defaults, i18n descriptions, validators, and tests.

Quick Start

Use the discourse-site-settings skill to add a new enum site setting with a dependent category list to my Discourse plugin.

Frequently Asked Questions about discourse-site-settings

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new site setting to a Discourse plugin?▼

Add the setting to plugins/<plugin>/config/settings.yml with a type and safe default, then add an i18n description under en.site_settings.<setting_name> in the plugin's locale file. Set client: true only if frontend code reads it via siteSettings.

What site setting types does Discourse support?▼

Discourse supports bool, integer, float, enum, list, group, group_list, category, category_list, tag_list, emoji_list, host_list, email, username, color, icon, upload, and json_schema types. Choose the simplest type matching the admin's mental model.

When should a Discourse setting use the category scope pattern?▼

Use the two-setting category-scope pattern only when a feature filters a topic or post result set and admins need all/public/include/exclude choices. For settings that simply mean 'these categories', use a plain type: category_list instead.

How do I make one Discourse setting depend on another?▼

Use depends_on for boolean parents, or depends_on_values when the parent is an enum and the dependent applies only to specific values. Add depends_behavior: hidden and dependent_setting_display: inline to control admin UI visibility, plus a server-side validator.

Why should client: true be avoided on Discourse site settings?▼

Settings with client: true are exposed to the frontend, increasing payload size and potentially leaking configuration. Only set client: true when JavaScript code must read the setting through the siteSettings service.

Related Skills

Explore More Software Engineering Skills→
bikeindexbikeindex
308

sandbox-test-setup

Configure Ruby and RSpec environments for Bike Index across macOS and sandboxes.

Official
Advanced
DFarynski99DFarynski99

discourse-upcoming-changes

Manage upcoming change feature flags in Discourse with site settings, translations, and image assets.

Community
Intermediate
joshyorkojoshyorko

37signals-caching

Implement HTTP, fragment, Russian doll, and low-level caching in Rails apps.

Community
Advanced
miXshiftmiXshift
2

mx-auth-service-setup

Exchange a one-time setup code for a MixShift service credential.

Official
Advanced