Terraform Documentation Generator

This skill helps generate and maintain Terraform module documentation using terraform-docs.

When to Use

Use this skill when:

• Creating README.md for a new module

• Updating documentation after module changes

• Generating input/output reference tables automatically

• Ensuring consistent documentation across modules

Using terraform-docs

Installation

macOS

brew install terraform-docs

Linux

curl -sSLo ./terraform-docs.tar.gz https://terraform-docs.io/dl/latest/terraform-docs-linux-amd64.tar.gz tar -xzf terraform-docs.tar.gz chmod +x terraform-docs mv terraform-docs /usr/local/bin/

Or use Go

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

Basic Usage

Generate markdown documentation

terraform-docs markdown table . > README.md

Preview without writing

terraform-docs markdown table .

Generate for specific directory

terraform-docs markdown table ./modules/vpc > ./modules/vpc/README.md

Configuration File

Create .terraform-docs.yml in module root for consistent formatting:

formatter: "markdown table"

header-from: main.tf

sections: show: - header - requirements - providers - inputs - outputs - resources

content: |- {{ .Header }}

Usage

module "example" {
  source = "./modules/example"
  
  # Add your example here
}

{{ .Requirements }}
{{ .Providers }}
{{ .Inputs }}
{{ .Outputs }}
{{ .Resources }}

output:
file: "README.md"
mode: inject
template: |-

{{ .Content }}

sort:
enabled: true
by: required

### Auto-Generate Documentation

```bash
# With config file
terraform-docs .

# Inject into existing README between markers
terraform-docs markdown table --output-file README.md --output-mode inject .

Output Formats

# Markdown table (most common)
terraform-docs markdown table .

# Markdown document
terraform-docs markdown document .

# JSON
terraform-docs json .

# YAML
terraform-docs yaml .

Documentation Best Practices

Add Header Comments

Add description at top of main.tf:

/**
* # Terraform AWS VPC Module
*
* Creates a VPC with public and private subnets across multiple availability zones.
*
* ## Features
*
* - Multi-AZ VPC with public and private subnets
* - NAT Gateway for private subnet internet access
* - Configurable CIDR blocks
*/

resource "aws_vpc" "main" {
# ...
}

terraform-docs will use this as the README header.

Document Variables Clearly

variable "vpc_cidr" {
description = "CIDR block for VPC (e.g., 10.0.0.0/16)"
type        = string

validation {
  condition     = can(cidrhost(var.vpc_cidr, 0))
  error_message = "Must be valid IPv4 CIDR."
}
}

variable "enable_nat_gateway" {
description = "Enable NAT Gateway for private subnet internet access"
type        = bool
default     = true
}

Document Outputs

output "vpc_id" {
description = "ID of the VPC"
value       = aws_vpc.main.id
}

output "private_subnet_ids" {
description = "List of private subnet IDs for use with internal resources"
value       = aws_subnet.private[*].id
}

Workflow Integration

Pre-commit Hook

Add to .pre-commit-config.yaml
:

repos:
- repo: https://github.com/terraform-docs/terraform-docs
  rev: "v0.16.0"
  hooks:
    - id: terraform-docs-go
      args: ["markdown", "table", "--output-file", "README.md", "."]

CI/CD Integration

# GitHub Actions example
- name: Generate terraform docs
uses: terraform-docs/gh-actions@v1
with:
  working-dir: .
  output-file: README.md
  output-method: inject

Quick Reference

# Generate docs for current directory
terraform-docs markdown table . > README.md

# Update existing README (between markers)
terraform-docs markdown table --output-file README.md --output-mode inject .

# Generate for all modules
find . -type f -name "*.tf" -exec dirname {} \; | sort -u | xargs -I {} terraform-docs markdown table {} --output-file {}/README.md

# Validate documentation is up to date
terraform-docs markdown table . | diff - README.md

Documentation Checklist

-  terraform-docs installed

-  .terraform-docs.yml
config created (optional)

-  Header comment added to main.tf

-  All variables have clear descriptions

-  All outputs have descriptions

-  Usage example added to README

-  Documentation generated with terraform-docs

-  Pre-commit hook configured (optional)