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.

  • replace

    Completely replace the output-file with generated output.

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 sorrounding 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