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.

::::{settings} /syntax/settings-with-applies-example.yml
::::
		

:deployment: <value>

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.

::::{settings} /syntax/settings-with-applies-example.yml
:deployment: ech
::::
		

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.

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
		

The keys are the same as Applies to. 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.

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):

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:

applies_to:
  stack: preview 9.2
  ech: ga
  ece: ga
  eck: ga
  self: ga
  serverless: ga
		

Self-managed only:

applies_to:
  stack: ga 9.2
  ech: unavailable
  ece: unavailable
  eck: unavailable
  self: ga
  serverless: unavailable
		

Observability serverless only:

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.

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.

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.

xpack.example.enabled: true
xpack.example.mode: strict
		

xpack.example.enabled

Supported on:

Enables the example feature.

Datatype: bool

Default: true

Options:

• true - Turns the feature on.
• false - Turns the feature off.

Note

Disable this only for troubleshooting.

Tip

Keep this enabled in production.

xpack.example.mode

Supported on:

Controls runtime mode.

Datatype: enum

Default: strict

Options:

• strict - Full validation.
• lenient - Reduced validation.

Warning

Lenient mode may hide configuration mistakes.

Important

Strict mode is recommended for production.

Deprecation details

The lenient option will be deprecated in a future release.

xpack.example.mode: strict
		

xpack.example.defaultModel

Supported on:

Default model used by the feature.

The model picker is also available in Discover.

Datatype: string

Default: model-v2

Note

In this version, this setting defaults to model-v1.

Advanced settings

These settings demonstrate nested entries and applies_to inheritance.

xpack.example.hosts

Supported on:

List of custom host settings.

Datatype: object

Default: []

xpack.example.hosts[n].url

Supported on:

Child setting inherits applies_to from the parent.

Datatype: string

xpack.example.hosts[n].mode

Supported on:

Child setting replaces the parent applies_to map.

Datatype: enum

Default: strict

Options:

• strict - Requires strict checks.
• lenient - Allows lenient checks.

Tip

Keep all host modes aligned to simplify troubleshooting and reduce drift.

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).