--- title: Automated settings reference description: Elastic Docs V3 can build a Markdown settings reference from a YAML source file. The {settings} directive is generic. Although the largest current examples... url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4047/syntax/automated_settings products: - Elastic Docs Builder --- # Automated settings reference Elastic Docs V3 can build a Markdown settings reference from a YAML source file. The `{settings}` directive is generic. Although the largest current examples come from Kibana, the directive can be used by any documentation repository that wants to render structured settings from YAML. ### Syntax ```markdown ::::{settings} /syntax/settings-with-applies-example.yml :::: ``` #### Options Filters the rendered settings to only those available for the specified deployment type. When omitted, all settings are shown regardless of deployment. Valid values: `ech` (Elastic Cloud Hosted), `ece` (Elastic Cloud Enterprise), `eck` (Elastic Cloud on Kubernetes), `self` (self-managed). A setting is considered available for a deployment type if its `applies_to` metadata lists that deployment with a lifecycle other than `removed` or `unavailable`. Flat keys such as `ech: ga` and a nested `deployment:` map both work. If a setting has `applies_to` metadata but no entry for the requested deployment, it is treated as unavailable and hidden. Settings with no `applies_to` metadata at all are always shown, regardless of the filter. ```markdown ::::{settings} /syntax/settings-with-applies-example.yml :deployment: ech :::: ``` ### Schema The schema below reflects the structure currently supported by docs-builder. For the original settings-gen schema that inspired this format, see [the Kibana schema reference](https://github.com/elastic/kibana/tree/main/docs/settings-gen#schema). ```yaml product: REQUIRED collection: REQUIRED # id: OPTIONAL # page_description: OPTIONAL multiline Markdown # note: OPTIONAL multiline Markdown or string groups: - group: REQUIRED # id: OPTIONAL # description: OPTIONAL multiline Markdown # note: OPTIONAL multiline Markdown or string # example: OPTIONAL multiline Markdown settings: - setting: REQUIRED description: | REQUIRED Multiline Markdown. # id: OPTIONAL # applies_to: OPTIONAL docs-builder applicability metadata # # Same keys as applies.md. The authoring contract is different. # See "applies_to in settings YAML" on this page. # # applies_to: # stack: ga 9.2 # ech: ga # ece: ga # eck: ga # self: ga # serverless: ga # # note: OPTIONAL # tip: OPTIONAL # warning: OPTIONAL # important: OPTIONAL # deprecation_details: OPTIONAL # datatype: OPTIONAL # default: OPTIONAL # options: # - option: OPTIONAL # description: OPTIONAL # example: OPTIONAL multiline Markdown # settings: OPTIONAL nested settings list # Child settings inherit applies_to when they omit the field. # A child applies_to map replaces the parent. It does not merge keys. # - setting: "[n].url" # description: | # REQUIRED ``` ### applies_to in settings YAML The keys are the same as [Applies to](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4047/syntax/applies). The authoring contract is different, because each setting renders a **Supported on** line. In settings YAML, list every deployment key so that line is complete and the `:deployment:` filter is explicit. | Key | What it means here | Write | |-----------------------------|--------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `stack` | The setting's lifecycle and versions it's available in | `ga`, `preview 9.2`, or a history such as `preview 9.0-9.2, ga 9.3+`. Omit the version if the setting was added before 9.0. | | `ech`, `ece`, `eck`, `self` | Supported on that deployment, or not | Always list all four. `ga` if supported. `unavailable` if not. Never a version. Never `preview`, `experimental`, `deprecated`, or `removed`. | | `serverless` | Supported on serverless, or not | Always list it. `ga` if every serverless project supports it. `unavailable` if none do. Never a version. Never `preview`, `experimental`, `deprecated`, or `removed`. If only some projects support it, nest those project keys. | `ga` on a deployment key is a support flag. It does not mean the setting is generally available. If `stack` is `preview` and the setting exists on Elastic Cloud Hosted, write `ech: ga`. Some settings exist on only some serverless projects. This is common for Advanced Settings. When that is the case, nest those project keys under `serverless`. The keys are `elasticsearch`, `observability`, `security`, and `vectordb`. Write `ga` on the projects that include the setting. Those keys are support flags. Never write a version. Never write `preview`, `experimental`, `deprecated`, or `removed`. Do not nest `workplace_ai`. That project type never shipped, and docs-builder has no `workplace_ai` key. Do not mix a scalar `serverless:` with project keys. Existing settings YAML sometimes lists those project keys as siblings of `stack`. That form still parses. Prefer the nested `serverless:` map for new entries. `unavailable` is not rendered as a badge. It hides the setting from `:deployment:`. Omitting a deployment key also hides it from that filter. Still write `unavailable` so the Supported on line is complete. Child settings inherit the parent's `applies_to` when they omit the field. If a child sets `applies_to`, that map replaces the parent. It does not merge keys. To scope a `note`, `tip`, `warning`, or `important` to a version or deployment, put `:applies_to:` on the first line of that field. docs-builder wraps the field in an admonition. Do not add a `:::{note}` wrapper. Preferred map (supported everywhere): ```yaml applies_to: stack: ga 9.2 ech: ga ece: ga eck: ga self: ga serverless: ga ``` Technical preview that is still supported on every deployment: ```yaml applies_to: stack: preview 9.2 ech: ga ece: ga eck: ga self: ga serverless: ga ``` Self-managed only: ```yaml applies_to: stack: ga 9.2 ech: unavailable ece: unavailable eck: unavailable self: ga serverless: unavailable ``` Observability serverless only: ```yaml applies_to: stack: ga 9.2 ech: ga ece: ga eck: ga self: ga serverless: observability: ga ``` The same nested shape works for `elasticsearch`, `security`, and `vectordb`. ### Example See `/syntax/settings-with-applies-example.yml` for a full, schema-compliant sample. It demonstrates: - Group `description`, `note`, and `example`. - Setting `id`, `datatype`, `default`, and `options`. - `note`, `tip`, `warning`, `important`, and `deprecation_details`. - Nested `settings`. - A complete `applies_to` map, including `unavailable` keys and `stack: preview` with `ech: ga`. - `applies_to` inheritance when a child omits the field, and replacement when it sets its own map. - Inline `{applies_to}` badges inside a setting `description` for version-scoped behavior that is not the `default` field. - A gated `note` for a previous default, and a gated `warning` with `:applies_to:` on the first line. - Top-level `page_description`. ### Result _Everything below this line is auto-generated._ This page demonstrates schema-compliant settings output, including applies_to badges, nested settings, metadata lines, options, admonitions, and examples. #### General settings These settings show top-level schema fields, metadata, and applies_to usage. ```yaml xpack.example.enabled: true xpack.example.mode: strict ``` Elastic Stack: Preview since 9.2 Elastic Cloud Serverless: Generally available, Elastic Cloud Hosted: Generally available, Elastic Cloud on Kubernetes: Generally available, Elastic Cloud Enterprise: Generally available, Self-managed Elastic deployments: Generally available Enables the example feature. Datatype: `bool` Default: `true` Options: - `true`: Turns the feature on. - `false`: Turns the feature off. Disable this only for troubleshooting. Keep this enabled in production. Elastic Stack: Generally available since 9.1 Elastic Cloud Serverless: Generally available, Elastic Cloud Hosted: Generally available, Elastic Cloud on Kubernetes: Generally available, Elastic Cloud Enterprise: Generally available, Self-managed Elastic deployments: Generally available Controls runtime mode. Datatype: `enum` Default: `strict` Options: - `strict`: Full validation. - `lenient`: Reduced validation. Lenient mode may hide configuration mistakes. Strict mode is recommended for production. The `lenient` option will be deprecated in a future release. ```yaml xpack.example.mode: strict ``` Elastic Stack: Generally available since 9.1 Elastic Cloud Serverless: Generally available, Elastic Cloud Hosted: Generally available, Elastic Cloud on Kubernetes: Generally available, Elastic Cloud Enterprise: Generally available, Self-managed Elastic deployments: Generally available Default model used by the feature. Elastic Stack: Generally available since 9.2 The model picker is also available in Discover. Datatype: `string` Default: `model-v2` In this version, this setting defaults to `model-v1`. #### Advanced settings These settings demonstrate nested entries and applies_to inheritance. Elastic Stack: Generally available since 9.2 Self-managed Elastic deployments: Generally available List of custom host settings. Datatype: `object` Default: `[]` Elastic Stack: Generally available since 9.2 Self-managed Elastic deployments: Generally available Child setting inherits applies_to from the parent. Datatype: `string` Elastic Stack: Preview since 9.3 Self-managed Elastic deployments: Generally available Child setting replaces the parent applies_to map. Datatype: `enum` Default: `strict` Options: - `strict`: Requires strict checks. - `lenient`: Allows lenient checks. Keep all host modes aligned to simplify troubleshooting and reduce drift. ```yaml xpack.example.hosts: - url: https://example.org mode: strict ``` For large Kibana-exported YAML samples used in local stress tests, see `kibana-settings-yaml-samples.md` in the `docs-tests/` docset at the repository root (outside the main `docs/` folder).