What is terraform-docs and why match its format?

terraform-docs is a tool that auto-generates module documentation from the source. Matching its conventional layout — Requirements, Providers, Inputs, Outputs tables — makes your README familiar to Terraform users and ready for the public or private registry.

Why mark inputs as required or optional?

A variable with no default is required and must be passed by callers; one with a default is optional. The README shows n/a as the default for required inputs and yes/no in the Required column, so users immediately know what they must supply.

What version constraints should I document?

List the minimum Terraform core version and each provider's version constraint, for example >= 1.3.0 and >= 5.0. These tell consumers what tooling they need and prevent surprises from breaking changes in newer releases.

How is the usage example generated?

The builder emits a module block referencing your source and pre-fills every required input with a placeholder value typed appropriately — a number for numeric inputs and a quoted string otherwise — so callers have a working starting point.

Can I publish this to the Terraform Registry?

Yes. The Terraform Registry renders the module README on its page. A clear description, version requirements, input and output tables, and a usage example are exactly what the registry and other engineers expect.

What is the Terraform Module README Builder?

Generate a README.md for a Terraform module in the terraform-docs style — description, requirements, providers, an inputs table, an outputs table, and a ready-to-paste usage example. It runs free in your browser on Gera Tools, with nothing uploaded.

Terraform Module README Builder

Name: Terraform Module README Builder
Creator: Gera Tools
License: https://creativecommons.org/licenses/by/4.0/

Document your Terraform module in seconds

A good module README is the difference between a reusable component and a black box. This builder produces a README in the well-known terraform-docs layout — description, requirements, providers, inputs and outputs tables, and a copy-paste usage example — so consumers know exactly how to call your module.

How it works

The generator renders standard GitHub-flavoured Markdown tables. The Inputs table lists each variable’s name, description, type, default, and whether it is required. A variable without a default is treated as required and shows n/a; an optional variable shows its default in backticks. The Outputs table pairs each output name with its description.

Cell values are escaped so a literal pipe character in a description does not break the table layout, and newlines are flattened to spaces. The Usage section emits a module block referencing your source and pre-fills only the required inputs with type-appropriate placeholders — numeric inputs get 1, everything else gets a quoted string.

What a complete module README contains

A well-structured module README follows this section order:

Title and description — one paragraph explaining what the module does and why someone would use it.
Requirements — minimum Terraform core version and any provider version constraints.
Providers — the provider(s) the module uses and the version it was tested against.
Inputs table — every variable block, with name, description, type, default, and required status.
Outputs table — every output block, with name and description.
Usage example — a module block callers can copy and adapt.

This builder generates sections 1–6. If your module has optional resource counts, backend configuration, or examples for multiple deployment patterns, add those manually after generating the scaffold.

Marking required vs optional inputs

Terraform variables are required when they have no default value and optional when they do. The inputs table communicates this with two columns:

Default — shows the default value in backticks for optional inputs, or n/a for required ones.
Required — yes for variables callers must supply, no for those with defaults.

Be explicit in descriptions about what format a required variable expects — for example, “The AWS region to deploy into (e.g. us-east-1)” is more useful than “AWS region.”

Using this with terraform-docs

terraform-docs is the de-facto CLI for auto-generating module documentation from source files. It reads your variables.tf and outputs.tf directly and can inject the tables into a README via a comment marker, keeping documentation in sync with code automatically.

Use this builder for the initial scaffold or for hand-authored modules not tracked in a repo. For modules in active development, wire terraform-docs markdown . into your pre-commit hooks or CI so the README never drifts.

Tips and notes

Keep descriptions to a single clear sentence — they render in one table row.
Document version constraints honestly: the lowest Terraform and provider versions you have actually tested against.
Outputs are how other modules and root configurations consume yours, so describe each output’s meaning and units, not just its name.
Pipe characters in descriptions must be escaped to \| — the builder handles this automatically.