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.
In order to test how documents will render in the Terraform Registry, you can use the Terraform Registry Doc Preview Tool.
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 LimitsEach 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.
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.
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 Location Filename Descriptiondocs/ index.md Index page for the provider. docs/guides/ <guide>.md Additional documentation for guides. docs/resources/ <resource>.md Information for a Resource. Filename should not include a <PROVIDER NAME>_ prefix. docs/data-sources/ <data_source>.md Information on a provider data source. docs/functions/ <function>.md Information on a provider function. docs/ephemeral-resources/ <ephemeral-resource>.md Information for an Ephemeral Resource. Filename should not include a <PROVIDER NAME>_ prefix.
Note: To support provider docs already formatted for publishing to the website, the Terraform Registry also supports docs in a website/docs/ legacy directory with file extensions of .html.markdown or .html.md.
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 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 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>
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"
---
The following frontmatter attributes are supported by the Terraform Registry:
guides/ folder.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.
Sigil Text prefix Color-> **Note** blue ~> **Note** yellow !> **Warning** red
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.
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:
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:
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:
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:
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.
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:
Guides without a subcategory are always rendered before guides with subcategories. Both are always rendered before resources, data sources, functions, and ephemeral resources.
For most provider docs already published to the website, no changes are necessary to publish them to the Terraform Registry.
Important: The only exceptions are providers which organize resources, data sources, or guides into subcategories. See the Subcategories section above for more information.
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:
website/docs/ folder to docs/docs/d/ to docs/data-sources/docs/r/ to docs/resources/docs/functions/, docs/ephemeral-resources, or docs/guides.html.markdown or .html.md to .md.RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4