Releases: terraform-docs/terraform-docs
v0.18.0
Notable Updates
The most notable changes in this release are:
-
Resources can get ignored using
terraform-docs-ignore
comment:All types of resources can be ignored from the generated output by prepending them
with a commentterraform-docs-ignore
.################################################################## # All of the following will be ignored from the generated output # ################################################################## # terraform-docs-ignore resource "foo_resource" "foo" {} # This resource is going to get ignored from generated # output by using the following known comment. # # terraform-docs-ignore # # The ignore keyword also doesn't have to be the first, # last, or the only thing in a leading comment resource "bar_resource" "bar" {} # terraform-docs-ignore data "foo_data_resource" "foo" {} # terraform-docs-ignore data "bar_data_resource" "bar" {} // terraform-docs-ignore module "foo" { source = "foo" version = "x.x.x" } # terraform-docs-ignore variable "foo" { default = "foo" } // terraform-docs-ignore output "foo" { value = "foo" }
-
Skip root module documentation while executing recursively:
The main module document is generated by default, but should the main module document be
excluded from document generation,--recursive-include-main=false
can be used or alternatively
in the.terraform-docs.yml
:recursive: enabled: true path: modules include-main: false
Changelog
Features
- 943489c Ignore inputs with terraform-docs-ignore comment
- 8f74fd4 feat: ignore outputs, providers, resources with comments
- d0862bd Update Dockerfile FROM command to use non-ambiguous container sources
- 59eb90f Make main module doc optional when in recursive generation
Bug Fixes
- 656f6a6 Fix output values with null
- d5a55ae more fixes of binary name with missing s
- 1b2dbab more fixes of binary name with missing s
- 29e186a Fixed binary name in description output
Chores
- 5e77bcc Bump actions/checkout from 3 to 4
- 21313cf Bump actions/setup-go from 3 to 5
- 89b52d5 Bump alpine from 3.18.5 to 3.19.0
- 01435d7 Bump alpine from 3.19.0 to 3.19.1
- b87d0e0 Bump alpine from 3.19.1 to 3.20.0 in /scripts/release
- 50a8858 Bump codecov/codecov-action from 1 to 3
- e729518 Bump codecov/codecov-action from 3 to 4
- 70ed14e Bump dawidd6/action-homebrew-bump-formula from 3.10.1 to 3.11.0
- 73ae81c Bump dawidd6/action-homebrew-bump-formula from 3.8.0 to 3.10.1
- 127dba6 Bump docker/login-action from 1 to 3
- 4dc7807 Bump github/codeql-action from 1 to 3
- 7a00604 Bump golang from 1.21.5-alpine to 1.22.1-alpine
- a321c28 Bump golang to 1.22.1
- d6331c1 Bump golang.org/x/net from 0.19.0 to 0.23.0
- 5a70c7a Bump google.golang.org/protobuf from 1.31.0 to 1.33.0
- ff0ce44 Bump google.golang.org/protobuf from 1.31.0 to 1.33.0
- ca3eea1 Bump goreleaser/goreleaser-action from 2 to 5
- 38fc0e6 Bump softprops/action-gh-release from 1 to 2
- f92cf6f Bump version to v0.18.0-alpha
- 6041ae9 Change dependabot cadence to daily
- 159bc83 Create dependabot file
- e5a9ee0 --- updated-dependencies: - dependency-name: alpine dependency-type: direct:production update-type: version-update:semver-patch ...
- 75e05c0 --- updated-dependencies: - dependency-name: golang dependency-type: direct:production update-type: version-update:semver-patch ...
- 228c7a7 Release version v0.18.0
- 656aa7c Update go crypto lib to v0.17.0
- 2b71b4d chore: add release-cut workflow
- d5e48a5 chore: add scripts/release/ folder to dependabot
- fde40b1 chore: bump alpine to 3.20.0
- b79a7c4 chore: bump golang to 1.22.3
- 288faea chore: update dependencies
- 740e0a8 go get -u github.com/hashicorp/hcl/v2, update to v0.20.1 to support provider functions
Docker images
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.18.0
Contributors
Very special thanks to the contributors.
v0.17.0
Changelog
Features
- 38a327a Add fish shell completion
- e72f215 Always convert CRLF to LF for output description
- eb2e3b7 fix completion installing command
- 230113f Move terraform-docs bin in a folder already in the Linux PATH
- 5727f8b Preserve whitespaces of provided content and template
- 65b37fb Update OpenSSL package to mitigate CVE-2023-5363
Bug Fixes
- 4132916 Fix CI linting
- 3467aa9 Fix faulty license headers
- b4d62c8 Fix spelling
- a375aa7 fix spaces
- 9449cf8 fix typo
Chores
- 4eb50ae Bump alpine to 3.14.2
- c51e1ac Bump alpine to 3.16.0
- e5abff0 Bump alpine to 3.18.5
- 6f4b4d8 Bump golang to 1.17.6
- 8423fc0 Bump golang to 1.18.10
- 61f0423 Bump golang to 1.18.3
- 47bb0d2 Bump golang to 1.21.5
- f093753 Bump golangci-lint to 1.47.2 and fix issues
- 5cfb2f2 Bump golangci-lint to 1.55.2 and fix issues
- 9fa02e7 Bump staticcheck to 2023.1.6
- b37d2dc Bump version to v0.17.0-alpha
- a74d0f4 Bump version to v1.0.0-alpha
- a89c52e Enhance release script
- ac2f987 Update actions/checkout to v3
- 040b27b Update actions/setup-go to v3
- 5fad7ab Update go dependencies
- 649f1c4 Update go module dependencies
- 4552242 Update go module dependencies
- 82eaf8b Update goreleaser/goreleaser-actiona to v3
- 89666c0 Update container to Alpine 3.18.2 and Go 1.18.10
- 5638b29 Update Alpine base image to 3.16.1
- 21a9745 Upgrade Google Cloud Go packages in go.sum
- bb12a12 Remove Scalr sponsorship
- 090efce Run make fmt
Docker images
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.17.0
Contributors
Very special thanks to the contributors.
v0.16.0
Changelog
Features
f613750 Add 'HideEmpy' section bool flag
6f97f67 Add abitlity to partially override config from submodules
de684ce Add public ReadConfig function
54dc0f5 Add recursive config to .terraform-docs.yml file
89648f7 Add sprig functions to built-in template functions
f3c9238 Extract leading comments for resources and modules
045707b feat: Add new flag 'read-comments' to optionally process comments as description
Bug Fixes
5a1210b Skip read lines from empty file
Refactoring
465dd14 Make terraform.Module available in content
90942f7 Move format package from internal to public
4a9ffe7 Move plugin-sdk to in-tree in core repository
d2fe2b1 Move print package from internal to public
b3ff514 Move template package from internal to public
ca8f833 Move template package from internal to public
Chores
f33826c Cleanup documentations
bb10971 Deprecate Settings and Options in favor of Config
3d2b878 Overhaul README and docs improvements
1ae5fd9 Restructure configurations docs
0ad14a3 Restructure how-tos docs
628f2c6 Update Netlify config and build CI
Docker images
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.16.0
Contributors
Very special thanks to the contributors.
v0.15.0
Notable Updates
The most notable changes in this release are:
-
Generate submodules documents with
--recursive
flagConsidering the file structure below of main module and its submodules, now it is possible to generate documentation for them main and all its submodules in one execution.
Note that generating documentation recursively is allowed only with
--output-file
set.Path to find submodules can be configured with
--recursive-path
(defaults tomodules
).Each submodule can also have their own
.terraform-docs.yml
config file, to override configuration from root module.. ├── README.md ├── main.tf ├── modules │ └── my-sub-module │ ├── README.md │ ├── main.tf │ ├── variables.tf │ └── versions.tf ├── outputs.tf ├── variables.tf └── versions.tf
-
Ignore extracting versions from terraform.lock.hcl
New flag,
--lockfile
, is added to control whether ignore reading.terraform.lock.hcl
file in an attempt to extract the exact version of provider being used or not. Default istrue
.If set to true, exact version of provider available in lock file at the time of execution will be extracted. If set to false, the version in
.tf
file will be used (either exact, or a constrained version:>=
,~>
, ...) -
The updated order of trying to look up for .terraform-docs.yml config file, now, is:
- root of module directory
.config/
folder at root of module directory- current directory
.config/
folder at current directory$HOME/.tfdocs.d/
-
add output-check option for outputs
This option can be used to compare content of target file with generated output by terraform-doc and fail if different.
-
Remove
--show-all
,--hide-all
, and--sort-by-XXX
flags. (which have been deprecated in v0.13.0)
Changelog
Features
d77324c Add new '--show all' and '--hide all' sections
d004771 Add support for generating Packer document
f46a48b Attempt looking up config file in .config folder
1450ee9 Generate submodules documents with '--recursive' flag
5256426 Ignore extracting versions from terraform.lock.hcl
25f03b4 Remove deprecated '--show-all' and '--hide-all' flags
258f460 Remove deprecated '--sort-by-XXX' flags
21eaab4 add output-check option for outputs
Bug Fixes
ab05309 Process \n as line break in --output-template flag
c14edaf Properly format indented code blocks
61cc005 Render resources without URL correctly in Markdown and Asciidoc
Chores
8a288b5 Add Scalr sponsorship
af68ca2 Add new example for MacOs Install docs
77bc780 Bump alpine to 3.14.0
dfd1256 Bump golang to 1.16.6-alpine
bb1e21a Cosmetic cleanup asciidoc module table
490644e Increase test coverage for Config
209ed66 Upgrade go dependencies
567cfcc updating how-to doc for correct Include Examples syntax
Docker images
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.15.0
Contributors
Very special thanks to the contributors.
v0.14.1
Changelog
This is a small patch over v0.14.0. It fixes base template not found
error on Windows. You can ignore updating to this version if you are not running terraform-docs on Windows.
Bug Fixes
30b429d Fix base template not found on Windows
Docker images
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.14.1
v0.14.0
Notable Updates
The most notable changes in this release are:
-
Generated content can be customized further away with
content
in configuration. If thecontent
is empty the default orders of section is used.content
is a Go template with following additional variables:{{ .Header }}
{{ .Footer }}
{{ .Inputs }}
{{ .Modules }}
{{ .Outputs }}
{{ .Providers }}
{{ .Requirements }}
{{ .Resources }}
content: |- Any arbitrary text can be placed anywhere in the content {{ .Header }} and even in between sections {{ .Providers }} and they don't even need to be in the default order {{ .Outputs }} {{ .Inputs }}
These variables are the generated output of individual sections in the selected formatter. For example
{{ .Inputs }}
is Markdown Table representation of inputs when formatter is set tomarkdown table
and AsciiDoc Document representation when formatter is set toasciidoc document
and so on.Compatible formats for customized content are:
asciidoc document
asciidoc table
markdown document
markdown table
-
Local relative files can be included automatically in the generated content with `{{ include "..." }} function. This can be very useful for:
- inject arbitrary markdown files in between sections
- automatically include example usage
content: |- include any relative files {{ include "relative/path/to/file" }} or examples ```hcl {{ include "examples/foo/main.tf" }} ```
-
Add
--html bool
flag and config to Markdown to control the generated HTML tags inside markdown output. If set to false no html tags (e.g.<br>
,<pre>
) will be generated. And as a workaround the multi-line codeblock will be converted to single line with linebreak onverted to<SPACE>
.For example:
{ "bar": { "bar": "bar", "foo": "bar" }, "buzz": [ "fizz", "buzz" ], "fizz": [] }
will be converted to:
{ "bar": { "bar": "bar", "foo": "bar" }, "buzz": [ "fizz", "buzz" ], "fizz": [] }
Changelog
Features
2f088f2 Add '--html bool' flag and config to Markdown
6777364 Customize content with individual sections output
ea34bce Include relative files into generated content
57cf3db Extract provider version from .terraform.lock.hcl
0284283 Separate the module version from module source when using ?ref=
Bug Fixes
90ccb84 Add missing Resource.Mode to plugin-sdk (#493)
6820b4c Normalize version to prevent malformed error
Chores
bd32f8c Bump action-homebrew-bump-formula action to v3.8.0
7327de1 Clarify deprecated settings in the docs (#499)
d79abf0 Documentation cosmetic cleanup
2706df0 Enable CodeQL scanning
5df7ff2 Improve Makefile help message
23436be Update release scripts
7f63260 Update to go1.16.4
4397fac Validate license header on files on CI
Docker images
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.14.0
Contributors
Very special thanks to the contributors.
v0.13.0
Notable Updates
The most notable changes in this release are:
-
Add support for Terraform v0.15 and
configuration_aliases
(thanks to @adamjohnson01) -
Add ability to show or hide data-sources (thanks to @edgarsandi)
-
Read
.terraform-docs.yml
from relative path, absolute path, or$HOME
(more info)# executing from parent $ terraform-docs -c .terraform-docs.yml module-a/ # executing from child $ cd module-a/ $ terraform-docs -c ../.terraform-docs.yml . # or an absolute path $ terraform-docs -c /path/to/parent/folder/.terraform-docs.yml .
-
Support outputing to file for absolute path (more info)
# this works, relative path $ terraform-docs markdown table --output-file ../docs/README.md . # so does this, absolute path $ terraform-docs markdown table --output-file /path/to/module/docs/README.md .
-
Version constraints configuration (more info)
# .terraform-docs.yml version: ">= 0.13.0, < 1.0.0"
Breaking Changes
-
We're no longer distributing standalone binaries. Only compressed files (either
tar.gz
orzip
) will be available to download from GitHub Release page. -
--sort-by-XX
flags are deprecated in favor of corresponding dynamic--sort-by XX
. Affected flags are:--sort-by-required
--sort-by-type
In return new
--sort-by string
is added with following values:name
(default)required
type
Note that the behavior of
--sort bool
was not changed and to disable sorting altogether you can run--sort false
.Note than the type of
sort.by
in.terraform-docs.yml
has been changed fromlist
tostring
sort: enabled: true by: required # this now only accepts string
-
Flags
--show-all
and--hide-all
are deprecated in favor of explicit use of--show
and--hide
.In other words when
--show <section>
is used, only<section>
will be shown. If you want to show multiple sections and hide the rest you can specify multiple--show
flags. The same logic is also applied to--hide
.# show 'inputs' and hide everything else $ terraform-docs --show inputs <formatter> # show 'inputs' and show 'outputs' and hide everything else $ terraform-docs --show inputs --show outputs <formatter> # hide 'header' and show everything else $ terraform-docs --hide header <formatter> # hide 'header' and hide 'providers' and show everything else $ terraform-docs --hide header --hide providers <formatter>
Note: Using
--show
or--hide
CLI flag will completely override the values from.terraform-docs.yml
. Example:$ cat .terraform-docs.yml sections: show: - inputs - outputs # example 1: this will only show 'providers' $ terraform-docs --show providers . # example 2: this will hide 'inputs' and hide 'providers' and show everything else $ terraform-docs --hide inputs --hide providers .
Changelog
Features
c8fc7ab add ability to show or hide data-sources
d914ca7 Add a flag for showing description with hcl formatted tfvars
a26111f Add support for configuration_aliases
fcd314b Read config from relative path, absolute, or $HOME
0eea133 Support inline comments variation for Markdown and AsciiDoc
845469c Support outputing to file for absolute path
dabf54f Version constraints configuration
Bug Fixes
4be2223 In output-mode inject do not fail if file not found
Refactoring
557d53d Deprecate '--sort-by-XX' in favor of '--sort-by XX'
8c531b6 Deprecate --show-all and --hide-all flags
40f9b9d Do not distribute standalone binaries
2ea8635 Remove unused build tools from dockerfile
Documentation
b4981a1 Add 'since version' to docs for clarity
1415ac9 Add Terraform compatibility matrix documentation
6b0cf54 Add document for 'false' value for CLI flag
2784920 Update doc to indicate minimum go1.16 is needed
Docker images
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.13.0
Contributors
Very special thanks to the contributors.
v0.12.1
Changelog
This is a small patch over v0.12.0. It fixes missing footer-from
from CLI and config (#449). You can ignore updating to this version if you are not using footer in your module output.
Bug Fixes
7a6f6c1 Fix missing footer-from if set via CLI flag or config
e4a3a84 print cli errors to stderr
Docker images
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.12.1
Contributors
Very special thanks to the contributors.
v0.12.0
Notable Updates
The most notable changes in this release are:
-
Add support for footer (thanks to @simonc-613)
-
Add anchors for markdown, asciidocs items (thanks to @nitrocode)
-
Save generated content directly into a file (mode
inject
andreplace
)-
inject: partially replace the target file with generated output
-
replace: completely replace the target file with generated output
The output generated by formatters (
markdown
,asciidoc
, etc) will be inserted into a template before getting saved into the file. This template can be customized with--output-template
CLI flag or corresponding item in.terraform-docs.yml
config file. Its default value is:<!-- BEGIN_TF_DOCS --> {{ .Content }} <!-- END_TF_DOCS -->
-
-
Remove
--no-XXX
flags. (in v0.10.0--no-XXX
have been deprecated in favor of their counterparts in the format of--XXX=false
)
Changelog
Features
aa1e6bb Add support for footer docs
1168e12 Add support for pre-commit hooks
ac5a29c Implement module sort by position (no sort)
243fb27 add mode resource or data source to generated docs
a3bafd6 Save generated content directly into a file
8c05cb9 Add resource 'Name' to generated docs
3d39a94 Add option to hide Type and Default columns
02f490d --anchor to add anchors for markdown, asciidocs
25d2ff4 Completely remove deprecated '--no-XXX' flags
Bug Fixes
7e489d2 Do not modify header lines and trailing whitespaces
c94b43a Template should be optional for output-mode 'replace'
Refactoring
10cd6de Add DCO file
5b57ea4 Disable codecov patch status
3cc4f44 Fix issues reported by golangci-lint
8faaf9f Remove authors file and corresponding scripts
c246442 Remove changelog and corresponding scripts
0c25f7b Update golangci-lint configuration
Docker images
docker pull quay.io/terraform-docs/terraform-docs:latest
docker pull quay.io/terraform-docs/terraform-docs:0.12.0
Contributors
Very special thanks to the contributors.
v0.12.0-beta.1
Notable Updates
terraform-docs v0.12.0-beta.1 is a pre-release. It is to help gather feedback from the community as well as give users a chance to test terraform-docs in staging environments before v0.12.0 is officially released.
Changelog
Features
a3bafd6 Save generated content directly into a file
8c05cb9 Add resource 'Name' to generated docs
3d39a94 Add option to hide Type and Default columns
02f490d --anchor to add anchors for markdown, asciidocs
25d2ff4 Completely remove deprecated '--no-XXX' flags
Docker images
docker pull quay.io/terraform-docs/terraform-docs:0.12.0-beta.1