Writing supplemental content

Supplemental files let you enrich any auto-generated CLI reference page with context, usage examples, and richer parameter descriptions without touching the schema. The generated parameter table, usage synopsis, and examples from the schema are always present; supplemental content adds to them.

Files are discovered automatically. Drop a file into the supplemental folder following the naming convention and it is picked up on the next build with no configuration needed.

Validation is strict. Any supplemental file whose name does not match a known namespace or command produces a build error, so renamed or removed commands can never leave orphaned docs behind silently.

Two naming styles are supported and can coexist in the same folder.

Hierarchy style mirrors the CLI namespace structure:

cli/
  assembler/
    index.md              ← assembler namespace
    cmd-build.md          ← assembler build command
    deploy/
      cmd-apply.md        ← assembler deploy apply command
  cmd-assemble.md         ← root-level assemble command
		

Flat prefix style places all files at the folder root with the full path encoded in the name:

cli/
  ns-assembler.md             ← assembler namespace
  cmd-assembler-build.md      ← assembler build command
  cmd-assembler-deploy-apply.md
		

The heading structure of a supplemental file controls what it contributes to the generated page.

A file with no ## headings replaces the auto-generated description entirely:

Clones all repositories listed in the assembler configuration.
Defaults to `$(pwd)/.artifacts/checkouts/{content_source}`.
		

A ## Description section replaces the auto-generated description while allowing other sections in the same file:

## Description

:::{note}
This command requires that you've previously run `docs-builder assembler clone`.
:::

Builds all documentation sets into a complete site ready to be deployed.

## Usage examples

...
		

Any ## heading other than Description, Options, or Arguments is appended verbatim after the generated parameter table. Use this for usage walkthroughs, worked examples, or background context that belongs after the reference material.

Add a ## Options section to replace the generated description for specific flags. Each entry starts with : --flag-name (or with backtick-wrapped : `--flag-name`) followed by the replacement text:

## Options

: `--environment`
  The environment to target. Must match the environment used when cloning.
  See [environments](../configure/site/environments.md) for available values.

: `--exporters`
  Comma-separated list of exporters to enable.
  Defaults to `html,llm,config,links,state,redirect`.
		

Only the flags you list are overridden; all other parameters keep their schema descriptions.

Flag names are validated at build time. If a flag does not exist in the schema for that command, the build emits an error.

Add a ## Arguments section to replace the generated description for positional arguments. Each entry starts with : <arg-name> followed by the replacement text:

## Arguments

: `<repository>`
  The name of the `elastic/<repository>` repository to match against configured content sources.

: `<branch>`
  The branch or tag to check. Follows semantic versioning for speculative build detection.
		

Argument names are validated the same way as flag names. An unknown name is a build error.