terraform-docs terraform-docs

    Configuration

    The terraform-docs configuration is a yaml file. This is a convenient way to share the configuation amongst teammates, CI, or other toolings. To do so you can use -c or --config flag which accepts name of the config file.

    Default name of this file is .terraform-docs.yml, and it will get picked it up (if existed) without needing to explicitly passing with config flag.

    $ tree
.
├── main.tf
├── ...
├── ...
└── .terraform-docs.yml
$ terraform-docs .

    Or you can use a config file with any arbitrary name:

    $ tree
.
├── main.tf
├── ...
├── ...
└── .tfdocs-config.yml
$ terraform-docs -c .tfdocs-config.yml .

    Options

    Below is a complete list of options that you can use with terraform-docs, with their corresponding default values (if applicable).

    formatter: <FORMATTER_NAME>

header-from: main.tf
footer-from: ""

sections:
  hide-all: false
  hide: []
  show-all: true
  show: []

output:
  file: ""
  mode: inject
  template: |-
    <!-- BEGIN_TF_DOCS -->
    {{ .Content }}
    <!-- END_TF_DOCS -->    

output-values:
  enabled: false
  from: ""

sort:
  enabled: true
  by: name

settings:
  anchor: true
  color: true
  default: true
  escape: true
  indent: 2
  required: true
  sensitive: true
  type: true

    Note: The following options cannot be used together:

    • sections.hide and sections.show
    • sections.hide-all and sections.show-all
    • sections.hide-all and sections.hide
    • sections.show-all and sections.show

    Formatters

    The following options are supported out of the box by terraform-docs and can be used for FORMATTER_NAME:

    Note: You need to pass name of a plugin as formatter in order to be able to use the plugin. For example, if plugin binary file is called tfdocs-format-foo, formatter name must be set to foo.

    header-from

    Relative path to a file to extract header for the generated output from. Supported file formats are .adoc, .md, .tf, and .txt. Default value is main.tf.

    Relative path to a file to extract footer for the generated output from. Supported file formats are .adoc, .md, .tf, and .txt. Default value is "".

    Sections

    The following options are supported and can be used for sections.show and sections.hide:

    • header
    • inputs
    • modules
    • outputs
    • providers
    • requirements
    • resources

    Output

    Insert generated output to file if output.file (or --output-file string CLI flag) is not empty. Insersion behavior can be controlled by output.mode (or --output-mode string CLI flag):

    • inject (default)

      Partially replace the output-file with generated output. This will fail if output-file doesn’t exist. Also will fail if output-file doesn’t already have surrounding comments.

    • replace

      Completely replace the output-file with generated output. This will create the output-file if it doesn’t exist.

    The output generated by formatters (markdown, asciidoc, etc) will first be inserted into a template, if provided, before getting saved into the file. This template can be customized with output.template or --output-template string CLI flag.

    Note: output.template is optional for mode replace.

    The default template value is:

    <!-- BEGIN_TF_DOCS -->
{{ .Content }}
<!-- END_TF_DOCS -->

    This template consists of at least three lines (all of which are mandatory):

    • begin comment
    • {{ .Content }} slug
    • end comment

    You may change the wording of comment as you wish, but the comment must be present in the template. Also note that SPACEs inside {{ }} are mandatory.

    You may also add as many lines as you’d like before or after {{ .Content }} line.

    Note: {{ .Content }} is mandatory if you want to customize template for mode replace. For example if you wish to output to YAML file with trailing comment, the following can be used:

    formatter: yaml

output:
  file: output.yaml
  mode: replace
  template: |-
    # Example trailing comments block which will be placed at the top of the
    # 'output.yaml' file.
    #
    # Note that there's no <!-- BEGIN_TF_DOCS --> and <!-- END_TF_DOCS -->
    # which will break the integrity yaml file.
    
    {{ .Content }}

    Template Comment

    Markdown doesn’t officially support inline commenting, there are multiple ways to do it as a workaround, though. The following formats are supported as begin and end comments of a template:

    • <!-- This is a comment -->
    • []: # (This is a comment)
    • []: # "This is a comment"
    • []: # 'This is a comment'
    • [//]: # (This is a comment)
    • [comment]: # (This is a comment)

    The following is also supported for AsciiDoc format:

    • // This is a comment

    The following can be used where HTML comments are not supported (e.g. Bitbucket Cloud):

    output:
  file: README.md
  mode: inject
  template: |-
    [//]: # (BEGIN_TF_DOCS)    
    {{ .Content }}

    [//]: # (END_TF_DOCS)

    Note: The empty line before [//]: # (END_TF_DOCS) is mandatory in order for Markdown engine to properly process the comment line after the paragraph.

    Sort

    To enable sorting of elements sort.enabled (or --sort bool CLI flag) can be used. This will indicate sorting is enabled or not, but consecutively type of sorting can also be specified with sort.by (or --sort-by string CLI flag). The following sort types are supported:

    • name (default): name of items
    • required: by name of inputs AND show required ones first
    • type: type of inputs

    Edit on GitHub

    ← Installation
    How To's →