Adding API Versions to HyperDocs

info

This page is about the public hyperdocs Docusaurus site (github.com/hvlabs/hyperdocs), not this internal documentation.

Overview

This guide walks you through adding API versioning to the HyperVerge documentation site. It covers two scenarios:

Converting a single-version API to use versioning — e.g., your API has one doc page and you're releasing v2.
Adding a new version to an already-versioned API — e.g., your API already has v1 and v2, and you're adding v3.

How it works: Each API version gets its own page. A dropdown selector lets users switch between versions; the sidebar shows one clean entry that links to the latest version; older versions automatically display a deprecation banner.

Recommended: use the Claude Code skill

The fastest way to add versioning is the /add-api-version Claude Code skill. It automates the entire process — finding the file, creating the folder structure, updating frontmatter, and verifying the build.

How to use it

Open Claude Code in the hyperdocs repository.
Type /add-api-version.
Answer three questions:
- Which API? — paste a URL (e.g., https://docs.hyperverge.co/API-documentation/USA%20APIs/usa_clear_api), URL path, or file path.
- New version number — e.g., 2, 3.
- New version content — provide it yourself, or ask to copy the previous version as a starting point.
The skill handles everything — locating the file, creating versioned folders, updating frontmatter, and running npm run build to verify.

What the skill does automatically

Checks if the ApiVersionSelector component and sidebar CSS exist (creates them if missing).
Converts a single .md file into the versioned folder structure.
Sets up correct frontmatter, doc IDs, _category_.json, and redirect page.
Handles spaces in folder names (%20 encoding) correctly.
Runs a build to catch errors before you push.

After the skill completes, verify in the browser (npm start), then commit, push, and create a PR to the dev branch.

Manual approach

If you prefer to do it manually or need to understand what the skill does under the hood, follow the steps below.

Prerequisites

Git access to the hvlabs/hyperdocs repository.
Node.js installed (to build and test locally).
Basic familiarity with Markdown and YAML frontmatter.
The versioning component is already in the dev branch — no component code changes needed.

Understanding the folder structure

The docs folder uses numbered prefixes on folder names to control sidebar ordering. For example:

docs/
  8-API documentation/
    1-India APIs/
    2-Global APIs/
    3-USA APIs/
      my_api.md           <-- a typical single-version API page

The numbers (8-, 3-, etc.) only affect ordering — Docusaurus strips them from URLs and doc IDs. So 8-API documentation/3-USA APIs/ becomes the URL path /API documentation/USA APIs/.

warning

Docusaurus preserves spaces in folder names as %20 in URLs — it does NOT convert them to hyphens. So the URL is /API%20documentation/USA%20APIs/, not /API-documentation/USA-APIs/.

When you add versioning, the single file becomes a folder:

docs/8-API documentation/3-USA APIs/
  My API/                    <-- new folder for the versioned API
    _category_.json          <-- controls the sidebar entry
    index.md                 <-- redirects base URL to latest version
    v1/
      index.md               <-- full v1 documentation
    v2/
      index.md               <-- full v2 documentation

warning

When referencing doc IDs (e.g., in _category_.json), always strip the numeric prefixes. Use API documentation/USA APIs/... not 8-API documentation/3-USA APIs/.... Getting this wrong causes a build error.

Scenario A: adding versioning to a single-version API

Use this when an API currently exists as a single .md file and you need to introduce a v2.

Step 1 — create a branch

git checkout dev
git pull origin dev
git checkout -b feature/<api-name>-versioning

Step 2 — create the version folders

mkdir -p "docs/8-API documentation/3-USA APIs/My API/v1"
mkdir -p "docs/8-API documentation/3-USA APIs/My API/v2"

Replace 3-USA APIs with whatever region your API lives under. The folder name My API becomes part of the URL, so use a clean readable name.

Step 3 — move the existing doc into v1

mv "docs/8-API documentation/3-USA APIs/my_api.md" \
   "docs/8-API documentation/3-USA APIs/My API/v1/index.md"

Step 4 — update the v1 frontmatter

Open v1/index.md and replace its frontmatter with:

---
title: 'My API Name'
hide_title: true
sidebar_label: 'v1'
sidebar_class_name: api-version-item
tags: ['usa-apis', 'my-api']
api_versioned: true
api_version: '1'
api_latest_version: '2'
api_versions:
  - version: '1'
    label: 'v1'
  - version: '2'
    label: 'v2 (Latest)'
---

Keep any existing fields like tags from the original frontmatter.

Notes:

title sets the browser tab title.
hide_title: true prevents Docusaurus from rendering a second H1 (the markdown already has one).
sidebar_class_name: api-version-item hides this page from the sidebar (the sidebar entry comes from _category_.json instead).

Step 5 — add the version components

Right after the frontmatter ---, add the imports and component tags. The final structure of the top of the file should look like:

---
(frontmatter)
---
import ApiVersionSelector, { ApiDeprecationBanner } from '@site/src/components/ApiVersionSelector/ApiVersionSelector';

<ApiVersionSelector/>

# My API Name

<ApiDeprecationBanner/>

(rest of the document content...)

note

If your API doc already uses Tabs, TabItem, or Admonition, keep those imports — they're not related to versioning but may be needed by your content.

The order matters:

<ApiVersionSelector /> goes before the H1 heading — it floats right to appear inline with the title.
<ApiDeprecationBanner /> goes after the H1 heading — it shows a warning banner on older versions.

Step 6 — create the v2 page

Copy v1/index.md to v2/index.md and replace the content with your new version's documentation. Change just two frontmatter fields:

api_version: '2' (instead of '1')
sidebar_label: 'v2 (Latest)' (instead of 'v1')

Everything else in the frontmatter stays identical across all versions.

Step 7 — create `_category_.json`

Create this file in the API folder root (My API/_category_.json). It controls the sidebar entry:

{
  "label": "My API Name",
  "position": 2,
  "link": {
    "type": "doc",
    "id": "API documentation/USA APIs/My API/v2/index"
  },
  "collapsible": false
}

position — set this to the original file's numeric prefix (e.g., if the file was 2-my_api.md, use 2) so the sidebar order is preserved. Omit if the original file had no numeric prefix.
collapsible: false — prevents the expand/collapse chevron from showing. The hidden child pages won't appear.
The doc id must NOT include numeric prefixes. Use API documentation/USA APIs/... not 8-API documentation/3-USA APIs/....

Step 8 — create the redirect page

Create My API/index.md (alongside _category_.json). This redirects anyone who visits the base API URL to the latest version:

---
sidebar_class_name: api-version-hidden
pagination_next: null
pagination_prev: null
---

import { Redirect } from '@docusaurus/router';

<Redirect to="/API%20documentation/USA%20APIs/My%20API/v2/"/>

warning

Build the redirect URL from the filesystem folder names (with numeric prefixes stripped), not the production site URL. Docusaurus preserves spaces as %20 in URLs — it does NOT convert them to hyphens. For example, 8-API documentation → API%20documentation, not API-documentation.

Step 9 — clean up

Delete the original file — its content now lives at v1/index.md:
```
git rm "docs/8-API documentation/3-USA APIs/my_api.md"
```
Update the region's index page — if USA APIs/index.md lists links to individual APIs, update the link for this API to point to the new versioned path. Remove any duplicate entries if old versions were listed separately.

Scenario B: adding a new version to an already-versioned API

Use this when an API already has version folders (v1/, v2/) and you need to add v3.

Step 1 — create the new version folder and page

mkdir -p "docs/8-API documentation/3-USA APIs/My API/v3"

Create v3/index.md with your new content. You can copy an existing version as a starting point.

In the frontmatter, set:

api_version: '3'
sidebar_label: 'v3 (Latest)'
api_latest_version: '3'
Add the new version to the api_versions array.

Step 2 — update ALL existing version pages

This is the most important step. Open every existing version page (v1/index.md, v2/index.md) and update:

api_latest_version → change to '3'.
api_versions → add the new v3 entry to the array.
On the previous latest version's page, change sidebar_label from 'v2 (Latest)' to just 'v2'.

The api_versions array and api_latest_version must be identical across all version pages. Only api_version and sidebar_label differ.

Step 3 — update `_category_.json`

Change the doc id to point to the new latest version:

"id": "API documentation/USA APIs/My API/v3/index"

Step 4 — update the redirect page

In My API/index.md, change the redirect target from /v2/ to /v3/.

Verify your changes

Before pushing, always build and test locally:

npm run build

If the build fails with a "no document found" error, check that your _category_.json doc ID doesn't include numeric prefixes.

Then start the dev server:

npm start

Check these things in the browser:

Sidebar shows a single entry for the API (no version sub-items visible).
Clicking the sidebar entry opens the latest version.
Version dropdown appears to the right of the page title.
Switching versions via dropdown navigates correctly.
Older versions show the deprecation banner.
Browser tab title shows the API name (not "index").

note

The dev server may show unlisted pages in the sidebar that are hidden in production. This is expected Docusaurus behaviour — always verify with npm run build if unsure.

Submit for review

Commit your changes:

git add .
git commit -m "Add API versioning for <API Name>"

Push and create a PR targeting the dev branch:

git push -u origin feature/<api-name>-versioning

Request a review from the Technical Writers team. In your PR description, mention which API was versioned, what versions are included, and share the local preview URLs you tested.

Troubleshooting

Build error: "no document found for ID…" The doc ID in _category_.json includes numeric prefixes. Remove them — use API documentation/USA APIs/... not 8-API documentation/3-USA APIs/....

Build error: "Module not found: ApiVersionSelector" The component hasn't been added to the repository yet. Check that src/components/ApiVersionSelector/ApiVersionSelector.js exists on your branch. It should be in the dev branch already.

Sidebar shows version sub-items (v1, v2) under the API Every version page needs sidebar_class_name: api-version-item in its frontmatter. The redirect index.md needs sidebar_class_name: api-version-hidden.

Sidebar entry missing entirely The CSS selector .theme-doc-sidebar-item-link.api-version-item targets only leaf sidebar links. If _category_.json uses collapsible: true instead of collapsible: false, the parent category may also get hidden. Set collapsible: false.

API appears at wrong position in sidebar Add a position field to _category_.json matching the original file's numeric prefix.

Version dropdown doesn't appear The component only renders when api_versioned: true and api_versions has 2+ entries. Check your frontmatter.

Deprecation banner appears on the latest version api_version doesn't match api_latest_version on that page. Both must be the same string on the latest version.

Browser tab shows "index | HyperVerge" Add title: 'Your API Name' and hide_title: true to the frontmatter.

Redirect goes to 404 The redirect URL was built from the production site URL (which may use hyphens) instead of the filesystem folder names (which use spaces). Use %20 for spaces: /API%20documentation/... not /API-documentation/....

Frontmatter quick reference

Field	Description
`title`	API name (sets browser tab title).
`hide_title`	Set to `true` (prevents duplicate H1).
`sidebar_label`	e.g., `'v1'` or `'v2 (Latest)'`.
`sidebar_class_name`	Must be `api-version-item`.
`api_versioned`	Must be `true`.
`api_version`	This page's version (`'1'`, `'2'`, etc.) — differs per page.
`api_latest_version`	Latest version number — same across all pages.
`api_versions`	Array of `{version, label}` for the dropdown — same across all pages.

Component: src/components/ApiVersionSelector/ApiVersionSelector.js
Styles: src/components/ApiVersionSelector/ApiVersionSelector.module.css
Sidebar CSS: src/css/custom.css (search for "API Versioning")
Skill: .claude/skills/add-api-version/SKILL.md
Repository: github.com/hvlabs/hyperdocs

Overview​

Recommended: use the Claude Code skill​

How to use it​

What the skill does automatically​

Manual approach​

Prerequisites​

Understanding the folder structure​

Scenario A: adding versioning to a single-version API​

Step 1 — create a branch​

Step 2 — create the version folders​

Step 3 — move the existing doc into v1​

Step 4 — update the v1 frontmatter​

Step 5 — add the version components​

Step 6 — create the v2 page​

Step 7 — create _category_.json​

Step 8 — create the redirect page​

Step 9 — clean up​

Scenario B: adding a new version to an already-versioned API​

Step 1 — create the new version folder and page​

Step 2 — update ALL existing version pages​

Step 3 — update _category_.json​

Step 4 — update the redirect page​

Verify your changes​

Submit for review​

Troubleshooting​

Frontmatter quick reference​

Related files​

Overview

Recommended: use the Claude Code skill

How to use it

What the skill does automatically

Manual approach

Prerequisites

Understanding the folder structure

Scenario A: adding versioning to a single-version API

Step 1 — create a branch

Step 2 — create the version folders

Step 3 — move the existing doc into v1

Step 4 — update the v1 frontmatter

Step 5 — add the version components

Step 6 — create the v2 page

Step 7 — create `_category_.json`

Step 8 — create the redirect page

Step 9 — clean up

Scenario B: adding a new version to an already-versioned API

Step 1 — create the new version folder and page

Step 2 — update ALL existing version pages

Step 3 — update `_category_.json`

Step 4 — update the redirect page

Verify your changes

Submit for review

Troubleshooting

Frontmatter quick reference

Related files