terraform-docs — Auto-Generate Documentation for Terraform Modules

Introduction

terraform-docs is a CLI utility that generates documentation from Terraform modules automatically. It parses .tf files to extract variables, outputs, providers, and resources, then renders them as Markdown tables, AsciiDoc, JSON, or other formats. This keeps module documentation accurate and in sync with code.

What terraform-docs Does

• Parses Terraform HCL files to extract inputs, outputs, providers, and resources
• Generates formatted documentation in Markdown, AsciiDoc, JSON, TOML, XML, or YAML
• Injects generated content between markers in existing README files
• Supports configuration via .terraform-docs.yml for consistent team-wide output
• Runs as a pre-commit hook to keep docs updated on every commit

Architecture Overview

terraform-docs is a standalone Go binary that uses the HCL parser to read .tf files in a given directory. It builds an internal model of all declared variables (with types, defaults, and descriptions), outputs, required providers, and resource blocks. A template engine then renders this model into the chosen output format. No Terraform binary or state file is needed.

Self-Hosting & Configuration

• Install via Homebrew, Chocolatey, or download pre-built binaries from GitHub releases
• Create .terraform-docs.yml in your module root to configure output format and sorting
• Use --output-mode inject to update content between <!-- BEGIN_TF_DOCS --> and <!-- END_TF_DOCS --> markers
• Integrate with pre-commit using the official terraform-docs-hook repository
• Run in CI to verify documentation is up to date with terraform-docs --output-check

Key Features

• Zero-dependency Go binary that requires no Terraform installation
• Multiple output formats including Markdown table, Markdown document, AsciiDoc, and JSON
• In-place injection mode that updates sections of existing documentation files
• Configurable sorting, escaping, and section ordering via YAML config
• Pre-commit hook integration for automatic doc updates before every commit

Comparison with Similar Tools

• terraform fmt — formats HCL code style; terraform-docs generates human-readable documentation
• tfdoc — older documentation generator with fewer output formats; terraform-docs is more actively maintained
• Terraform Registry — auto-renders module docs on registry.terraform.io; terraform-docs works locally and in any CI pipeline
• inframap — generates visual infrastructure diagrams; terraform-docs produces text-based reference documentation
• Rover — interactive Terraform state visualizer; terraform-docs focuses on module input/output documentation

FAQ

Q: Does terraform-docs need Terraform installed? A: No. terraform-docs parses HCL files directly and does not require the Terraform binary or any providers.

Q: How do I keep README docs in sync automatically? A: Use the pre-commit hook or add a CI step that runs terraform-docs --output-check to fail the build if documentation is outdated.

Q: Can terraform-docs handle multiple modules in a monorepo? A: Yes. Run terraform-docs against each module directory separately, or use a script to iterate over all module paths.

Q: Does it support Terraform 1.x and OpenTofu? A: Yes. terraform-docs parses standard HCL syntax and works with both Terraform and OpenTofu module files.

Sources

• https://github.com/terraform-docs/terraform-docs
• https://terraform-docs.io/