terraform-docs: Inject Docs Into README.md
terraform-docs injects generated documentation between BEGIN and END comment markers in an existing README so the rest of the file is untouched.
Instead of a separate docs file, most modules keep the inputs/outputs table inside README.md. terraform-docs replaces only the block between its markers, leaving your prose intact.
What it does
With --output-file README.md and --output-mode inject, terraform-docs finds the <!-- BEGIN_TF_DOCS --> and <!-- END_TF_DOCS --> comment markers and replaces whatever is between them with freshly generated content. --output-mode replace overwrites the whole file instead.
Common usage
# add the markers to README.md once:
# <!-- BEGIN_TF_DOCS -->
# <!-- END_TF_DOCS -->
terraform-docs markdown table --output-file README.md --output-mode inject .
# fail CI if injection would change the file
terraform-docs markdown table --output-file README.md --output-mode inject \
--output-check .Options
| Flag | What it does |
|---|---|
| --output-file <file> | File to write or inject into |
| --output-mode inject | Replace only the content between the markers |
| --output-mode replace | Overwrite the entire file |
| --output-check | Exit non-zero if the file would change (CI gate) |
| --output-template <tpl> | Customize the wrapper around the generated block |
In CI
Use --output-check as the gate: it regenerates in memory and fails if the committed README is stale, without modifying the working tree. A pre-commit hook running the same command keeps contributors from forgetting. The default markers are BEGIN_TF_DOCS / END_TF_DOCS unless you override the template.
Common errors in CI
"the file ... does not contain expected insert markers" means the BEGIN/END comments are missing or misspelled; add them exactly. --output-check exiting non-zero is the intended "docs are out of date" signal, not a crash; run the inject command and commit. "open README.md: no such file" means --output-file points at the wrong path.