terraform-docs .terraform-docs.yml Config File

A .terraform-docs.yml file captures the format, sections, sorting, and output settings so terraform-docs behaves the same everywhere.

Long flag lists drift between local runs, pre-commit hooks, and CI. A committed .terraform-docs.yml makes the configuration declarative and consistent across all three.

What it does

terraform-docs auto-loads .terraform-docs.yml from the target directory (or one named with -c). It sets the format, which sections to show or hide, the sort order, and the output file and mode, so a bare terraform-docs . produces the team-standard output.

Common usage

.terraform-docs.yml

formatter: "markdown table"

output:
  file: README.md
  mode: inject

sort:
  enabled: true
  by: required

sections:
  hide:
    - providers

Run it

Terminal

# auto-loads .terraform-docs.yml from the directory
terraform-docs .
# point at a shared config explicitly
terraform-docs -c ../.terraform-docs.yml .

Options

Key	What it does
formatter	Required: e.g. "markdown table", "markdown document"
output.file / output.mode	Where and how to write (inject or replace)
sort.by	name, required, or type
sections.hide / sections.show	Which sections appear
-c <file>	Load a config from a non-default path

In CI

Commit .terraform-docs.yml at the repo root (or per module) so the CI check, the pre-commit hook, and developers all run with identical settings. With output.mode: inject set in the file, the CI gate is just terraform-docs --output-check ..

Common errors in CI

"formatter is required" means the YAML omits the formatter key, which has no default. "yaml: unmarshal errors" points at an indentation or key typo in the config. If output goes to stdout instead of the README, the output: block is missing or -c loaded a different file than you expected.