---
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://www.elastic.co/elastic/docs-builder/docs/3491/reference/docs-builder/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

<definitions>
  <definition term=":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.deployment` block explicitly lists that deployment with a non-removed lifecycle. 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
    ::::
    ```
  </definition>
</definitions>


### 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
        #
        # Supports docs-builder applies_to syntax, for example:
        #
        # applies_to:
        #   stack: ga 9.2
        #   ech: ga
        #   self: 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 from the parent unless overridden.
        #   - setting: "[n].url"
        #     description: |
        #       REQUIRED
```


### 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`.
- `applies_to` inheritance and override behavior.
- Inline `{applies_to}` badges inside a setting `description` (for example, to label per-version defaults in a bulleted list).
- 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
```

<definitions>
  <definition term="xpack.example.enabled">
    <stack-availability>Elastic Stack: Generally available since 9.2</stack-availability>
    <supported-on>Elastic Cloud Hosted: Generally available</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.
</note>


<tip>
  Keep this enabled in production.
</tip>

  </definition>
  <definition term="xpack.example.mode">
    <stack-availability>Elastic Stack: Generally available since 9.2</stack-availability>
    <supported-on>Self-managed Elastic deployments: Generally available since 9.2</supported-on>

Controls runtime mode.
Datatype: `enum`
Default: `strict`
Options:
- `strict`: Full validation.
- `lenient`: Reduced validation.

<warning>
  Lenient mode may hide configuration mistakes.
</warning>


<important>
  Strict mode is recommended for production.
</important>


<admonition title="Deprecation details">
  The `lenient` option will be deprecated in a future release.
</admonition>


```yaml
xpack.example.mode: strict
```

  </definition>
  <definition term="xpack.example.defaultModel">

Default model used by the feature. The default varies by version:
- <applies-to>Elastic Stack: Generally available since 9.2</applies-to> Defaults to `model-v2`.
- <applies-to>Elastic Stack: Generally available since 9.1</applies-to> Defaults to `model-v1`.

Datatype: `string`
  </definition>
</definitions>

#### Advanced settings

These settings demonstrate nested entries and applies_to inheritance.
<definitions>
  <definition term="xpack.example.hosts">
    <stack-availability>Elastic Stack: Generally available since 9.2</stack-availability>
    <supported-on>Self-managed Elastic deployments: Generally available</supported-on>

List of custom host settings.
Datatype: `object`
Default: `[]`
  </definition>
  <definition term="xpack.example.hosts[n].url">
    <stack-availability>Elastic Stack: Generally available since 9.2</stack-availability>
    <supported-on>Self-managed Elastic deployments: Generally available</supported-on>

Child setting inherits applies_to from the parent.
Datatype: `string`
  </definition>
  <definition term="xpack.example.hosts[n].mode">
    <stack-availability>Elastic Stack: Preview since 9.3</stack-availability>
    <supported-on>Self-managed Elastic deployments: Preview since 9.3</supported-on>

Child setting overrides applies_to.
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.
</tip>


```yaml
xpack.example.hosts:
  - url: https://example.org
    mode: strict
```

  </definition>
</definitions>

For large Kibana-exported YAML samples used in local stress tests, see [Kibana settings YAML samples](https://www.elastic.co/elastic/docs-builder/docs/3491/reference/docs-builder/testing/kibana-settings-yaml-samples).