terraform-docs markdown: Generate Module Docs
terraform-docs markdown reads a Terraform module and prints a Markdown table of its inputs, outputs, providers, and resources.
Hand-written variable tables drift the moment someone adds a variable. terraform-docs derives them from the .tf files, so the docs always match the code.
What it does
terraform-docs parses the .tf files in a module directory and renders documentation. The markdown subcommand has two layouts: markdown table (the default, columnar) and markdown document (prose with headings). Output goes to stdout unless you write it into a file.
Common usage
# table layout to stdout
terraform-docs markdown table .
# document layout
terraform-docs markdown document ./modules/vpc
# write straight to a file
terraform-docs markdown table . > docs/INPUTS.mdOptions
| Flag | What it does |
|---|---|
| markdown table | document | Choose the columnar or prose layout |
| --output-file <file> | Write into a file (used with injection) |
| --sort-by <key> | name, required, or type ordering |
| --hide <section> | Omit a section, e.g. providers or requirements |
| --show <section> | Show only the named sections |
In CI
Run terraform-docs in a docs lint stage and fail if the generated output differs from what is committed, the same pattern as a fmt check. terraform-docs reads only static .tf files, so it needs no providers, backends, or cloud credentials and runs in milliseconds.
Common errors in CI
"No Terraform configuration found" means the path has no .tf files or points at the wrong directory. "unknown command" for markdown table means an old v0.9 style invocation on a newer binary or vice versa; align the command form with the installed version. Empty output usually means the module has no variables or outputs yet.