github.com/rstandt/terraform@v0.12.32-0.20230710220336-b1063613405c/website/docs/registry/providers/docs.html.md (about) 1 --- 2 layout: "registry" 3 page_title: "Terraform Registry - Provider Documentation" 4 sidebar_current: "docs-registry-provider-docs" 5 description: |- 6 Expected document structure for publishing providers to the Terraform Registry. 7 --- 8 9 # Provider Documentation 10 11 The [Terraform Registry][terraform-registry] displays documentation for the providers it hosts. This page describes the expected format for provider documentation. 12 13 ## Publishing 14 15 -> **Note:** Publishing is currently in a closed beta. Although we do not expect this document to change significantly before opening provider publishing to the community, this reference currently only applies to providers already appearing on the [Terraform Registry providers list][terraform-registry-providers]. 16 17 The Terraform Registry publishes providers from their Git repositories, creating a version for each Git tag that matches the [Semver](https://semver.org/) versioning format. Provider documentation is published automatically as part of the provider release process. 18 19 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. 20 21 ### Storage Limits 22 23 The maximum number of documents allowed for a single provider version is 1000. 24 25 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. 26 27 ## Format 28 29 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 and data source, and optional documents for any guides. 30 31 ### Directory Structure 32 33 | Location | Filename | Description | 34 |-|-|-| 35 | `docs/` | `index.md` | Index page for the provider. | 36 | `docs/guides/` | `<guide>.md` | Additional documentation for guides. | 37 | `docs/resources/` | `<resource>.md` | Information for a Resource. Filename should not include a `<PROVIDER NAME>_` prefix. | 38 | `docs/data-sources/` | `<data_source>.md` | Information on a provider data source. | 39 40 -> **Note:** In order to support provider docs which have already been formatted for publishing to [terraform.io][terraform-io-providers], the Terraform Registry also supports docs in a `website/docs/` legacy directory with file extensions of `.html.markdown` or `.html.md`. 41 42 ### Headers 43 44 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”). 45 46 #### Index Headers 47 48 # <provider> Provider 49 50 Summary of what the provider is for, including use cases and links to 51 app/service documentation. 52 53 ## Example Usage 54 55 ```hcl 56 // Code block with an example of how to use this provider. 57 ``` 58 59 ## Argument Reference 60 61 * List any arguments for the provider block. 62 63 #### Resource/Data Source Headers 64 65 # <resource name> Resource/Data Source 66 67 Description of what this resource does, with links to official 68 app/service documentation. 69 70 ## Example Usage 71 72 ```hcl 73 // Code block with an example of how to use this resource. 74 ``` 75 76 ## Argument Reference 77 78 * `attribute_name` - (Optional/Required) List arguments this resource takes. 79 80 ## Attribute Reference 81 82 * `attribute_name` - List attributes that this resource exports. 83 84 ### YAML Frontmatter 85 86 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. 87 88 Frontmatter is not rendered in the Terraform Registry web UI. 89 90 #### Example 91 92 ```markdown 93 --- 94 page_title: "Authenticating with Foo Service via OAuth" 95 subcategory: "Authentication" 96 --- 97 ``` 98 99 #### Supported Attributes 100 101 The following frontmatter attributes are supported by the Terraform Registry: 102 103 * **page_title** - The title of this document, which will display in the docs navigation. This is only required for documents in the `guides/` folder. 104 * **subcategory** - An optional additional layer of grouping that affects the display of the docs navigation; [see Subcategories below](#subcategories) 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. 105 106 ### Callouts 107 108 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. 109 110 Sigil | Text prefix | Color 111 ------|-------------------|------- 112 `->` | `**Note**` | blue 113 `~>` | `**Note**` | yellow 114 `!>` | `**Warning**` | red 115 116 ## Navigation Hierarchy 117 118 Provider docs are organized by category: resources, data sources, and guides. At a minimum, a provider must contain an index (`docs/index.md`) and at least one resource or data source. 119 120 ### Typical Structure 121 122 A provider named `example` with a resource and data source for `instance` would have these 3 files: 123 124 ``` 125 docs/ 126 index.md 127 data-sources/ 128 instance.md 129 resources/ 130 instance.md 131 ``` 132 133 After publishing this provider version, its page on the Terraform Registry would display a navigation which resembles this hierarchy: 134 135 * example Provider 136 * Resources 137 * example_instance 138 * Data Sources 139 * example_instance 140 141 ### Subcategories 142 143 To group these resources by a service or other dimension, add the optional `subcategory` field to the YAML frontmatter of the resource and data source: 144 145 ```markdown 146 --- 147 subcategory: "Compute" 148 --- 149 ``` 150 151 This would change the navigation hierarchy to the following: 152 153 * example Provider 154 * Compute 155 * Resources 156 * example_instance 157 * Data Sources 158 * example_instance 159 160 Resources and data sources without a subcategory will be rendered before any subcategories. 161 162 ### Guides 163 164 Providers can optionally include 1 or more guides. These can assist users in using the provider for certain scenarios. 165 166 ``` 167 docs/ 168 index.md 169 guides/ 170 authenticating.md 171 data-sources/ 172 instance.md 173 resources/ 174 instance.md 175 ``` 176 177 The title for guides is controlled with the `page_title` attribute in the YAML frontmatter: 178 179 ```markdown 180 --- 181 page_title: "Authenticating with Example Cloud" 182 --- 183 ``` 184 185 The `page_title` is used (instead of the filename) for rendering the link to this guide in the navigation: 186 187 * example Provider 188 * Guides 189 * Authenticating with Example Cloud 190 * Resources 191 * example_instance 192 * Data Sources 193 * example_instance 194 195 Guides are always rendered before resources, data sources, and any subcategories. 196 197 If a `page_title` attribute is not found, the title will default to the filename without the extension. 198 199 ### Guides Subcategories 200 201 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: 202 203 ``` 204 docs/ 205 index.md 206 guides/ 207 authenticating-basic.md 208 authenticating-oauth.md 209 setup.md 210 data-sources/ 211 instance.md 212 resources/ 213 instance.md 214 ``` 215 216 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: 217 218 * example Provider 219 * Guides 220 * Initial Setup 221 * Authentication 222 * Authenticating with Basic Authentication 223 * Authenticating with OAuth 224 * Resources 225 * example_instance 226 * Data Sources 227 * example_instance 228 229 Guides without a subcategory are always rendered before guides with subcategories. Both are always rendered before resources and data sources. 230 231 ## Migrating Legacy Providers Docs 232 233 For most provider docs already published to [terraform.io][terraform-io-providers], no changes are required to publish them to the Terraform Registry. 234 235 ~> **Important:** The only exceptions are providers which organize resources, data sources, or guides into subcategories. See the [Subcategories](#subcategories) section above for more information. 236 237 If you want to publish docs on the Terraform Registry that are not currently published to terraform.io, take the following steps to migrate to the newer format: 238 239 1. Move the `website/docs/` folder to `docs/` 240 2. Expand the folder names to match the Terraform Registry's expected format: 241 * Rename `docs/d/` to `docs/data-sources/` 242 * Rename `docs/r/` to `docs/resources/` 243 3. Change file suffixes from `.html.markdown` or `.html.md` to `.md`. 244 245 [terraform-registry]: https://registry.terraform.io 246 [terraform-registry-providers]: https://registry.terraform.io/browse/providers 247 [terraform-io-providers]: https://www.terraform.io/docs/providers/