# How to Contribute New Documentation to Context Hub: A Step-by-Step Guide

> Learn how developers can contribute new documentation to Context Hub. Follow our step by step guide to structure your documents, validate them locally, and submit a pull request.

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

---

**Developers can contribute new documentation to Context Hub by creating a properly structured directory with a [`DOC.md`](https://github.com/andrewyng/context-hub/blob/main/DOC.md) file containing valid YAML front-matter, validating it locally using the `chub build` CLI command, and submitting a pull request against the `main` branch.**

Context Hub treats documentation as first-class content that compiles into a searchable registry. Whether you are documenting a new API or adding a skill definition, the andrewyng/context-hub repository provides a Node.js-based CLI to validate and build your contributions. This guide walks through the exact workflow, file structures, and validation commands required to submit high-quality documentation.

## Repository Setup and Prerequisites

Before adding content, fork the repository and install dependencies locally. The CLI tools required for validation and building reside in the `cli/` directory.

```bash
git clone https://github.com/andrewyng/context-hub.git
cd context-hub
npm install

```

All documentation must reside under the `content/` directory, following a strict author-based hierarchy that the build system discovers automatically.

## Directory Structure and Content Organization

Context Hub enforces a specific layout to ensure the CLI can discover and catalog entries correctly.

### The Author/Type/Entry Layout

Create your content following this exact pattern:

```

content/
  <author>/
    docs/
      <entry-name>/
        DOC.md                    # Required main documentation

        references/               # Optional supplementary files

          advanced.md
    skills/
      <skill-name>/
        SKILL.md                  # Skill definition file

```

The registry compiler scans every [`DOC.md`](https://github.com/andrewyng/context-hub/blob/main/DOC.md) and [`SKILL.md`](https://github.com/andrewyng/context-hub/blob/main/SKILL.md) under `content/` during the build process. According to [`docs/content-guide.md`](https://github.com/andrewyng/context-hub/blob/main/docs/content-guide.md), this structure ensures consistent routing and metadata association for the public lookup service.

## Creating Documentation Files

Every documentation entry requires a [`DOC.md`](https://github.com/andrewyng/context-hub/blob/main/DOC.md) file with mandatory YAML front-matter. The CLI uses `parseFrontmatter` in [`cli/src/lib/frontmatter.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/frontmatter.js) to extract this metadata.

### Required Front-Matter Schema

Begin each [`DOC.md`](https://github.com/andrewyng/context-hub/blob/main/DOC.md) with a YAML block containing these exact fields:

```yaml
---
name: my-api
description: Short description of what this doc covers
metadata:
  languages: "python,javascript"
  versions: "1.0.0"
  revision: 1
  updated-on: "2026-02-22"
  source: community
  tags: "api,rest"
---

```

**Required fields** include `name`, `description`, `languages`, `versions`, `revision`, `updated-on`, and `source`. The build system validates these keys against the schema defined in [`docs/content-guide.md`](https://github.com/andrewyng/context-hub/blob/main/docs/content-guide.md). Missing or malformed front-matter causes the CLI to exit with an error pointing to the specific file.

## Validating Changes Locally

Always validate your documentation before opening a pull request. The `--validate-only` flag checks front-matter schema compliance without generating the full registry.

```bash
node cli/bin/chub build content/<author>/ --validate-only

```

A successful validation outputs: `Validated 1 doc, 0 skills`. If validation fails, the CLI references the offending file and the specific missing key, allowing you to fix errors before submission as noted in [`CONTRIBUTING.md`](https://github.com/andrewyng/context-hub/blob/main/CONTRIBUTING.md).

## Building the Registry

Running a full build generates the [`registry.json`](https://github.com/andrewyng/context-hub/blob/main/registry.json) file that powers Context Hub's public CDN and search functionality. You can inspect this output to verify your entry appears correctly.

```bash
node cli/bin/chub build content/<author>/ -o temp-dist/
cat temp-dist/registry.json | jq '.["<author>/<entry-name>"]'

```

The build logic in [`cli/src/lib/registry.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/registry.js) discovers your files, validates the metadata, and writes the structured JSON used by `chub search` and `chub get` commands. Verify that your entry includes the correct `metadata` and `recommendedVersion` fields in the output.

## Submitting Your Contribution

Once local validation passes, complete the following steps to submit your documentation:

1. **Create a feature branch** from `main` with a descriptive name like `docs/<author>-<entry>`.
2. **Add your content directory** under `content/<author>/` following the layout rules above.
3. **Run the test suite** using `npm test` to ensure no regressions exist in the CLI logic.
4. **Push and open a PR** against the `main` branch.

The CI workflow defined in [`.github/workflows/ci.yml`](https://github.com/andrewyng/context-hub/blob/main/.github/workflows/ci.yml) automatically executes the build and lint steps. After merge, the pipeline publishes the updated [`registry.json`](https://github.com/andrewyng/context-hub/blob/main/registry.json) to the CDN, making your documentation instantly available via `chub search` and `chub get` commands worldwide.

## Summary

- **Directory structure matters**: Place [`DOC.md`](https://github.com/andrewyng/context-hub/blob/main/DOC.md) files under `content/<author>/docs/<entry-name>/` for proper discovery by [`cli/src/lib/registry.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/registry.js).
- **Front-matter is mandatory**: Include all required YAML fields (`name`, `description`, `metadata` sub-fields) validated by `parseFrontmatter` in [`cli/src/lib/frontmatter.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/frontmatter.js).
- **Validate locally first**: Use `node cli/bin/chub build <path> --validate-only` to catch schema errors before submitting your pull request.
- **Test before PRs**: Run `npm test` and the full build command to ensure [`registry.json`](https://github.com/andrewyng/context-hub/blob/main/registry.json) generates correctly and passes CI checks.

## Frequently Asked Questions

### What file naming conventions does Context Hub require?

You must name the main documentation file [`DOC.md`](https://github.com/andrewyng/context-hub/blob/main/DOC.md) for standard entries or [`SKILL.md`](https://github.com/andrewyng/context-hub/blob/main/SKILL.md) for skill definitions. The CLI specifically searches for these filenames during the build process. Optional reference files can use any name but should reside in a `references/` subdirectory adjacent to the main file.

### How do I validate my documentation before submitting a PR?

Run the validation command using the CLI entry point at `cli/bin/chub` with the `--validate-only` flag. This executes the schema checks from [`cli/src/lib/frontmatter.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/frontmatter.js) without writing output files. If your front-matter is missing required keys like `updated-on` or `source`, the CLI exits with a descriptive error pointing to the specific line in your file.

### Where is the front-matter schema defined?

The complete schema specification, including required fields and valid values for the `source` and `languages` keys, is documented in [`docs/content-guide.md`](https://github.com/andrewyng/context-hub/blob/main/docs/content-guide.md). The actual parsing implementation resides in [`cli/src/lib/frontmatter.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/frontmatter.js), which extracts and validates the YAML block using the rules defined in that guide.

### What happens after my PR is merged?

Once merged into `main`, the GitHub Actions workflow ([`.github/workflows/ci.yml`](https://github.com/andrewyng/context-hub/blob/main/.github/workflows/ci.yml)) automatically runs the full build and publishes the updated [`registry.json`](https://github.com/andrewyng/context-hub/blob/main/registry.json) to Context Hub's CDN. Your documentation becomes immediately searchable using `chub search <entry-name>` and retrievable via `chub get <author>/<entry-name>`, making it available to agents and developers globally.