|
| 1 | +# Content Guide |
| 2 | + |
| 3 | +How to author docs and skills for the Chub registry. Whether you're contributing to the public registry or building a private one for your team. |
| 4 | + |
| 5 | +## Directory Structure |
| 6 | + |
| 7 | +Content is organized by author, then by type (`docs` or `skills`), then by entry name: |
| 8 | + |
| 9 | +``` |
| 10 | +my-content/ |
| 11 | + acme/ |
| 12 | + docs/ |
| 13 | + widgets/ |
| 14 | + DOC.md # single-language doc |
| 15 | + references/ |
| 16 | + advanced.md # additional reference file |
| 17 | + client/ |
| 18 | + javascript/ |
| 19 | + DOC.md # multi-language: JS variant |
| 20 | + python/ |
| 21 | + DOC.md # multi-language: Python variant |
| 22 | + api/ |
| 23 | + v1/ |
| 24 | + DOC.md # multi-version: v1 |
| 25 | + v2/ |
| 26 | + DOC.md # multi-version: v2 |
| 27 | + skills/ |
| 28 | + deploy/ |
| 29 | + SKILL.md # a skill |
| 30 | +``` |
| 31 | + |
| 32 | +### Single-language docs |
| 33 | + |
| 34 | +Place `DOC.md` directly in the entry directory: |
| 35 | + |
| 36 | +``` |
| 37 | +author/docs/entry-name/DOC.md |
| 38 | +``` |
| 39 | + |
| 40 | +### Multi-language docs |
| 41 | + |
| 42 | +Create a subdirectory per language: |
| 43 | + |
| 44 | +``` |
| 45 | +author/docs/entry-name/javascript/DOC.md |
| 46 | +author/docs/entry-name/python/DOC.md |
| 47 | +``` |
| 48 | + |
| 49 | +### Multi-version docs |
| 50 | + |
| 51 | +When an API has breaking changes across major versions, create a subdirectory per version: |
| 52 | + |
| 53 | +``` |
| 54 | +author/docs/entry-name/ |
| 55 | + v1/ |
| 56 | + DOC.md # versions: "1.0.0" |
| 57 | + v2/ |
| 58 | + DOC.md # versions: "2.0.0" |
| 59 | +``` |
| 60 | + |
| 61 | +Both `DOC.md` files must share the same `name` in frontmatter. The build groups them into a single registry entry with multiple versions. The highest version becomes the `recommendedVersion`. |
| 62 | + |
| 63 | +You can combine multi-version with multi-language: |
| 64 | + |
| 65 | +``` |
| 66 | +author/docs/entry-name/ |
| 67 | + v1/ |
| 68 | + javascript/DOC.md |
| 69 | + python/DOC.md |
| 70 | + v2/ |
| 71 | + javascript/DOC.md |
| 72 | + python/DOC.md |
| 73 | +``` |
| 74 | + |
| 75 | +### Skills |
| 76 | + |
| 77 | +Place `SKILL.md` in the entry directory: |
| 78 | + |
| 79 | +``` |
| 80 | +author/skills/entry-name/SKILL.md |
| 81 | +``` |
| 82 | + |
| 83 | +### Reference files |
| 84 | + |
| 85 | +Additional files (examples, advanced topics, error references) go alongside the entry file: |
| 86 | + |
| 87 | +``` |
| 88 | +author/docs/widgets/ |
| 89 | + DOC.md |
| 90 | + references/ |
| 91 | + advanced.md |
| 92 | + errors.md |
| 93 | +``` |
| 94 | + |
| 95 | +These are discoverable via `chub get` (shown in the footer) and fetchable with `--file` or `--full`. |
| 96 | + |
| 97 | +## Frontmatter |
| 98 | + |
| 99 | +Every `DOC.md` and `SKILL.md` starts with YAML frontmatter between `---` delimiters. |
| 100 | + |
| 101 | +### DOC.md frontmatter |
| 102 | + |
| 103 | +```yaml |
| 104 | +--- |
| 105 | +name: widgets |
| 106 | +description: "Acme widget API for creating and managing widgets" |
| 107 | +metadata: |
| 108 | + languages: "javascript" |
| 109 | + versions: "2.0.0" |
| 110 | + revision: 1 |
| 111 | + updated-on: "2026-01-01" |
| 112 | + source: maintainer |
| 113 | + tags: "acme,widgets,api" |
| 114 | +--- |
| 115 | +``` |
| 116 | + |
| 117 | +| Field | Required | Description | |
| 118 | +|-------|----------|-------------| |
| 119 | +| `name` | Yes | Entry name (used in the ID: `author/name`) | |
| 120 | +| `description` | Yes | Short description for search results | |
| 121 | +| `metadata.languages` | Yes | Language of this doc variant | |
| 122 | +| `metadata.versions` | Yes | Package/SDK version this doc covers | |
| 123 | +| `metadata.revision` | Yes | Content revision number (starts at 1, increment on update) | |
| 124 | +| `metadata.updated-on` | Yes | Date this content was last revised (`YYYY-MM-DD`) | |
| 125 | +| `metadata.source` | Yes | Trust level: `official`, `maintainer`, or `community` | |
| 126 | +| `metadata.tags` | No | Comma-separated tags for filtering | |
| 127 | + |
| 128 | +### SKILL.md frontmatter |
| 129 | + |
| 130 | +```yaml |
| 131 | +--- |
| 132 | +name: deploy |
| 133 | +description: "Deployment automation skill for CI/CD pipelines" |
| 134 | +metadata: |
| 135 | + revision: 1 |
| 136 | + updated-on: "2026-01-01" |
| 137 | + source: community |
| 138 | + tags: "deploy,ci,automation" |
| 139 | +--- |
| 140 | +``` |
| 141 | + |
| 142 | +Skills have the same fields as docs except `languages` and `versions` are not required (skills are language-agnostic). |
| 143 | + |
| 144 | +## Versioning |
| 145 | + |
| 146 | +### Package version vs API version |
| 147 | + |
| 148 | +The `versions` field refers to the **package/SDK version** (the version on npm or pypi). This is what agents detect from `package.json` or `requirements.txt`. |
| 149 | + |
| 150 | +If a library has a separate API versioning scheme (like Stripe's dated API versions), document that within the content body. The frontmatter `versions` stays as the package version. |
| 151 | + |
| 152 | +### Updating content |
| 153 | + |
| 154 | +When you improve content for the same package version (fix examples, add details, clarify wording): |
| 155 | + |
| 156 | +1. Bump `revision` (e.g., 1 → 2) |
| 157 | +2. Update `updated-on` to today's date |
| 158 | +3. Keep `versions` the same |
| 159 | + |
| 160 | +## Writing Guidelines |
| 161 | + |
| 162 | +Content is markdown, written for LLM consumption: |
| 163 | + |
| 164 | +- **Be direct.** Agents don't need introductions or marketing. Start with what the API does and how to use it. |
| 165 | +- **Show code first.** A working example is worth more than a paragraph of explanation. |
| 166 | +- **Cover the common case.** Don't exhaustively document every option. Cover what agents need 90% of the time. |
| 167 | +- **Use reference files for depth.** Put advanced topics, error handling, and edge cases in separate reference files rather than making the main doc too long. |
| 168 | + |
| 169 | +## Building |
| 170 | + |
| 171 | +```sh |
| 172 | +chub build my-content/ # build to my-content/dist/ |
| 173 | +chub build my-content/ -o dist/ # custom output directory |
| 174 | +chub build my-content/ --validate-only # validate without building |
| 175 | +chub build my-content/ --base-url https://cdn.example.com/v1 # set CDN URL |
| 176 | +``` |
| 177 | + |
| 178 | +The build process: |
| 179 | +1. Discovers all `DOC.md` and `SKILL.md` files |
| 180 | +2. Validates frontmatter (checks required fields) |
| 181 | +3. Generates `registry.json` with entry metadata and `search-index.json` for BM25 search |
| 182 | +4. Copies content files to the output directory |
| 183 | + |
| 184 | +Builds are incremental by default — a SHA-256 manifest skips unchanged files. |
| 185 | + |
| 186 | +### Validation |
| 187 | + |
| 188 | +Run `--validate-only` to check your content without building: |
| 189 | + |
| 190 | +```sh |
| 191 | +chub build my-content/ --validate-only |
| 192 | +``` |
| 193 | + |
| 194 | +## Using built content |
| 195 | + |
| 196 | +Point your config at the build output to use it alongside the public registry: |
| 197 | + |
| 198 | +```yaml |
| 199 | +# ~/.chub/config.yaml |
| 200 | +sources: |
| 201 | + - name: community |
| 202 | + url: https://cdn.aichub.org/v1 |
| 203 | + - name: my-team |
| 204 | + path: /path/to/my-content/dist |
| 205 | +``` |
| 206 | +
|
| 207 | +Now `chub search` and `chub get` cover both public and your local content. |
| 208 | + |
| 209 | +See [Self-Hosting](/guide/self-hosting) for serving your registry over HTTP or deploying to a CDN. |
0 commit comments