plugins.md

title	Plugins
description	terraform-docs plugin development guide
menu	docs parent developer-guide
weight	310
toc	false

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.

[content]: {{< ref "content" >}} [formatter]: {{< ref "formatter" >}} [tfdocs-format-template]: https://github.com/terraform-docs/tfdocs-format-template