Plugins

Generated output can be heavily customized with content, but if using that is not enough for your use-case, you can write your own plugin.

In order to install a plugin the following steps are needed:

  • download the plugin and place it in ~/.tfdocs.d/plugins (or ./.tfdocs.d/plugins)
  • make sure the plugin file name is tfdocs-format-<NAME>
  • modify formatter of .terraform-docs.yml file to be <NAME>

Important notes:

  • if the plugin file name is different than the example above, terraform-docs won’t be able to to pick it up nor register it properly
  • you can only use plugin thorough .terraform-docs.yml file and it cannot be used with CLI arguments

To create a new plugin create a new repository called tfdocs-format-<NAME> with following main.go:

package main

import (
    _ "embed" //nolint

    "github.com/terraform-docs/terraform-docs/plugin"
    "github.com/terraform-docs/terraform-docs/print"
    "github.com/terraform-docs/terraform-docs/template"
    "github.com/terraform-docs/terraform-docs/terraform"
)

func main() {
    plugin.Serve(&plugin.ServeOpts{
        Name:    "<NAME>",
        Version: "0.1.0",
        Printer: printerFunc,
    })
}

//go:embed sections.tmpl
var tplCustom []byte

// printerFunc the function being executed by the plugin client.
func printerFunc(config *print.Config, module *terraform.Module) (string, error) {
    tpl := template.New(config,
        &template.Item{Name: "custom", Text: string(tplCustom)},
    )

    rendered, err := tpl.Render("custom", module)
    if err != nil {
        return "", err
    }

    return rendered, nil
}

Please refer to tfdocs-format-template for more details. You can create a new repository from it by clicking on Use this template button.

Edit on GitHub

Contributing →