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.

Terraform Module README Builder

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

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.

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 consume yours, so describe each one’s meaning, not just its name.
Run terraform-docs in CI to keep the README in sync as variables change; use this builder for the initial scaffold or for modules you author by hand.