feat(settings): add :deployment: filter option to {settings} directive

[florent-leborgne]

Why

Documentation consumers often only care about settings available for a specific deployment model (e.g. Elastic Cloud Hosted). Without a filter, they have to manually skip settings that do not apply to their environment, which adds friction and noise.

This is done with the idea of automating this page https://www.elastic.co/docs/reference/kibana/cloud/elastic-cloud-kibana-settings like other settings pages - but because this specific page is rather a legacy, ECH-only, view of kibana settings, I want to find a way to also relying on the individual yaml settings files (and reference them all in that page but to just show those on ECH). This allows this page to keep existing while centralizing its maintenance.

This page has value for ECH users as it avoids that they have to go through each individual settings page, so it would be sad to get rid of it while there is a simple path to keep it while avoiding manual maintenance.

Today some eng teams are confused and are updating this page instead of yaml files because it's the only .md file they find with their settings in it. By having it use a similar logic to other kibana settings files, we're making this a lot more obvious.

What

Adds a :deployment: option to the {settings} directive. When set to ech, ece, eck, or self, the renderer hides every setting whose applies_to.deployment block either omits the requested deployment or marks it as removed/unavailable. Settings with no applies_to metadata at all remain visible (they are universally applicable).

The filtering is applied consistently in three places: HTML rendering (via SettingsViewModel), table-of-contents generation, and anchor collection. A warning is emitted when an unknown deployment value is supplied.

Documentation for the new option is added to docs/syntax/automated_settings.md, and live filtered examples using real Kibana YAML fixtures are added to the Kibana settings test page.

Made with Cursor

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a :deployment: filtering option to the {settings} directive in the markdown processing pipeline. When applied, the option filters settings visibility based on deployment type (ech, ece, eck, self). The implementation defines a DeploymentFilter helper with validation and visibility logic, updates SettingsBlock to parse and validate the deployment parameter, flows the filter through SettingsViewModel with new visibility helpers, and conditionally renders settings in the view based on whether they apply to the selected deployment. The HTML renderer wires the block's filter to the view model. Documentation explains the feature, and tests cover filtering behavior, missing deployment entries, and invalid values.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 15.38% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main feature being added: a :deployment: filter option to the {settings} directive.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The description clearly explains the feature's purpose, implementation approach, and scope—adding a :deployment: filter to the {settings} directive with specific valid values and filtering logic.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feature/settings-deployment-filter

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[theletterf]

Nice!