# terraform-docs — Auto-Generate Documentation for Terraform Modules

> terraform-docs reads your Terraform module source code and generates formatted documentation of inputs, outputs, providers, and resources in Markdown, JSON, or other formats.

## Install

Save in your project root:

# terraform-docs — Auto-Generate Documentation for Terraform Modules

## Quick Use
```bash
# Install
brew install terraform-docs

# Generate Markdown docs for a module
terraform-docs markdown table ./my-module

# Auto-inject into README between markers
terraform-docs markdown table --output-file README.md --output-mode inject ./my-module
```

## 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/

---
Source: https://tokrepo.com/en/workflows/804525f8-414b-11f1-9bc6-00163e2b0d79
Author: AI Open Source