# Docs

Configure documentation generation for READMEs, release notes, and other artifacts. Define multiple named documentation generators that can be invoked via `atmos docs generate <name>`.

## Configuration

Documentation generation is configured in the `docs.generate` section:

**File:** `atmos.yaml`

```yaml
docs:
  generate:
    readme:
      base-dir: .
      input:
        - "./README.yaml"
      template: "https://raw.githubusercontent.com/cloudposse/terraform-null-label/main/README.md.gotmpl"
      output: "./README.md"
      terraform:
        source: src/
        enabled: false
        format: "markdown"
        show_providers: false
        show_inputs: true
        show_outputs: true
        sort_by: "name"
        hide_empty: false
        indent_level: 2

    release-notes:
      base-dir: .
      input:
        - "./CHANGELOG.yaml"
      template: "./release-notes.gotmpl"
      output: "./RELEASE_NOTES.md"
```

## Configuration Options

Each named section under `docs.generate` supports the following options:

- **`base-dir`** — Base directory for resolving relative paths. Defaults to current working directory.
- **`input`** — List of YAML input files to combine. Supports local paths and remote URLs via go-getter.
- **`template`** — Path or URL to the Go template file used to generate the output.
- **`output`** — Path where the generated documentation will be written.
- **`terraform`** — Optional terraform-docs configuration for including Terraform documentation in the output.

### Terraform Documentation Options

When `terraform` is configured, Atmos can include Terraform module documentation in your generated files:

- **`terraform.source`** — Path to the Terraform module source directory, absolute or relative to `base-dir`.
- **`terraform.enabled`** — Whether to generate Terraform documentation. Default: `false`.
- **`terraform.format`** — Output format for Terraform docs. Options: `markdown`, `markdown table`, `tfvars hcl`, `tfvars json`. Default: `markdown table`.
- **`terraform.show_providers`** — Include provider information in the output. Default: `false`.
- **`terraform.show_inputs`** — Include input variables in the output. Default: `true`.
- **`terraform.show_outputs`** — Include outputs in the output. Default: `true`.
- **`terraform.sort_by`** — How to sort inputs/outputs. Options: `name`, `required`, `type`. Default: `name`.
- **`terraform.hide_empty`** — Hide sections with no content. Default: `false`.
- **`terraform.indent_level`** — Markdown heading level. Default: `2`.

Native templates can access the parsed module with the
[`terraform` function](/cli/commands/docs/generate#custom-terraform-formatting).
Its objects remain complete even when the formatted `terraform_docs` string hides
sections. Display defaults above describe the built-in `readme` generator; other
generator names retain terraform-docs section defaults when these options are omitted.

Visibility, `hide_empty`, and `indent_level` settings are honored for unpinned
projects and editions on or after `2026-10-17`. Earlier edition pins retain the
legacy formatter behavior, which ignored these settings.

## Multiple Documentation Generators

You can define as many documentation generators as needed. Each top-level key under `docs.generate` becomes a CLI argument:

**File:** `atmos.yaml`

```yaml
docs:
  generate:
    # Generate project README
    readme:
      input:
        - "./README.yaml"
      template: "./templates/README.md.gotmpl"
      output: "./README.md"

    # Generate release notes
    release-notes:
      input:
        - "./CHANGELOG.yaml"
      template: "./templates/release-notes.gotmpl"
      output: "./RELEASE_NOTES.md"

    # Generate component documentation
    component-docs:
      input:
        - "./docs/components.yaml"
      template: "./templates/components.md.gotmpl"
      output: "./docs/COMPONENTS.md"
```

Then invoke each generator by name:

```bash
atmos docs generate readme
atmos docs generate release-notes
atmos docs generate component-docs
```

## Template Example

Templates use Go templating with Gomplate functions:

**File:** `templates/README.md.gotmpl`

```
{{- $data := (ds "config") -}}

# {{ $data.name | default "Project Title" }}

{{ $data.description | default "No description provided." }}

{{ if has $data "extra_info" }}
## Additional Information

{{ $data.extra_info }}
{{ end }}

{{ if has $data "terraform_docs" }}
## Terraform Documentation

{{ $data.terraform_docs }}
{{ end }}
```

## Input File Sources

### Local Sources

Supports absolute paths, relative paths, and paths relative to `base-dir`:

```yaml
docs:
  generate:
    readme:
      input:
        # Absolute path
        - "/Users/me/Documents/README.yaml"
        # Relative to current directory
        - "./README.yaml"
        # Relative to base-dir
        - "terraform/README.yaml"
```

### Remote Sources

Atmos uses [go-getter](https://github.com/hashicorp/go-getter) for downloading remote files:

```yaml
docs:
  generate:
    readme:
      input:
        - "https://raw.githubusercontent.com/org/repo/main/README.yaml"
      template: "https://raw.githubusercontent.com/org/repo/main/README.md.gotmpl"
```

## Related Commands

- [`atmos docs generate`](/cli/commands/docs/generate) — Generate documentation artifacts
- [`atmos docs`](/cli/commands/docs/usage) — Open Atmos documentation