Terraform Documentation

This directory contains the portions of the Terraform website that pertain to the core functionality, excluding providers and the overall configuration.

The website uses the files in this directory in conjunction with the terraform-website repository. The terraform-website repository brings all of the documentation together and contains the scripts for testing and building the entire site.

Suggesting Changes

You can submit an issue with documentation requests or submit a pull request with suggested changes.

Click Edit this page at the bottom of any Terraform website page to go directly to the associated markdown file in GitHub.

Modifying Sidebar Navigation

You must update the the sidebar navigation when you add or delete documentation .mdx files. If you do not update the navigation, the website deploy preview fails.

To update the sidebar navigation, you must edit the appropriate nav-data.json file. This repository contains the sidebar navigation files for the following documentation sets:

• Terraform Language: language-nav-data.json
• Terraform CLI: cli-nav-data.json
• Introduction to Terraform: intro-nav-data.json

For more details about how to update the sidebar navigation, refer to Editing Navigation Sidebars in the terraform-website repository.

Adding Redirects

You must add a redirect when you move, rename, or delete documentation pages. Refer to https://github.com/hashicorp/terraform-website#redirects for details.

Previewing Changes

You should preview all of your changes locally before creating a pull request. The build includes content from this repository and the terraform-website repository, allowing you to preview the entire Terraform documentation site.

Set Up Local Environment

1. Install Docker.

2. Install Go or create a ~/go directory manually.

3. Open terminal and set GOPATH as an environment variable:

   Bash: export $GOPATH=~/go(bash)

   Zsh: echo -n 'export GOPATH=~/go' >> ~/.zshrc

4. Restart your terminal or command line session.

Launch Site Locally

1. Navigate into your local terraform top-level directory and run make website.
2. Open http://localhost:3000 in your web browser. While the preview is running, you can edit pages and Next.js automatically rebuilds them.
3. Press ctrl-C in your terminal to stop the server and end the preview.

Deploying Changes

Merging a PR to main queues up documentation changes for the next minor product release. Your changes are not immediately available on the website.

The website generates versioned documentation by pointing to the HEAD of the release branch for that version. For example, the v1.2.x documentation on the website points to the HEAD of the v1.2 release branch in the terraform repository. To update existing documentation versions, you must also backport your changes to that release branch. Backported changes become live on the site within one hour.

Backporting

Important: Editing old versions (not latest) should be rare. We backport to old versions when there is an egregious error. Egregious errors include inaccuracies that could cause security vulnerabilities or extreme inconvenience for users.

Backporting involves cherry-picking commits to one or more release branches within a docs repository. You can backport (cherry-pick) commits to a version branch by adding the associated backport label to your pull request. For example, if you need to add a security warning to the v1.1 documentation, you must add the 1.1-backport label. When you merge a pull request with one or more backport labels, GitHub Actions opens a backport PR to cherry-pick your changes to the associated release branches. You must manually merge the backport PR to finish backporting the changes.

To make your changes available on the latest docs version:

1. Add the backport label for the latest version.

   

2. Merge the pull request. GitHub Actions autogenerates a backport pull request, linked to the original.

   

3. Merge the auto-generated backport pull request.

   You can review and merge your own backport pull request without waiting for another review if the changes in the backport pull request are effectively equivalent to the original. You can make minor adjustments to resolve merge conflicts, but you should not merge a backport PR that contains major content or functionality changes from the original, approved pull request. If you are not sure whether it is okay to merge a backport pull request, post a comment on the original pull request to discuss with the team.