1.6.3.1. What is terraform-docs: Why and How to Use It

Users of Terraform modules need to read documentation on the Registry to understand a module's purpose, usage, and specifications for all parameters. As teams and organizations scale, the number and complexity of Terraform modules often increase dramatically, making documentation maintenance a critical bottleneck constraining collaboration, review, and delivery efficiency. terraform-docs, a tool focused on automating Terraform module documentation generation, was created specifically to address this pain point.

1.6.3.1.1. What is terraform-docs

terraform-docs is a utility tool that automatically generates documentation from Terraform modules and supports multiple output formats. It parses metadata within a module—such as variables (variable), outputs (output), resources (resource), and providers—and organizes them into a structured, standardized output. This significantly reduces the workload and error probability associated with manual documentation maintenance.

Official Definition: A utility to generate documentation from Terraform modules in various output formats.

——terraform-docs README

It can run as a standalone command-line tool or be integrated into CI/CD pipelines via Docker containers, GitHub Actions, and pre-commit hooks.

1.6.3.1.2. Why Use terraform-docs

1.6.3.1.2.1. Automate Documentation to Enhance Development Efficiency

Manual maintenance of Terraform module documentation is labor-intensive and error-prone. With frequent changes to variables and outputs, documentation easily disconnects from the actual code. terraform-docs automatically parses the latest module definitions and generates authoritative documentation, maximizing consistency between code and docs.

1.6.3.1.2.2. Reduce Communication Costs and Improve Collaboration Transparency

A standardized documentation structure allows team members, reviewers, and even external users to quickly understand a module's interfaces, inputs, outputs, and dependencies. This drastically improves the efficiency of code reviews, reuse, and module governance.

1.6.3.1.2.3. Support Multiple Output Formats to Flexibly Adapt to Team Needs

terraform-docs supports various formats including Markdown, JSON, YAML, and Asciidoc, allowing for easy integration into various knowledge bases, portals, automated checks, or downstream toolchains.

1.6.3.1.2.4. Easy CI/CD Integration to Ensure Continuous Updates

Through mechanisms like GitHub Actions and pre-commit hooks, documentation generation and validation can be automated. This "shifts left" the maintenance of documentation to the development and commit stages, preventing omissions and outdated information.

1.6.3.1.3. How to Install terraform-docs

terraform-docs supports multiple mainstream platforms with flexible installation methods:

1.6.3.1.3.1. Using Homebrew (macOS)

brew install terraform-docs
# or use tap
brew install terraform-docs/tap/terraform-docs

1.6.3.1.3.2. Using Scoop/Chocolatey (Windows)

scoop bucket add terraform-docs [https://github.com/terraform-docs/scoop-bucket](https://github.com/terraform-docs/scoop-bucket)
scoop install terraform-docs

# or
choco install terraform-docs

1.6.3.1.3.3. Download Binary

Download the binary for your platform from the releases page, unzip it, and add it to your $PATH.

1.6.3.1.3.4. Using go install (Recommended for Go users)

go install github.com/terraform-docs/terraform-docs@latest

1.6.3.1.3.5. Using Docker

No local installation required; use the official image directly:

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

1.6.3.1.4. How to Use terraform-docs

1.6.3.1.4.1. Basic Usage

The simplest usage is to run the following command in the Terraform module directory:

terraform-docs markdown .

This reads the .tf files in the current directory and prints the module documentation in Markdown format to the standard output.

Supported output formats include:

• asciidoc (document/table)
• markdown (document/table)
• json
• pretty
• tfvars (hcl / json)
• toml
• xml
• yaml

For example, to generate JSON documentation:

terraform-docs json .

1.6.3.1.4.2. Integration into CI/CD and Development Workflows

GitHub Actions

You can use the official terraform-docs GitHub Action to automatically generate and validate module documentation in Pull Requests.

pre-commit hook

By configuring pre-commit, you can automatically update documentation locally before committing, reducing the risk of missed updates.

Docker

As shown above, this is suitable for scenarios requiring no local installation, cross-platform compatibility, and CI environments.

1.6.3.1.4.3. Advanced Configuration: Custom Templates and YAML Configuration

terraform-docs supports rich customization via a .terraform-docs.yml file. Typical configuration items include:

• Documentation structure templates (e.g., header, footer, section visibility)
• Recursive documentation generation for sub-modules
• Documentation sorting rules
• Output files and modes (e.g., inject into a specific location in README.md)

A basic YAML configuration example:

formatter: "" # this is required

version: ""

header-from: main.tf
footer-from: ""

recursive:
  enabled: false
  path: modules
  include-main: true

sections:
  hide: []
  show: []

content: ""

output:
  file: ""
  mode: inject
  template: |-
    {{ .Content }}
    output-values:
  enabled: false
  from: ""

sort:
  enabled: true
  by: name

settings:
  anchor: true
  color: true
  default: true
  description: false
  escape: true
  hide-empty: false
  html: true
  indent: 2
  lockfile: true
  read-comments: true
  required: true
  sensitive: true
  type: true

You can automatically inject the module interface documentation into a specific block of the README.md using: terraform-docs markdown table --output-file README.md --output-mode inject .

1.6.3.1.4.4. Content Customization and Template Variables

The terraform-docs template allows insertion of various parts of the module, such as:

• {{.Inputs}} Variable input table
• {{.Outputs}} Output table
• {{.Providers}} Provider information
• {{.Requirements}} Version constraints
• It even supports {{ include "path/to/file" }} to import external content

And functions like:

• {{ include "relative/path/to/file" }}

These variables represent the output of individual sections generated by the selected formatter. For example, when the formatter is set to markdown table, {{ .Inputs }} will be the Markdown table representation of inputs.

Note that section visibility parameters (i.e., sections.show and sections.hide) take precedence over the content configuration.

Additionally, there is a special variable in content:

• {{ .Module }}

Unlike other variables mentioned above, this variable does not generate a block based on the formatter but is the Terraform module struct itself.

content: |-
  You can place arbitrary text in content

  {{ .Header }}

  You can even insert it between different sections

  {{ .Providers }}

  The order does not have to follow the default order

  {{ .Outputs }}

  Can include content from any file via relative path

  {{ include "relative/path/to/file" }}

  {{ .Inputs }}

  # Example

  ```hcl
  {{ include "examples/foo/main.tf" }}
  ```

  ## Resources

  {{ range .Module.Resources }}
  - {{ .GetMode }}.{{ .Spec }} ({{ .Position.Filename }}#{{ .Position.Line }})
  {{- end }}

The template mechanism greatly enhances the customizability and aesthetics of the documentation.

1.6.3.1.4.5. Compatibility and Ecosystem

terraform-docs is compatible with mainstream Terraform versions and is well-maintained. The community is active, providing a detailed User Guide, CLI Reference, and Configuration Documentation.

1.6.3.1.5. Script for Generating Documentation

The Azure Verified Module uses the following script to invoke terraform-docs for documentation generation:

#!/usr/bin/env bash
set -e

generate_docs () {
  local dir=$1
  echo "===> Generating documentation in $dir"
  rm -f "$dir/.terraform.lock.hcl"
  terraform-docs -c ".terraform-docs.yml" "$dir"
}

echo "==> Generating root module documentation..."
generate_docs .

echo "==> Generating examples documentation..."
if [ ! -d examples ]; then
  echo "==> Error - no examples directory found"
  exit 1
fi
cd examples
subfolders=$(find ./ -maxdepth 1 -mindepth 1 -type d)
for d in $subfolders; do
  generate_docs $d
done
cd ..

echo "==> Generating sub modules documentation..."
if [ ! -d modules ]; then
  echo "==> Warning - no modules directory found"
else
  cd modules
  subfolders=$(find ./ -maxdepth 1 -mindepth 1 -type d)
  for d in $subfolders; do
    generate_docs $d
  done
  cd ..
fi

This script generates documentation for the module as well as all examples.

1.6.3.1.6. Script for Checking if Documentation is Up-to-Date

#!/usr/bin/env bash

check_docs () {
  local dir=$1
  echo "===> Generating documentation in $dir"
  cp "$dir/README.md" "$dir/README-generated.md"
  rm -f "$dir/.terraform.lock.hcl"
  terraform-docs -c ".terraform-docs.yml" "$dir"
  echo "===> Comparing documentation in $dir"
  if [ ! -z "$(diff -q "$dir/README.md" "$dir/README-generated.md")" ]; then
    echo "==> $dir/README.md is out of date. Run 'make pre-commit' to update the generated document and commit."
    mv -f "$dir/README-generated.md" "$dir/README.md"
    exit 1
  fi
  rm -f "$dir/README-generated.md"
}

echo "==> Checking root module documentation..."
check_docs .

echo "==> Checking examples documentation..."
if [ ! -d examples ]; then
  echo "==> Error - no examples directory found"
  exit 1
fi
cd examples
subfolders=$(find ./ -maxdepth 1 -mindepth 1 -type d)
for d in $subfolders; do
  check_docs $d
done
cd ..

echo "==> Checking sub modules documentation..."
if [ ! -d modules ]; then
  echo "==> Warning - no modules directory found"
else
  cd modules
  subfolders=$(find ./ -maxdepth 1 -mindepth 1 -type d)
  for d in $subfolders; do
  check_docs $d
  done
  cd ..
fi

This script attempts to generate documentation for the module and all examples but saves it to a README-generated.md file. It then checks if the documentation has been updated by comparing this file with the existing README.md. This script can be used in CI/CD pipelines to ensure that code changes include corresponding documentation updates.

1.6.3.1.7. Best Practices and Governance Recommendations

1. Combine pre-commit and PR checks to achieve documentation automation and standardization, ensuring docs always reflect the current module configuration.
2. Configure content templates to ensure a unified documentation structure across all modules, facilitating team knowledge transfer and module reuse.
3. Regularly upgrade terraform-docs to access better formatting support and new features.

For more detailed usage and best practices, please refer to the official documentation: terraform-docs.io.