terraform-docs: inject mode, five config paths, and its defaults
Generate documentation from Terraform modules in various output formats
At a glance
- What is it?
- terraform-docs turns a Terraform module into a table of inputs and outputs and puts it back into your README. It is a small Go binary with a fixed set of switches, and the surprises a new user hits come from configuration defaults rather than from the generator itself.
- Who is it for?
- terraform-docs earns a slot in any module repo that keeps generated tables in git, and it costs nothing when your modules are single directory and hand written. Before wiring it into a repo, check three things: whether your submodules live under a directory that recursive mode is pointed at, whether the formatter you want is one of the two that honour a content template, and whether the version string in your hook matches the binary your team installs.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- terraform-docs/terraform-docs4,841 ★ · +15
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| terraform-docs/terraform-docs | 4.8k | 4.8k |
15 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Inject mode rewrites the span between two comment markers
The shortest useful invocation names a formatter, points at a module directory and asks for the table to land back in the README:
terraform-docs markdown table --output-file README.md --output-mode inject /path/to/module`--output-file` picks the file, `--output-mode inject` says to rewrite a marked region instead of dumping text at the top, and the default `output` block supplies those markers:
output:
file: ""
mode: inject
template: |-
<!-- BEGIN_TF_DOCS -->
{{ .Content }}
<!-- END_TF_DOCS -->Run that first command on a branch and read the diff. The container recipe redirects output with `> doc.md` when `output.file` is not enabled for the module.
A config file in $HOME/.tfdocs.d/ reaches every module on the machine
The file is named `.terraform-docs.yml`, and the lookup runs through five places in order: the root of the module directory, a `.config/` folder in that root, the current directory, a `.config/` folder in the current directory, and finally `$HOME/.tfdocs.d/`. That last entry is the one that bites. A config file dropped there applies to modules you never configured, including repositories checked out under some other path or rendered by a script that changes directory between runs. The sample marks `formatter: ""` as the required entry, so a home directory file that does set a formatter can change tables for modules that have no config file earlier in the lookup order. When a colleague's table differs from yours and no config in the repo explains it, read `$HOME/.tfdocs.d/` before you start diffing individual keys.
Recursive walking ships switched off, so a modules directory is never opened
The default block reads:
recursive:
enabled: false
path: modules
include-main: trueWith `enabled: false`, a run over a module root sees the `.tf` files sitting next to it and stops there. A repository that keeps its submodules in a `modules/` directory therefore gets a table listing only the top level variables and outputs, and nothing in the generated output hints that deeper files went unread. Flipping `enabled` on and pointing `path` at the directory your repo actually uses is the whole fix; `include-main: true` keeps the root module in the listing while children are added underneath. When two repos in the same organisation produce different tables from similar modules, this flag is the first thing to compare, not the formatter.
A content template is honoured by two formatters and thrown away by the rest
`content` is a Go template that decides which sections appear and in what order, and an empty value falls back to the default order. The variables are `{{ .Header }}`, `{{ .Footer }}`, `{{ .Inputs }}`, `{{ .Modules }}`, `{{ .Outputs }}`, `{{ .Providers }}`, `{{ .Requirements }}` and `{{ .Resources }}`, plus an `include "relative/path/to/file"` function for pulling extra files into the layout. One variable is different: `{{ .Module }}` is a struct representing the module itself rather than a section rendered in the chosen formatter. Two conditions decide whether any of it runs. Only the asciidoc and markdown formatters read `content`, and section visibility through `sections.show` and `sections.hide` takes precedence over the order you wrote. Choose another output format and the template is dropped without complaint, and a hand tuned layout disappears from the result with no error to explain it.
The install recipe and the module's own Go directive point at different toolchains
The Go path in the installation notes is two lines, one for newer toolchains:
# go1.17+
go install github.com/terraform-docs/[email protected]and one for go1.16 that sets `GO111MODULE="on"` before `go get`, followed by a note that the minimum is `go1.16`. The module file itself asks for more than that: it declares `go 1.25.0` with `toolchain go1.25.8`, and the Dockerfile builds on `docker.io/library/golang:1.26.4-alpine`. So a reader on an old toolchain can follow every documented step and still meet a module directive the notes never mention. For anyone building from a clone, `make build` is the documented path, and it drops the binary under `$(go env GOPATH)/src/github.com/terraform-docs/terraform-docs/bin/$(uname | tr '[:upper:]' '[:lower:]')-amd64/terraform-docs`.
Four runners pin the same binary four different ways
The container recipe mounts the working directory and passes the user id so the files it writes do not end up owned by root:
docker run --rm --volume "$(pwd):/terraform-docs" -u $(id -u) quay.io/terraform-docs/terraform-docs:0.24.0 markdown /terraform-docsIts `latest` tag means the newest stable release and `edge` means the head of master, which makes a pinned tag the only reproducible choice. The pre-commit path pins instead of following:
repos:
- repo: https://github.com/terraform-docs/terraform-docs
rev: "v0.24.0"
hooks:
- id: terraform-docs-go
args: ["markdown", "table", "--output-file", "README.md", "./mymodule/path"]`pre-commit install` and `pre-commit install-hooks` wire it to every commit. The GitHub Action goes the other way and tracks a branch, with `uses: terraform-docs/gh-actions@main`, `working-dir: .`, `output-file: README.md`, `output-method: inject` and `git-push: "true"`. The last push to master is dated 2026-09-02, later than the v0.24.0 release on 2026-05-10.
The table stops where the module files stop
Output values are the clearest gap. The block reads:
output-values:
enabled: false
from: ""Output values do not reach the table until you enable `output-values` and point `from` at a values file, and the repository carries `examples/output_values.json` for exactly that case. Values that only exist after an apply are absent from the generated documentation by default. The rest of what you see comes from the module source: `header-from: main.tf` copies a header out of a file, `footer-from` does the same for the bottom, `read-comments: true` brings in the comments. Settings also carry `anchor`, `color`, `escape`, `html`, `hide-empty`, `lockfile` and `required`, with `indent: 2` and `sort.enabled: true` by name.
Editorial conclusion
terraform-docs earns a slot in any module repo that keeps generated tables in git, and it costs nothing when your modules are single directory and hand written. Before wiring it into a repo, check three things: whether your submodules live under a directory that recursive mode is pointed at, whether the formatter you want is one of the two that honour a content template, and whether the version string in your hook matches the binary your team installs. The output is only as honest as the descriptions your module already carries.
Frequently asked questions
What does terraform-docs do with a Terraform module?
It reads the module and renders it as documentation: a header copied from main.tf, then sections for inputs, modules, outputs, providers, requirements and resources, in markdown, asciidoc and other output formats. The result can be injected into an existing README between the BEGIN_TF_DOCS and END_TF_DOCS markers.
How do I use terraform-docs to keep a module README current?
Run the binary against the module directory, for example `terraform-docs markdown table --output-file README.md --output-mode inject /path/to/module`. The same generator also runs as the quay.io/terraform-docs/terraform-docs:0.24.0 container, as the terraform-docs/gh-actions action, or as a pre-commit hook that fires on every commit.
How do I install terraform-docs from source with Go?
Use `go install github.com/terraform-docs/[email protected]` on go1.17 and newer, and `GO111MODULE="on" go get github.com/terraform-docs/[email protected]` on go1.16. The binary lands in `$(go env GOPATH)/bin`, so if you see `terraform-docs: command not found` that directory is not on your PATH yet.
How do I install terraform-docs on Windows?
Two package managers are documented: `scoop bucket add terraform-docs https://github.com/terraform-docs/scoop-bucket` followed by `scoop install terraform-docs`, or `choco install terraform-docs`. Release archives for Windows come as ZIP rather than tar.gz, so the curl and tar recipe shown for the releases page applies to macOS and Linux only.
What is the alternative to terraform-docs?
The alternative is writing the table by hand, and what you trade away is the choice of formats, the asciidoc and markdown content templates, and four ways to run the same generator: the local binary, the quay.io container, the GitHub Action and the pre-commit hook.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/terraform-docs-terraform-docs)Star history chart for your README
[](https://hysenlabs.com/projects/terraform-docs-terraform-docs)Was this useful?