envdoc

envdoc

envdoc is a tool for generating documentation for environment variables in Go structs. It takes comments associated with env tags in Go structs and creates a Markdown, plaintext or HTML file with detailed documentation.

For docenv linter see docenv/README.md.

Installation

Go >= 1.24

Add envdoc tool and install it:

go get -tool github.com/kda47/envdoc@latest
go install tool

Add go:generate:

//go:generate envdoc -output config.md
type Config struct {
    // ...
}

Generate:

go generate ./...

Before Go 1.24

Run it with go run in source file:

//go:generate go run github.com/kda47/envdoc@latest -output environments.md
type Config struct {
    // ...
}

Or download binary to run it:

go install github.com/kda47/envdoc@latest

And use it in code:

//go:generate envdoc -output environments.md
type Config struct {
    // ...
}

Usage

//go:generate envdoc -output <output_file_name>

• -dir (path string, optional) - Specify the directory to search for files. Default is the file dir with go:generate command.
• -files (glob string, optional) - File glob pattern to specify file names to process. Default is the single file with go:generate.
• -types (glob string, optional) - Type glob pattern for type names to process. If not specified, the next type after go:generate is used.
• -target (enum(caarlos0, cleanenv) string, optional, default caarlos0) - Set env library target.
• -output (path string, required) - Output file name for generated documentation.
• -format (enum(markdown, plaintext, html, dotenv, json) string, optional) - Output format for documentation. Default is markdown.
• -template (path string, optional) - Path to a custom template file for rendering the output. It has priority over -format.
• -title (string, optional, default Environment Variables) - Title to be used as the header of the generated file.
• -no-styles (bool, optional) - If true, CSS styles will not be included for html format.
• -env-prefix (string, optional) - Sets additional global prefix for all environment variables.
• -tag-name (string, optional, default: env) - Use custom tag name instead of env.
• -tag-default (string, optional, default: envDefault) - Use "default" tag name instead of envDefault.
• -required-if-no-def (bool, optional, default: false) - Set attributes as required if no default value is set.
• -field-names (bool, optional) - Use field names as env names if env: tag is not specified.
• -debug (bool, optional) - Enable debug output.

These params are deprecated and will be removed in the next major release:

• -type - Specify one type to process.
• -all - Process all types in a file.

Both parameters could be replaced with -types param:

• Use -types=Foo instead of -type=Foo.
• Use -types='*' instead of -all.

Example

Suppose you have the following Go file config.go:

package foo

//go:generate envdoc --output env-doc.md
type Config struct {
  // Port to listen for incoming connections
  Port int `env:"PORT,required"`
  // Address to serve
  Address string `env:"ADDRESS" envDefault:"localhost"`
}

And the go:generate line above creates documentation in env-doc.md file:

# Environment Variables

- `PORT` (**required**) - Port to listen for incoming connections
- `ADDRESS` (default: `localhost`) - Address to serve

See _examples dir for more details.

Compatibility

This tool is compatible with

• full compatibility: caarlos0/env
• full compatibility: ilyakaznacheev/cleanenv
• partial compatibility: sethvargo/go-envconfig
• partial compatibility: joeshaw/envdecode

Let me know about any new lib to check compatibility.

Custom Templates

envdoc also supports user-defined templates for more specific layouts provided with the -template flag.

Examples can be found here.

Template Data

Custom templates are expected to be Go text templates and are executed with the following data.

Top-Level Data

Section: renderSection

Each section represents a struct holding fields that map to environment variables.

Item: renderItem

Each item represents a struct field that maps to an environment variable.

Functions

Custom templates support the following string functions from the standard library:

• repeat
• split
• join
• contains
• toLower
• toUpper
• toTitle
• replace
• hasPrefix
• hasSuffix
• trimSpace
• trimPrefix
• trimSuffix
• trimLeft
• trimRight

In addition to the standard functions above, the following are supported:

• strAppend: func (arr []string, item string) []string - Appends item to arr.
• strSlice: func () []string - Makes a new empty slice.
• list: func(args ...any) []any - Returns the variadic args as a slice.
• sum: func(args ...int) int - Returns the sum of the variadic args.
• marshalIndent: func(v any) (string, error) - Marshals the given value into a JSON string.
  Returns an error if the value is not a valid JSON.

Contributing

If you find any issues or have suggestions for improvement, feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.