terraform-docs: generating Terraform module documentation from HCL

The documentation drift problem terraform-docs targets

A Terraform module has a public surface: variables with types and defaults, outputs, required providers, and the resources it creates. All of that lives in .tf files. The README that explains it usually lives in a separate Markdown file, edited by hand. When someone adds a variable and forgets the README, the two diverge, and the next consumer of the module reads a table that is missing an entry.

terraform-docs closes that gap by generating the documentation from the module itself. The README describes it as "a utility to generate documentation from Terraform modules in various output formats." The audience is module authors and platform teams who publish modules to a registry or an internal catalog and want the reference tables to be accurate without manual upkeep. It is not aimed at people who want to document an entire Terraform configuration or explain architecture; it documents the module interface.

How terraform-docs reads a module and what each formatter emits

The tool parses the module directory and produces sections such as Requirements, Providers, Modules, Resources, Inputs and Outputs. The README lists these as the variables available inside a custom content template: {{ .Header }}, {{ .Footer }}, {{ .Inputs }}, {{ .Modules }}, {{ .Outputs }}, {{ .Providers }}, {{ .Requirements }} and {{ .Resources }}. Each variable holds the rendered output of that section in the chosen formatter, so {{ .Inputs }} in a markdown table run is the Markdown table of the module's variables.

The formatter is selected on the command line (markdown table, asciidoc, and others) and the repository layout confirms the split: there is a format/ directory for formatters and a print/ directory for output handling. Custom content templates work only with asciidoc and markdown; the README states that content is ignored for other formatters. Configuration is read from a YAML file named .terraform-docs.yml, searched in the module root, a .config/ folder there, the current directory, a .config/ folder there, and finally $HOME/.tfdocs.d/. The config exposes keys such as formatter, header-from, footer-from, recursive, sections, content, output, output-values, sort and a settings block with flags like anchor, default, required, sensitive and type. That settings block is where you decide whether default values, the required marker and sensitive flags appear in the tables.

Install terraform-docs and inject a table into a README

The README gives platform-specific install paths. On macOS, Homebrew:

brew install terraform-docs

On Windows, either Scoop or Chocolatey:

scoop bucket add terraform-docs https://github.com/terraform-docs/scoop-bucket
scoop install terraform-docs
choco install terraform-docs

If you have Go, the module path is used directly. The README notes go1.16 is the minimum and recommends the latest Go:

go install github.com/terraform-docs/[email protected]

For a first real use, run the binary against a module directory and write into an existing README. The README's own example is:

terraform-docs markdown table --output-file README.md --output-mode inject /path/to/module

With inject mode, the generated content replaces whatever sits between the BEGIN_TF_DOCS and END_TF_DOCS markers defined by output.template. The default template in the README is:

output:
  file: ""
  mode: inject
  template: |-
    <!-- BEGIN_TF_DOCS -->
    {{ .Content }}
    <!-- END_TF_DOCS -->

So a README that already contains those two comment lines keeps its prose and gets a refreshed table between them. If the markers are absent, there is nothing to inject into. To inspect the output before committing to a file, drop --output-file and read the result on stdout.

The container route avoids installing anything locally. The README mounts the working directory and passes the module path:

docker run --rm --volume "$(pwd):/terraform-docs" -u $(id -u) quay.io/terraform-docs/terraform-docs:0.24.0 markdown /terraform-docs

If output.file is not enabled, the README shows redirecting stdout to a file with > doc.md. The image tags are worth noting: latest tracks the latest stable release and edge tracks the head of master.

Where terraform-docs stops being the right tool

The generator only knows what the HCL declares. A variable with a description field of "the region" produces a table row saying "the region" and nothing more. If your module needs to explain why a default was chosen, which IAM permissions the caller must already hold, or the order in which resources must be created, terraform-docs will not write that for you. It renders structure, not reasoning.

There is a second boundary around values. The output-values feature reads a JSON file of applied values (examples/output_values.json in the repository shows the shape), and it is disabled by default. Enabling it means your documentation reflects one particular apply, which may not match what another caller sees. The sensitive setting controls whether sensitive variables are flagged in the table; it does not redact anything, because the tool is working from declarations rather than state.

The README also does not document rollback. If you run inject mode and the generated section is wrong, the previous content between the markers is gone unless you have the file under version control. There is no dry-run flag described in the README, so the safe pattern is to commit the README first, or read stdout before writing.

terraform-docs compared with terraform-config-inspect

The go.mod file shows terraform-docs depends on github.com/terraform-docs/terraform-config-inspect, which is the library that does the HCL parsing. That library is itself usable on its own and is the closer alternative for anyone who wants structured module metadata rather than rendered documents. The difference in approach is output versus data: terraform-config-inspect returns the module's variables, outputs and requirements as Go structures you consume in your own program, while terraform-docs takes that same information and renders it into Markdown, AsciiDoc, JSON or another format through a formatter. If your goal is a README table, terraform-docs is the shorter path. If your goal is a custom internal portal, a policy check, or a catalog that ingests module metadata, going to the inspect library directly avoids parsing rendered Markdown back into data.

Maintenance, licence and upgrade cost

The repository is not archived and the last push was on 2026-09-02. The release cadence visible in the repository is v0.22.0 on 2026-04-07, v0.23.0 on 2026-05-06 and v0.24.0 on 2026-05-10, so the project is still moving, but the version numbers are pre-1.0 and the README's own examples pin a version (v0.24.0) rather than tracking a floating tag. That pinning is the upgrade cost in practice: your pre-commit hook config, your GitHub Actions workflow and your Docker image tag each name a version, and upgrading means changing all three in step. The pre-commit example in the README pins rev: "v0.24.0".

The licence is MIT, declared in the LICENSE file at the repository root and repeated in the Makefile's LICENSE variable and in the header comments of the Dockerfile. MIT is permissive, so redistributing the binary or embedding the tool in an internal pipeline carries few obligations beyond keeping the copyright notice. That is a summary of what the repository states, not legal advice; if you vendor the code or ship it inside a product, have counsel read the actual LICENSE text.

Editorial conclusion

Adopt terraform-docs if you publish Terraform modules and want their variable and output tables generated from the .tf source rather than hand-edited. Skip it if your modules are private one-offs that nobody reads, or if you need prose documentation that explains design decisions, because the tool only renders what the HCL declares. Before rolling it out, run terraform-docs markdown table on one module and check that the generated table matches your expectations for defaults, required flags and sensitive values, then decide whether the inject mode markers belong in your README.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. terraform-docs/terraform-docs on GitHub