Provider documentation

The Terraform Registry displays documentation for the providers it hosts. This page describes the expected format for provider documentation. Provider documentation is not supported in the private registry of HCP Terraform or Terraform Enterprise.

Publishing

The Terraform Registry publishes providers from their Git repositories, creating a version for each Git tag that matches the Semver versioning format. Provider documentation is published automatically as part of the provider release process.

Provider documentation is always tied to a provider version. A given version always displays the documentation from that version's Git commit, and the only way to publish updated documentation is to release a new version of the provider.

Storage Limits

Each document can contain no more than 500KB of data. Documents which exceed this limit will be truncated, and a note will be displayed in the Terraform Registry.

Generating Documentation

The tfplugindocs command can be used to automatically generate documentation for your provider in the format necessary for the Terraform Registry. It will read descriptions and schema from each resource and data source in your provider and generate the relevant markdown files for you.

The terraform-provider-scaffolding-framework template repository includes example usage of the tfplugindocs command via go generate:

//go:generate go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs

If preferred you can choose to also invoke this manually for your provider. Once run, this command produces all of the content that satisfies the expected format for the Registry. Finally you can also create the documentation manually following the format and structure below. For more information on how the generation tool works, please see the terraform-plugin-docs repository.

Format

Provider documentation should be a directory of Markdown documents in the provider repository. Each Markdown document is rendered as a separate page. The directory should include a document for the provider index, a document for each resource, data source, ephemeral resource and function, and optional documents for any guides.

Directory Structure

Headers

We strongly suggest that provider docs include the following sections to help users understand how to use the provider. Create additional sections if they would enhance usability of the resource (for example, “Imports” or “Customizable Timeouts”).

Index Headers

# <provider> Provider

Summary of what the provider is for, including use cases and links to
app/service documentation.

## Example Usage

```hcl
// Code block with an example of how to use this provider.
```

## Argument Reference

* List any arguments for the provider block.

Resource/Data Source/Ephemeral Resource Headers

# <resource name> Resource/Data Source/Ephemeral Resource

Description of what this resource does, with links to official
app/service documentation.

## Example Usage

```hcl
// Code block with an example of how to use this resource.
```

## Argument Reference

* `attribute_name` - (Optional/Required) List arguments this resource takes.

## Attribute Reference

* `attribute_name` - List attributes that this resource exports.

Function Headers

# <function name> Function

Description of what this function returns, with links to any standards or algorithms.

## Example Usage

```hcl
provider::<provider name>::<function name>(/* ... */)
# result: /* ... */
```

## Signature

```text
<function name>(<parameter 0 display name> <parameter 0 type>) <return type>
```

## Arguments

1. `<parameter 0 display name>` (<parameter 0 type>) <parameter 0 description>

YAML Frontmatter

Markdown source files may contain YAML frontmatter, which provides organizational information and display hints. Frontmatter can be omitted for resources and data sources that don't require a subcategory.

Frontmatter is not rendered in the Terraform Registry web UI.

Example

---
page_title: "Authenticating with Foo Service via OAuth"
subcategory: "Authentication"
---

Supported Attributes

The following frontmatter attributes are supported by the Terraform Registry:

• page_title - The title of this document, which will display in the docs navigation. This is only required for documents in the guides/ folder.
• subcategory - An optional additional layer of grouping that affects the display of the docs navigation; see Subcategories below for more details. Resources and data sources should be organized into subcategories if the number of resources would be difficult to quickly scan for a user. Guides should be separated into subcategories if there are multiple guides which fit into 2 or more distinct groupings.

Callouts

If you start a paragraph with a special arrow-like sigil, it will become a colored callout box. You can't make multi-paragraph callouts. For colorblind users (and for clarity in general), callouts will automatically start with a strong-emphasized word to indicate their function.

Navigation Hierarchy

Provider docs are organized by category: functions, ephemeral resources, resources, data sources, and guides. At a minimum, a provider must contain an index (docs/index.md) and at least one function, ephemeral resource, resource, or data source.

Typical Structure

A provider named example with a resource and data source for instance, an ephemeral resource for auth_token, and a function named parse_instance_id would have these 4 files:

docs/
    index.md
    data-sources/
        instance.md
    ephemeral-resources/
        auth_token.md
    functions/
        parse_instance_id.md
    resources/
        instance.md

After publishing this provider version, its page on the Terraform Registry would display a navigation which resembles this hierarchy:

• example Provider
• Functions
  • parse_instance_id
• Ephemeral Resources
  • example_auth_token
• Resources
  • example_instance
• Data Sources
  • example_instance

Subcategories

To group these resources by a service or other dimension, add the optional subcategory field to the YAML frontmatter of the resource, data source, and function:

---
subcategory: "Compute"
---

This would change the navigation hierarchy to the following:

• example Provider
• Compute
  • Functions
    • parse_instance_id
  • Ephemeral Resources
    • example_auth_token
  • Resources
    • example_instance
  • Data Sources
    • example_instance

Resources, data sources, and functions without a subcategory will be rendered before any subcategories.

The following subcategories will be rendered at the bottom of the list:

• Beta
• Deprecated

Guides

Providers can optionally include 1 or more guides. These can assist users in using the provider for certain scenarios.

docs/
    index.md
    guides/
        authenticating.md
    data-sources/
        instance.md
    ephemeral-resources/
        auth_token.md
    functions/
        parse_instance_id.md
    resources/
        instance.md

The title for guides is controlled with the page_title attribute in the YAML frontmatter:

---
page_title: "Authenticating with Example Cloud"
---

The page_title is used (instead of the filename) for rendering the link to this guide in the navigation:

• example Provider
• Guides
  • Authenticating with Example Cloud
• Functions
  • parse_instance_id
• Ephemeral Resources
  • example_auth_token
• Resources
  • example_instance
• Data Sources
  • example_instance

Guides are always rendered before resources, data sources, functions, ephemeral resources, and any subcategories.

If a page_title attribute is not found, the title will default to the filename without the extension.

Guides Subcategories

If a provider has many guides, you can use subcategories to group them into separate top-level sections. For example, given the following directory structure:

docs/
    index.md
    guides/
        authenticating-basic.md
        authenticating-oauth.md
        setup.md
    data-sources/
        instance.md
    ephemeral-resources/
        auth_token.md
    functions/
        parse_instance_id.md
    resources/
        instance.md

Assuming that these three guides have titles similar to their filenames, and the first two include subcategory: "Authentication" in their frontmatter, the Terraform Registry would display this navigation structure:

• example Provider
• Guides
  • Initial Setup
• Authentication
  • Authenticating with Basic Authentication
  • Authenticating with OAuth
• Functions
  • parse_instance_id
• Ephemeral Resources
  • example_auth_token
• Resources
  • example_instance
• Data Sources
  • example_instance

Guides without a subcategory are always rendered before guides with subcategories. Both are always rendered before resources, data sources, functions, and ephemeral resources.

Migrating Legacy Providers Docs

For most provider docs already published to the website, no changes are necessary to publish them to the Terraform Registry.

If you want to publish docs on the Terraform Registry that are not available on the website, take the following steps to migrate to the newer format:

1. Move the website/docs/ folder to docs/
2. Expand the folder names to match the Terraform Registry's expected format:
   • Rename docs/d/ to docs/data-sources/
   • Rename docs/r/ to docs/resources/
   • No changes necessary for docs/functions/, docs/ephemeral-resources, or docs/guides
3. Change file suffixes from .html.markdown or .html.md to .md.