`terraform-docs`: A Cool Way of Documenting Terraform Projects

What Is It?

terraform-docs is a utility that generates documentation from Terraform modules in various output formats. It allows you to easily integrate documentation that displays inputs, outputs, requirements, providers, and more! It supports several output formats—my personal favorite is Markdown.

What Does It Look Like?

An example from the official documentation provides a clear illustration of how the module works, making it much easier for users to understand its usage. Below is an image demonstrating this example.

Markdown Table Output — Screenshot of a markdown table generated by `terraform-docs`.

Installation

As the installation process may change over time, please refer to the official documentation.

Options

You need to define a .config directory inside the directory where you want to generate the documentation. In this file, we define:

formatter: Set to Markdown, which I recommend.
output: Set to README.md, which is the default file for displaying content in a repository.
sort: To enable sorting of elements. We use the required criteria that sorts inputs by name and shows required ones first.
settings: General settings to control the behavior and the generated output.
content: The specific content to include in the documentation.

Minimal Configuration

formatter: "markdown"

output:
  file: "README.md"

sort:
  enabled: true
  by: required

settings:
  read-comments: false
  hide-empty: true
  escape: false

content: |-
  {{ .Requirements }}

  {{ .Modules }}

  {{ .Inputs }}

  {{ .Outputs }}

For more details about the configuration, please refer to this guide

Integration with Github Actions

To use terraform-docs with GitHub Actions, configure a YAML workflow file (e.g., .github/workflows/documentation.yml) with the following content:

name: Generate terraform docs

on:
  pull_request:
    branches:
      - main

jobs:
  terraform:
    name: "terraform docs"
    runs-on: ubuntu-latest

    # Use the Bash shell regardless whether the GitHub Actions runner is ubuntu-latest, macos-latest, or windows-latest
    defaults:
      run:
        shell: bash

    steps:
      # Checkout the repository to the GitHub Actions runner
      - name: Checkout
        uses: actions/checkout@v2

      # Install the latest version of Terraform CLI
      - name: Check docs
        uses: terraform-docs/gh-actions@v1.0.0
        with:
          output-file: README.md
          fail-on-diff: true

See it in action

Here's an example of terraform-docs being used in a personal module I developed.

terraform-docs: A Cool Way of Documenting Terraform Projects