Cheatterraform-docs Terraform module docs
Light · Postcard
102 × 152 mm · PDF
Dark · Postcard
102 × 152 mm · PDF
Ink saver · Postcard
102 × 152 mm · PDF
Light · A4 landscape
297 × 210 mm · PDF
Dark · A4 landscape
297 × 210 mm · PDF
Ink saver · A4 landscape
297 × 210 mm · PDF
Light · A3 landscape
420 × 297 mm · PDF
Dark · A3 landscape
420 × 297 mm · PDF
Ink saver · A3 landscape
420 × 297 mm · PDF
Start here
terraform-docs markdown table .
Print module docs
terraform-docs markdown table --output-file README.md
.
Update README
terraform-docs json .
Machine-readable output
terraform-docs pretty .
Coloured terminal view
terraform-docs -c .terraform-docs.yml .
Use a config file
terraform-docs --output-check .
Fail if docs stale
terraform-docs --recursive .
Also document submodules
terraform-docs version
Show version
Concepts
- Module .tf files variables, outputs
- terraform-docs format + sections
- Output stdout or file
- README.md between markers
Install
brew install terraform-docs
Install with Homebrew
go install
github.com/terraform-docs/terraform-docs@<version>
Install with Go
scoop install terraform-docs
Install on Windows (Scoop)
Run scoop bucket add terraform-docs
https://github.com/terraform-docs/scoop-bucket first.
choco install terraform-docs
Install on Windows (Chocolatey)
docker run --rm -v "$(pwd):/terraform-docs" -u $(id
-u) quay.io/terraform-docs/terraform-docs:<version>
markdown /terraform-docs
Run from the Docker image
terraform-docs version
Print installed version
Formats
terraform-docs markdown table <path>
Markdown with tables
terraform-docs markdown document <path>
Markdown with headings per item
terraform-docs asciidoc table <path>
AsciiDoc with tables
terraform-docs asciidoc document <path>
AsciiDoc with headings
terraform-docs json <path>
JSON for scripts
terraform-docs yaml <path>
YAML output
terraform-docs toml <path>
TOML output
terraform-docs xml <path>
XML output
terraform-docs pretty <path>
Readable terminal output
terraform-docs tfvars hcl <path>
Generate a terraform.tfvars template
terraform-docs tfvars json <path>
Generate tfvars as JSON
Sections
--show <section>
Show only the named section
Sections: header, inputs, outputs, providers, requirements,
resources, modules, data-sources, footer.
--hide <section>
Hide a section
--hide providers,footer
Hide several at once
--sort-by <name|required|type>
Sort inputs by this key
--sort=falseKeep declaration order
--header-from <file>
Read header text from a file
Default is main.tf; use a .md file for a longer intro.
--footer-from <file>
Read footer text from a file
--read-comments=false
Ignore comment-based descriptions
--lockfile=false
Skip .terraform.lock.hcl
Output to file
--output-file <file>
Write result into a file
--output-mode inject
Replace only the marked block
Content goes between the BEGIN_TF_DOCS and END_TF_DOCS
markers.
--output-mode replace
Overwrite the whole file
--output-template <tpl>
Wrap content in custom markers
--output-checkExit non-zero if file is out of date
Use in CI to enforce regenerated docs.
--output-valuesInclude real output values
--output-values-from <file>
Read values from terraform output -json
Submodules
--recursiveDocument submodules too
--recursive-path <dir>
Where submodules live (default modules)
--recursive-include-main=false
Skip the root module
--recursive-exclude <dir>
Skip a submodule directory
Config file
-c, --config <file>
Use a specific config file
Default is .terraform-docs.yml in the module directory.
formatter: "markdown table"
Choose format (only required key)
version: ">= 0.20, < 1.0"
Constrain terraform-docs version
header-from: main.tf
Header source file
sections: { show: [...], hide: [...] }
Pick visible sections
output: { file: README.md, mode: inject }
Where and how to write
recursive: { enabled: true, path: modules }
Enable submodule pass
sort: { enabled: true, by: name }
Sort order
settings: { anchor: false, required: false }
Tune table columns and anchors
content: "{{ .Header }}..."
Custom template for the body
Ignore blocks
# terraform-docs-ignore
Leading comment hides a block
Works on resource, data, module, variable and output blocks;
since v0.18.
Automation
repo:
https://github.com/terraform-docs/terraform-docs
pre-commit repo entry
id: terraform-docs-go
pre-commit hook id
id: terraform-docs-docker
pre-commit hook using Docker
uses: terraform-docs/gh-actions@main
GitHub Action step
Recipes
<!-- BEGIN_TF_DOCS --><!-- END_TF_DOCS --># the block between them is regeneratedformatter: "markdown table"output: file: README.md mode: injectsort: by: requiredrepos: - repo: https://github.com/terraform-docs/terraform-docs rev: "v0.24.0" hooks: - id: terraform-docs-go args: ["--output-file", "README.md", "./modules/vpc"]terraform-docs --output-check -c .terraform-docs.yml .# fails when README.md differs from the generated docs
