Skip to main content
Many products in this repository maintain documentation for multiple simultaneous versions. This page explains how versioned content is structured and how to work with it.

​
Versioned vs. unversioned products

The following table lists all products in the repository and whether their documentation is versioned:
ProductDirectoryVersioned
Boundarycontent/boundaryYes
Consulcontent/consulYes
HCPcontent/hcp-docsNo
HCP Vault Dedicatedcontent/hcp-docsNo
HCP Vault Secretscontent/hcp-docsNo
HCP Packercontent/hcp-docsNo
Nomadcontent/nomadYes
Sentinelcontent/sentinelYes
Terraformcontent/terraformYes
Terraform CDKcontent/terraform-cdkYes
HCP Terraform agentscontent/terraform-docs-agentsYes
Terraform (common docs)content/terraform-docs-commonNo
Terraform Enterprisecontent/terraform-enterpriseYes
Terraform MCP Servercontent/terraform-mcp-serverYes
Terraform Migratecontent/terraform-migrateYes
Terraform Plugin Frameworkcontent/terraform-plugin-frameworkYes
Terraform Plugin Logcontent/terraform-plugin-logYes
Terraform Plugin Muxcontent/terraform-plugin-muxYes
Terraform Plugin SDKcontent/terraform-sdkYes
Terraform Plugin Testingcontent/terraform-plugin-testingYes
Vaultcontent/vaultYes
Waypointcontent/hcp-docsNo
Well-Architected Frameworkcontent/well-architected-frameworkNo

​
Directory structure for versioned products

For versioned products, the product directory contains one subdirectory per supported version: 
content/terraform/
├── v1.7.x/
│   ├── docs/
│   ├── data/
│   └── img/
├── v1.8.x/
│   ├── docs/
│   ├── data/
│   └── img/
└── v1.9.x/
    ├── docs/
    ├── data/
    └── img/
Each version subdirectory is self-contained: it includes the MDX content files, the navigation sidebar data, and the image assets for that specific version. For unversioned products, the product directory contains content directly: 
content/hcp-docs/
├── content/
├── data/
└── public/

​
Finding the right version to edit

When updating currently published documentation, edit the files in the version directory that corresponds to the released version you want to change. If you need to apply the same fix to multiple versions, edit each version directory separately.
Because all version directories are on the filesystem at the same time, you can use your editor’s find-and-replace across the entire product directory to update content in all versions at once.
For upcoming minor or patch releases, each product’s tech writer team creates an assembly branch named using the format <product>/<exact_release_number> (for example, vault/202511). Clone that branch and make your changes in the current release folder: 
git clone --single-branch --branch <minor_branch_name> [email protected]:hashicorp/web-unified-docs.git
For upcoming major releases, the tech writer team also creates the new version directory. Check with your team for the branch name and the name of the new version folder.

​
The v-latest and RC version workflow

The prebuild process and version metadata generation use the semverCoerce function defined for each product in productConfig.mjs to sort and identify the latest version. The version directory with the highest semver value is treated as the latest version and served at the latest version alias in the API.
Terraform Enterprise uses date-based version strings (e.g., v202206-01) rather than semver. Its semverCoerce function converts these date strings to a sortable semver representation purely for ordering purposes.
When a new release is cut, the tech writer team merges the release branch into main. The new version directory goes live, and the latest alias in the API automatically points to the new highest version.

​
How version metadata is generated

The prebuild process generates app/api/versionMetadata.json by:
  1. Scanning each versioned product’s content directory for version subdirectories.
  2. Applying the product’s semverCoerce function to normalize version strings for sorting.
  3. Writing the sorted list of versions and their metadata into versionMetadata.json.
This file is read at runtime by the GET /api/content/[productSlug]/version-metadata endpoint, which the dev-portal uses to populate version selector dropdowns.

Build docs developers (and LLMs) love

Get started for freeTalk to us