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

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

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.

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

		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

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

		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.