# How Context Hub Handles Version-Specific Documentation: Complete Technical Guide

> Learn how Context Hub handles version specific documentation by parsing SDK versions into a unified registry and resolving them at runtime. Explore the complete technical guide.

- Repository: [Andrew Ng/context-hub](https://github.com/andrewyng/context-hub)
- Tags: deep-dive
- Published: 2026-03-20

---

**Context Hub treats every package SDK version as a first-class dimension by parsing version declarations from front-matter, merging them into a unified registry structure, and resolving specific or latest versions at runtime through the `resolveDocPath` function.**

The `andrewyng/context-hub` repository implements a sophisticated version resolution system that allows documentation authors to maintain separate guides for different SDK releases while giving CLI users seamless access to the correct content. This architecture ensures that agents and developers always receive documentation matching their installed package version.

## Declaring Versions in Front-Matter

Documentation authors specify supported package versions directly in the [`DOC.md`](https://github.com/andrewyng/context-hub/blob/main/DOC.md) front-matter using the `metadata.versions` field (or the shorthand `versions` key). This comma-separated list declares which SDK versions the document covers.

```yaml
name: openai/chat
description: Python SDK for OpenAI Chat
metadata:
  languages: python
  versions: 2.0.0,1.0.0

```

During the `chub build` process, the build script expands this declaration into an array of structured objects containing the version string, file path, and associated files. Each version maps to a distinct directory structure, isolating version-specific content at the filesystem level.

## How the Registry Indexes Multiple Versions

The registry system in [`cli/src/lib/registry.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/registry.js) (lines 73-78, 150-158) merges all [`DOC.md`](https://github.com/andrewyng/context-hub/blob/main/DOC.md) files sharing the same `name` into a single entry containing a `languages[]` array. Each language object maintains its own independent `versions[]` array.

```json
{
  "id": "openai/chat",
  "languages": [
    {
      "language": "python",
      "versions": [
        { "version": "2.0.0", "path": "openai/chat/python/v2", "files": [] },
        { "version": "1.0.0", "path": "openai/chat/python/v1", "files": [] }
      ],
      "recommendedVersion": "2.0.0"
    }
  ]
}

```

The build process automatically calculates the **highest semver** across all versions and stores it as `recommendedVersion`, ensuring the CLI can default to the latest stable documentation when users omit specific version flags.

## Resolving Versions at Runtime

The core version resolution logic resides in `resolveDocPath()` within [`cli/src/lib/registry.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/registry.js) (lines 504-518). This function accepts an entry, language, and optional version parameter, then returns the precise path to the correct documentation files.

```js
export function resolveDocPath(entry, language, version) {
  const lang = language ? normalizeLanguage(language) : null;
  
  // Language lookup logic omitted for brevity...
  
  if (version) {
    // User supplied a version flag
    verObj = langObj.versions?.find(v => v.version === version);
    if (!verObj) {
      return {
        versionNotFound: true,
        requested: version,
        available: langObj.versions?.map(v => v.version) || [],
      };
    }
  } else {
    // No flag → use the recommended (latest) version
    const rec = langObj.recommendedVersion;
    verObj = langObj.versions?.find(v => v.version === rec) || langObj.versions?.[0];
  }
  // Return resolved path...
}

```

### Automatic Latest Version Selection

When users run `chub get openai/chat` without specifying `--version`, the CLI automatically selects `recommendedVersion` (or falls back to the first version in the array if the field is missing). This guarantees that agents receive the most current documentation without manual version management.

### Handling Missing Version Requests

If a user requests a version that does not exist (e.g., `--version 9.9.9`), `resolveDocPath` returns a `versionNotFound` payload containing the requested string and an array of available versions. The `get` command in [`cli/src/commands/get.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/get.js) (lines 47-52) catches this result and surfaces a user-friendly error:

```js
if (resolved.versionNotFound) {
  error(
    `Version "${resolved.requested}" not found for "${id}". ` +
    `Available versions: ${resolved.available.join(', ')}`,
    globalOpts
  );
}

```

## Multi-Language Version Independence

Context Hub supports **per-language version lists**, enabling scenarios where Python SDK v2.0.0 coexists with JavaScript SDK v1.5.0 under the same documentation entry. The resolver first selects the language slice using the `--lang` flag, then searches for the version within that language's specific `versions[]` array (lines 492-505 in [`cli/src/lib/registry.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/registry.js)).

```bash

# Get Python v1.0.0 specifically

chub get openai/chat --lang python --version 1.0.0

# Get JavaScript latest (might be different version number)

chub get openai/chat --lang javascript

```

## Skills vs. Docs: Version-Agnostic Content

According to [`docs/design.md`](https://github.com/andrewyng/context-hub/blob/main/docs/design.md) (lines 49-55), **Skills** represent a distinct content type that lacks both `languages` and `versions` fields. When retrieving skills via `chub get`, the CLI silently ignores `--lang` and `--version` flags, treating the content as universally applicable regardless of SDK version or programming language.

## Summary

- **Front-matter driven**: Authors declare supported versions using comma-separated `metadata.versions` in [`DOC.md`](https://github.com/andrewyng/context-hub/blob/main/DOC.md) files.
- **Registry aggregation**: The build process merges versioned docs into a unified entry with `languages[].versions[]` structures and calculates `recommendedVersion` from semver comparisons.
- **Smart resolution**: The `resolveDocPath()` function in [`cli/src/lib/registry.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/registry.js) handles both explicit version requests and automatic latest-version fallback.
- **Graceful errors**: When a requested version does not exist, the CLI returns a clear message listing all available versions instead of failing silently.
- **Cross-language flexibility**: Each programming language maintains independent version lists, supporting divergent release cycles across SDKs.

## Frequently Asked Questions

### How do I specify multiple versions for a single documentation entry?

Add a comma-separated list to the `versions` key in your [`DOC.md`](https://github.com/andrewyng/context-hub/blob/main/DOC.md) front-matter. During `chub build`, the system expands this into distinct version objects within the registry, each pointing to its own directory path.

### What happens if I request a version that doesn't exist?

The CLI prints a specific error message listing the available versions. The `resolveDocPath` function returns a `versionNotFound` object containing the requested version and an array of valid alternatives, which the `get` command renders as: `Version "9.9.9" not found for "openai/chat". Available versions: 2.0.0, 1.0.0`.

### Does Context Hub support different version numbers for different programming languages?

Yes. Each language slice within a registry entry maintains its own `versions[]` array. This allows Python documentation to track versions `2.0.0` and `1.0.0` while JavaScript documentation simultaneously tracks `2.0.0` and `1.5.0`, with independent `recommendedVersion` values for each language.

### Are skills version-specific like SDK documentation?

No. Skills are version-agnostic by design. They lack both `languages` and `versions` fields in the registry schema, and the CLI ignores `--version` and `--lang` flags when retrieving them, as documented in [`docs/design.md`](https://github.com/andrewyng/context-hub/blob/main/docs/design.md).