name	terraform-documentation-generator
description	Generates documentation for Terraform modules using terraform-docs tool to auto-generate README files with input/output tables, usage examples, and requirements. This skill should be used when users need to document Terraform modules, create or update README files, or maintain consistent module documentation.

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
  
  ```hcl
  module "example" {
    source = "./modules/example"
    
    # Add your example here
  }

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)

terraform-documentation-generator

Install Skill

SKILL.md