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

Developers can contribute new documentation to Context Hub by creating a properly structured directory with a 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.

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 and SKILL.md under content/ during the build process. According to 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 file with mandatory YAML front-matter. The CLI uses parseFrontmatter in cli/src/lib/frontmatter.js to extract this metadata.

Required Front-Matter Schema

Begin each DOC.md with a YAML block containing these exact fields:

---
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. 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.

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.

Building the Registry

Running a full build generates the registry.json file that powers Context Hub's public CDN and search functionality. You can inspect this output to verify your entry appears correctly.

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 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 automatically executes the build and lint steps. After merge, the pipeline publishes the updated 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 files under content/<author>/docs/<entry-name>/ for proper discovery by 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.
• 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 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 for standard entries or 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 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. The actual parsing implementation resides in 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) automatically runs the full build and publishes the updated 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}