output

Since v0.12.0

Save generated output to a file, if output.file is not empty.

Saving behavior can be controlled by output.mode:

• inject (default)

  Partially replace the output-file content with generated output.

  This creates the output-file if it doesn’t exist, otherwise it appends to output-file if it doesn’t have surrounding comments.

• replace

  Completely replace the output-file with generated output.

  This creates the output-file if it doesn’t exist.

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

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

Wording of the comments may be changed as necessary, 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.

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

Options#

Available options with their default values.

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

Examples#

Inject the generated output into README.md between the surrounding comments.

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

Replace the content of USAGE.md with generated output. Note that any manual changes to that file will be overwritten.

output:
  file: USAGE.md
  mode: replace
  template: |-
        {{ .Content }}

To output to YAML file with leading comment, the following can be used:

formatter: yaml

output:
  file: output.yaml
  mode: replace
  template: |-
    # Example leading 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 }}    

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)    

Edit on GitHub