cf3a72a2bc
* Reinstate the accidentally deleted experimental testing page * try removing nav reference as it is hidden anyway * try nesting the nav reference? * try nesting with the other module pages |
||
---|---|---|
.. | ||
data | ||
docs | ||
img/docs | ||
layouts | ||
scripts | ||
Makefile | ||
package-lock.json | ||
package.json | ||
README.md | ||
vercel.json |
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.
Validating Content
Content changes are automatically validated against a set of rules as part of the pull request process. If you want to run these checks locally to validate your content before committing your changes, you can run the following command:
npm run content-check
If the validation fails, actionable error messages will be displayed to help you address detected issues.
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
-
Install Go or create a
~/go
directory manually. -
Open terminal and set
GOPATH
as an environment variable:Bash:
export $GOPATH=~/go
(bash)Zsh:
echo -n 'export GOPATH=~/go' >> ~/.zshrc
-
Restart your terminal or command line session.
Launch Site Locally
- Navigate into your local
terraform
top-level directory and runmake website
. - Open
http://localhost:3000
in your web browser. While the preview is running, you can edit pages and Next.js automatically rebuilds them. - 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:
-
Add the backport label for the latest version.
-
Merge the pull request. GitHub Actions autogenerates a backport pull request, linked to the original.
-
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.