Skip to main content

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:

atmos.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.
hooks
Optional map of lifecycle hooks that run around generation, on the before.docs.generate and after.docs.generate events. Hooks use the same kinds and fields as component hooks; see Hooks.

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

Hooks​

Declare hooks under a generator to run steps or commands before and after it generates, for example to publish the result to a wiki. Each hook has the same fields as a component hook, and its events must be before.docs.generate or after.docs.generate:

atmos.yaml
docs:
generate:
readme:
input:
- "./README.yaml"
template: "./README.md.gotmpl"
output: "./README.md"
hooks:
announce:
kind: step
type: log
events: [after.docs.generate]
with:
content: "Generated {{ .docs.output_path }}"

Hook steps receive ATMOS_DOCS_TYPE, ATMOS_DOCS_OUTPUT_PATH, and ATMOS_DOCS_BASE_DIR. See atmos docs generate for ordering, failure handling, an http step example, and policy support.

Multiple Documentation Generators​

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

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

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

Template Example​

Templates use Go templating with Gomplate functions:

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:

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 for downloading remote files:

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