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:

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.

{{- $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:

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:

{{- $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, 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:

atmos docs generate readme2
atmos docs generate release-notes

Usage

atmos docs generate --help

atmos docs generate readme

Supported Sources for README.yaml and template

Local Sources

It supports the following local file sources:

• Absolute paths

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

• Paths relative to the current working directory

  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)

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

Remote Sources

To download remote files, Atmos uses go-getter (used by Terraform for downloading modules)