/provider-docs

HashiCorp Provider Documentation Reference

Source of truth for this skill:

• https://developer.hashicorp.com/terraform/registry/providers/docs

Core Rules

• Publish provider docs through Terraform Registry using tfplugindocs.
• Generate provider docs from schema descriptions and markdown templates.
• Store templates under the repository docs/ directory with expected naming conventions.
• Keep release tags and manifest metadata valid so Registry can render and display docs.

Template Paths

Use these template paths when the corresponding provider objects exist:

• docs/index.md.tmpl
• docs/data-sources/<name>.md.tmpl
• docs/resources/<name>.md.tmpl
• docs/ephemeral-resources/<name>.md.tmpl
• docs/list-resources/<name>.md.tmpl
• docs/functions/<name>.md.tmpl
• docs/actions/<name>.md.tmpl
• docs/guides/<name>.md.tmpl

The Registry renders action pages from docs/actions/<action>.md, and tfplugindocs generates action documentation (including missing template scaffolds) with Terraform v1.14.0+. Action example files follow the convention examples/actions/<action_type>/action*.tf.

Example File Conventions

Keep example HCL in the examples/ directory and pull it into templates, instead of inlining HCL in .tmpl files:

examples/
├── provider/provider.tf                      # provider block for the index page only
├── resources/<type>/resource.tf              # picked up by generated templates
├── data-sources/<type>/data-source.tf
└── actions/<type>/action.tf

• One example per file, referenced from templates with {{ tffile "examples/resources/examplecloud_widget/resource.tf" }} — named variants get their own files (resource-with-tags.tf), each behind its own heading in the template.
• No terraform, provider, or output blocks in resource, data source, or action examples. Version constraints and provider configuration belong on the provider index page only; outputs distract from the object being documented. (The one exception is examples/provider/provider.tf, which exists to show provider configuration.)
• Keep each example minimal, runnable, and formatted with terraform fmt — generated docs render the file verbatim.

Generation Workflow

HashiCorp recommends wiring generator execution through go generate:

//go:generate go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>

Run from repository root:

go generate ./...

Alternative direct execution:

go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>

Action Pages

Structure modeled on the largest production example, terraform-provider-aws (website/docs/actions/ — hand-written there because that provider predates tfplugindocs action support; new providers should generate instead):

• One page per action. H1 uses an Action: prefix — # Action: examplecloud_restart_widget — parallel to # Resource: / # Data Source: on sibling pages.

• Intro paragraph states what the action does and whether it is synchronous or asynchronous, then links to the upstream service documentation for the operation it invokes.

• ## Example Usage starts with ### Basic Usage and must show both halves of using an action: the action block and the resource-side lifecycle { action_trigger { ... } } wiring — an action example without a trigger is not runnable:

  action "examplecloud_restart_widget" "example" {
    config {
      widget_id = examplecloud_widget.example.id
    }
  }
  
  resource "terraform_data" "trigger" {
    lifecycle {
      action_trigger {
        events  = [after_create, after_update]
        actions = [action.examplecloud_restart_widget.example]
      }
    }
  }

• ## Argument Reference lists config arguments (either flat, or split into required/optional groups). No attribute/output reference section — actions produce no state, and including one misleads readers.

• Callout conventions (while actions remain experimental):

  • ~> **Note:** for the preview disclaimer, e.g. "<action> is in alpha. Its interface and behavior may change as the feature evolves, and breaking changes are possible."
  • !> **Warning:** when the action causes changes Terraform does not reconcile (e.g. it mutates a resource whose state attributes will be stale until the next refresh) — name the affected attribute and the consequence.

• If the repo tracks release notes with go-changelog, new actions use the release-note:new-action entry type.

Release and Publication Constraints

• Use semantic version tags prefixed with v.
• Create tags from the default branch.
• Keep terraform-registry-manifest.json in the repository root.
• Understand docs appear by provider version in Registry once the provider release is published.

Preview and Troubleshooting

• Use HashiCorp's preview process to verify rendering before release when needed.
• If docs are missing or stale in Registry, verify:
  • tag naming and tag branch source
  • manifest file presence and validity
  • provider version publication state

Related Canonical Pages

• Provider docs guidance:
  • https://developer.hashicorp.com/terraform/registry/providers/docs
• Terraform Plugin Docs (tfplugindocs) source and usage:
  • https://github.com/hashicorp/terraform-plugin-docs