# atmos docs generate

Use this command to generate one of your documentation artifacts (e.g. a README) as defined by the **named** section under `docs.generate.<KEY>` in `atmos.yaml`.

Replace `<KEY>` with the name of the section you want to run (for example, `readme`, `release-notes`, etc.).

In `atmos.yaml`, you can define **one or more** documentation‐generation blocks under `docs.generate`.  Each top‐level key becomes a CLI argument:

```yaml
docs:
  generate:
    readme:
      base-dir: .
      input:
        - "./README.yaml"
      template: "https://.../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"
```

For each CLI argument the command combines all local or remote YAML files specified at `input` and template file then generates the documentation artifact at the respective `output` folder. In case the template contains `terraform_docs` key, e.g.

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

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

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

{{ if has $data "extra_info" }}
Extra info: {{ $data.extra_info }}
{{ end }}

{{ if has $data "terraform_docs" }}
## Terraform Docs
{{ $data.terraform_docs }}
{{ end }}

```

the resultant file will also have a corresponding section rendered. By default `terraform.format` is set to `markdown table`, and can also be `markdown`, `tfvars hcl`, and `tfvars json`.

## Custom Terraform formatting

Use the `terraform` template function to format Terraform documentation yourself.
It returns the native parsed terraform-docs module, preserving fields and methods
such as `.Type.Raw`, `.Description.Raw`, `.GetValue`, and `.Position.Filename`.
The module is loaded once per document and is also used to generate the existing
`terraform_docs` string.

The `terraform` function requires a version of Atmos containing this feature.
Atmos 1.232.0 and earlier cannot parse templates that call it, even inside
`{{ with terraform }}` or with Terraform generation disabled. Upgrade the Atmos
version pinned by your repository before adopting a native template. The guard
handles a missing module in a supported version; it does not provide backward
compatibility with an undefined function. Older pins can continue using
`{{ (ds "config").terraform_docs }}`.

Configure your template and enable Terraform documentation:

```yaml
docs:
  generate:
    readme:
      base-dir: .
      input:
        - "./README.yaml"
      template: "./README.md.gomplate"
      output: "./README.md"
      terraform:
        enabled: true
        source: .
        sort_by: name
```

In `README.md.gomplate`:

```gotemplate
{{- $data := ds "config" -}}
# {{ $data.name }}

{{ $data.description }}

{{ with terraform }}
## Required Variables
{{ range .RequiredInputs }}
### `{{ .Name }}`

{{ .Description.Raw }}

Type: `{{ .Type.Raw }}`
{{ end }}

## Optional Variables
{{ range .OptionalInputs }}
### `{{ .Name }}`

{{ .Description.Raw }}

Type: `{{ .Type.Raw }}`

Default: `{{ .GetValue }}`
{{ end }}
{{ end }}
```

You can also iterate directly with `{{ range (terraform).Inputs }}` when a module
is available. Use `{{ with terraform }}` to handle disabled Terraform generation
or a missing configured source directory: the function returns `nil` in those
cases. An empty module returns an object with empty collections. Invalid Terraform
or template errors fail generation.

| Module field | Available data |
| --- | --- |
| `.Inputs`, `.RequiredInputs`, `.OptionalInputs` | Names, types, descriptions, defaults, required status, and source positions; `.GetValue` and `.HasDefault` methods |
| `.Outputs` | Names, descriptions, sensitivity, and source positions; state values are not loaded |
| `.Providers`, `.Requirements` | Provider and version requirement information |
| `.ModuleCalls` | Module names, sources, versions, descriptions, and source positions |
| `.Resources` | Managed resources and data sources; `.GetMode`, `.Spec`, `.URL`, and source positions |
| `.Header`, `.Footer` | Header and footer text loaded by terraform-docs |

For `terraform_docs`, explicit `show_providers`, `show_inputs`, and `show_outputs`
settings control visibility, `hide_empty` omits empty sections, and `indent_level`
sets the Markdown heading level (default `2`). Omitted display settings retain
the formatter defaults. The built-in `readme` configuration defaults to hiding
providers and showing inputs and outputs; other generator names inherit the
formatter's visible sections unless configured otherwise.

Projects with an `edition` pin before `2026-10-17` retain the previous behavior,
which ignored visibility, empty-section, and heading-level settings. Unpinned
projects and pins on or after that date honor them. Sorting works in both paths.

The native module retains all parsed sections regardless of the formatter's
section-display settings. Your template controls grouping, visibility, escaping,
and layout. The `sort_by` setting determines the module's input ordering.

The `terraform` function is available only during `atmos docs generate` rendering.
Its native objects are separate from `ds "config"`, which continues to provide
merged YAML metadata and the formatted `terraform_docs` string. Existing templates
can keep using `{{ (ds "config").terraform_docs }}` unchanged. Both `.gomplate`
and `.gotmpl` filenames work; the configured filename has no required extension.

For a complete example with required, optional, and context-variable sections,
definition lists, badges, and collapsible details, see the
[README template fixture](https://github.com/cloudposse/atmos/tree/main/tests/fixtures/scenarios/docs-generate/native-terraform),
adapted from the original Cloud Posse component README design.

## Dynamic Keys

If you add a new key under docs.generate—say readme2 or release-notes —you simply pass that key to the CLI:

```shell
atmos docs generate readme2
atmos docs generate release-notes
```

## Usage

```shell
atmos docs generate readme
```

## Supported Sources for README.yaml and template

### Local Sources

It supports the following local file sources:

- Absolute paths

  ```yaml
  docs:
    generate:
      readme:
        input:
          - "/Users/me/Documents/README.yaml"
        template: "/Users/me/Documents/README.md.gotmpl"
  ```

- Paths relative to the current working directory

  ```yaml
  docs:
    generate:
      readme:
        input:
          - "./README.yaml"
        template: "./README.md.gotmpl"
  ```

- Paths relative to the `base_dir` defined in `atmos.yaml` CLI config file (then resolved as relative to cwd)

  ```yaml
  docs:
    generate:
      readme:
        input:
          - "terraform/README.yaml"
        template: "terraform/README.md.gotmpl"
  ```

### Remote Sources

To download remote files, Atmos uses [`go-getter`](https://github.com/hashicorp/go-getter)
(used by [Terraform](https://www.terraform.io/) for downloading modules)

## Examples

```shell
# Generate the README
atmos docs generate readme

# Generate it without running any hooks
atmos docs generate readme --skip-hooks

# Skip one hook by name
atmos docs generate readme --skip-hooks=publish-wiki
```

## Arguments

- **`<KEY>`** — The name of a section under `docs.generate` in `atmos.yaml`, such as `readme` or `release-notes`.

## Flags

- **`--skip-hooks`** — Skip all lifecycle hooks for this run, or pass `--skip-hooks=<name>[,<name>]` to skip specific hooks by name. Also available as the `ATMOS_SKIP_HOOKS` environment variable. Hooks that a governing [policy](/policies/hooks) marks `required` cannot be skipped.

## Hooks

Generated documentation often needs to go somewhere else: a wiki, a documentation portal, a
bucket, a chat channel. Declare `hooks` under the generator that produces the document and Atmos
runs them around generation, using the same [hook kinds and fields](/stacks/hooks) as component
hooks. The events are `before.docs.generate` and `after.docs.generate`.

```yaml
docs:
  generate:
    readme:
      input:
        - "./README.yaml"
      template: "./README.md.gotmpl"
      output: "./README.md"
      hooks:
        publish-wiki:
          kind: step
          type: http
          events: [after.docs.generate]
          when: success
          on_failure: fail
          with:
            url: "https://example.atlassian.net/wiki/rest/api/content/123456"
            method: PUT
            headers:
              Authorization: "Bearer {{ .env.WIKI_TOKEN }}"
              Content-Type: application/json
            body: '{"id": "123456", "type": "page", "title": "README", "version": {"number": 2}, "body": {"storage": {"value": "<p>Generated by Atmos</p>", "representation": "storage"}}}'
            expect:
              status: [200]
```

The example uses the generic [`http` step](/steps/type/http) against a wiki's REST API. Atmos has
no wiki-specific feature; any service that accepts an HTTP request works the same way. To send the
generated file's contents instead of fixed text, use a `kind: command` hook or a
[`script` step](/steps/type/script) that reads `ATMOS_DOCS_OUTPUT_PATH`.

### Ordering and failure

1. `before.docs.generate` hooks run first. A before-hook whose failure propagates (`on_failure: fail`, the default,
   or a policy denial) aborts the command before any file is written; with `on_failure: warn` or
   `ignore`, generation continues.
2. The document is generated.
3. `after.docs.generate` hooks run with the outcome. By default an after-hook runs only on success;
   set `when: failure` or `when: always` to run it on failure too. See
   [reacting to success or failure](/stacks/hooks#reacting-to-success-or-failure).
4. If generation succeeded and an after-hook fails, the command fails unless that hook sets
   `on_failure: warn` or `on_failure: ignore`.

A hook with no `events` list runs on both events. Hooks belong to one generator: hooks under
`readme` do not run for `release-notes`.

Within one event, hooks run in order of hook name. Hooks run in the process working directory (the
directory where `atmos docs generate` starts, or the `--chdir` target) rather than `base-dir`. Use
`ATMOS_DOCS_BASE_DIR` or `ATMOS_DOCS_OUTPUT_PATH` to reach the generator's files.

### Hook context

- **`ATMOS_DOCS_TYPE`** — The generator name, such as `readme`.
- **`ATMOS_DOCS_OUTPUT_PATH`** — The resolved path of the generated file.
- **`ATMOS_DOCS_BASE_DIR`** — The resolved base directory of the generator.

Step templates can use the same values as `{{ .docs.type }}`, `{{ .docs.output_path }}`, and
`{{ .docs.base_dir }}`. Documentation hooks have no infrastructure component or stack: the stack is empty, and
`ATMOS_COMPONENT` holds the generator name (for example `readme`).

### Policy

A governing policy with `on: operation` and `action: hooks` applies to documentation generation
too. The operation input has `component_type: docs`, `command: generate`, the generator name as
`component`, and no `stack`. See [Policy-Driven Hooks](/policies/hooks) and
[operation input](/policies/inputs#operation-input).
