Provider Docs

Terraform Provider Docs

Follow This Workflow

1. Confirm scope and documentation targets.

• Map code changes to the exact doc targets: provider index, resources, data sources, ephemeral resources, list resources, functions, or guides.
• Decide whether content should come from schema descriptions, templates, or both.

2. Write schema descriptions first.

• Add precise user-facing descriptions to schema fields so generated docs stay aligned with behavior.
• Keep wording specific to argument purpose, constraints, defaults, and computed behavior.

3. Add or update template files in docs/.

• Create only files that map to implemented provider objects.
• Use HashiCorp-recommended template paths:
• 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/guides/<name>.md.tmpl
• Keep templates focused on overview and examples; rely on generated sections for field-by-field details.

4. Generate documentation with tfplugindocs.

• Prefer repository defaults when configured:

go generate ./...

• Otherwise run the generator directly:

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

• Re-run generation after every schema or template edit.

5. Validate the generated markdown.

• Verify files in docs/ match the current provider implementation.
• Verify examples are valid HCL and reflect current argument/attribute names.
• Verify required/optional/computed semantics in docs match schema behavior.

6. Apply Registry publication rules before release.

• Use semantic version tags prefixed with v (for example v1.2.3).
• Create release tags from the default branch.
• Keep terraform-registry-manifest.json in the repository root.
• Expect docs to be versioned in Registry and switchable with the version selector.

7. Preview or troubleshoot publication when needed.

• Use the HashiCorp preview process to inspect rendered docs before release when accuracy risk is high.
• If docs are missing in Registry, check tag format, tag source branch, manifest file presence, and provider publication status.

Enforce Quality Bar

• Keep documentation behaviorally accurate; never describe unsupported arguments or attributes.
• Keep examples minimal, realistic, and runnable.
• Keep terminology and naming consistent across provider, resources, and data sources.
• Avoid duplicating generated argument/attribute blocks in manual templates.
• Keep doc changes tied to the same PR as schema/API changes whenever possible.

Load References On Demand

• Read references/hashicorp-provider-docs.md for source-backed rules and official links.
• Load only the sections needed for the current change to keep context lean.

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/guides/<name>.md.tmpl

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>

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