catalog.config.json configures one @ocx-sh/catalog deployment: data
sources, branding, nav, and CI rendering. Validation is hand-rolled in
src/config/load.ts, not ajv-driven; src/config/schema/catalog.config.schema.json
is a published sibling artifact for editor tooling, kept in sync with the
loader but not read by it at runtime. This page transcribes both, and notes
every place they diverge.
Top-level fields
Section titled “Top-level fields”| Field | Type | Required | Default | Meaning |
|---|---|---|---|---|
$schema |
string | no | none | Editor/tooling pointer at the published JSON Schema. Never read at runtime. |
configVersion |
number, const 1 |
no | 1 |
Forward-compat discriminator. |
sources |
array of source entry, minItems: 1 |
yes | — | One or more index sources this catalog renders. |
brand |
object | yes, except under chrome: "ocx" |
— | Site branding: title, wordmark, logo. Rejected under chrome: "ocx". |
nav |
array of nav entry | no | none (no extra links) | Extra top-nav links, rendered after the docs entries when docs is set. Links starting with / are joined onto base. Rejected under chrome: "ocx". |
footer |
object | no | none (only the catalog json link) |
Footer links. A dedicated key, not a reuse of nav[]. Links starting with / are joined onto base. Rejected under chrome: "ocx". |
docs |
string | no | none (no docs mount) | Single docs directory, resolved relative to the config file’s directory. Must stay inside it. Mounted at <base>docs/. See Docs mount. |
docsNav |
array of nav entry | no | one auto entry labelled docs at /docs/ |
Labelled entries for the docs-mount link(s) in the top nav, replacing that single auto entry. Requires docs to be set. Every link must be /docs/ or start with it, and is joined onto base. |
css |
string | no | none | Custom stylesheet, resolved relative to the config file’s directory. Must stay inside it. The build bundles it with the theme’s styles, so it ships as a minified, content-hashed file under _astro/ and is linked from every page. A missing file fails the build with exit 65. It wins over the theme because every theme rule sits in a cascade layer. It has no stable selector contract. See Stylesheet. |
publicDir |
string | no | none (no public assets copied) | Static assets directory, resolved relative to the config file’s directory; must stay inside it. Copied verbatim into the site’s public root, served at base. Its top-level entries become reserved names. |
ci |
object | no | none | CI workflow rendering configuration for ocx-catalog ci. |
siteUrl |
string | no | none (no sitemap, no og:url) |
Deployment URL (e.g. https://index.ocx.sh). Must be an absolute http(s) URL. Enables sitemap-index.xml, canonical and og:url tags, and a default robots.txt. A path in it is the default for base. |
ownerUrl |
string | no | https://github.com/{login} |
Owner-profile link template for the package page’s owners row: an absolute http(s) URL containing {login} exactly once, e.g. https://gitlab.com/{login} (a self-hosted GitLab/Gitea works the same). The index does not say which forge its owner logins belong to, so this is deployment config. The login is URL-encoded into the template. |
description |
string | no | none | Site-wide tagline/meta description, distinct from brand.title. |
favicon |
string | no | none (no icon link) | Href for the browser-tab icon. Either a catalog-root-relative path (e.g. /favicon.svg), joined onto base in the page, or an absolute http(s) URL, used as written. The build never reads the file, so it may come from publicDir, brand.logo, or from the host or a CDN. A //host value, a bare or relative file name, a javascript: value and any path with a dot segment fail with INVALID_TYPE. |
base |
string | no | the path of siteUrl, else / |
URL path prefix the site is served under. See base. |
chrome |
"neutral" | "ocx" |
no | "neutral" |
Experimental. Page chrome. See chrome. |
Every string field above (and every string field in every sub-object below)
carries minLength: 1 in the schema; the loader mirrors this by rejecting an
empty string as INVALID_TYPE — use an absent/optional key for “unset”,
never "".
Unknown keys are hard errors. Any key at the top level not in the table
above throws UNKNOWN_KEY, naming the offending key. The same closed-shape
check applies to each sources[] entry (against its own discriminant
variant’s key set), to brand, to footer, and to each nav[]/
footer.links[]/docsNav[] entry. ci is the one
documented exception: unknown keys inside ci are accepted and passed
through unmodified, because rendered-workflow configuration is expected to
grow tunables this loader doesn’t know about yet, and a config author using
a newer field shouldn’t be blocked from loading at all — only the CI
renderer itself would need to understand a new key.
configVersion: absent is treated as 1. Any other value fails loudly
at load with UNSUPPORTED_VERSION — checked before the unknown-key scan,
so a config written for a version this loader doesn’t support reports the
version mismatch, not a confusing UNKNOWN_KEY about a field it doesn’t
recognize yet.
| Field | Type | Required | Default | Meaning |
|---|---|---|---|---|
title |
string | yes | — | Site <title> and og:site_name. |
wordmark |
string | no | falls back to title in the header |
Header wordmark — the text beside the logo/mark. Exists because the two are legitimately different strings (a <title> reads as prose, a wordmark is usually the deployment’s own host). |
logo |
string, local path only | no | the built-in OCX mark | Logo asset, resolved relative to the config file’s directory. Must stay inside it (PATH_ESCAPE otherwise). Copied into the site’s public root under its file name and rendered in the header in place of the built-in OCX mark. Its file name becomes a reserved name. |
brand is closed: any key other than title/wordmark/logo is
UNKNOWN_KEY.
| Field | Type | Required | Meaning |
|---|---|---|---|
text |
string | yes | Visible label for this nav entry. |
link |
string | yes | Target href. |
nav[].link must be an absolute http(s) URL, or a path starting with /
that resolves back onto this site’s own origin. A path never starts with //,
which is protocol-relative. The check parses the value with the real WHATWG
URL constructor instead of matching the string. A plain startsWith("/")
check would accept an open-redirect shape such as /\evil.example, or a value
with a stripped control character. A spec-conformant parser resolves both to a
different origin.
A javascript: or data: value, or any link that escapes the site’s own
origin, is rejected at config load. It is not only sanitized at render time.
This config can be authored in a fork pull request for a corporate mirror. The
theme’s header and footer components render the value as an href, so there is
no second line of defense at render time.
A link with a dot segment (., .. or an encoded %2e) is rejected at load,
because the renderer cannot join it onto base. A link that starts with / is
joined onto base when the page renders.
Write it relative to the catalog root, such as /status, and it becomes
/catalog/status under "base": "/catalog/". Absolute http(s) links are
left as written.
nav entries are closed: any key other than text/link is UNKNOWN_KEY.
footer
Section titled “footer”{ "footer": { "links": [{ "text": "Status", "link": "/status" }] } }| Field | Type | Required | Meaning |
|---|---|---|---|
links |
array of nav entry | yes | Footer links, same shape and assertSafeNavLink validation as nav[]. |
footer is closed: any key other than links is UNKNOWN_KEY. A mirror that
configures nav[] for its header does not get those links repeated in its
footer. It needs its own footer.links[]. The footer always carries a
catalog json link to the site’s own view model, and footer.links[] follows it.
Omitting footer leaves that one link.
docsNav[]
Section titled “docsNav[]”{ "docs": "./docs", "docsNav": [ { "text": "setup", "link": "/docs/setup/" }, { "text": "reference", "link": "/docs/reference/" } ]}| Field | Type | Required | Meaning |
|---|---|---|---|
text |
string | yes | Visible label for this docs-nav entry. |
link |
string | yes | Target href — must be /docs/ or start with it. |
Two rules on top of nav[]’s own text/link shape and
assertSafeNavLink validation (both reuse the same buildNavEntry builder,
not a second implementation):
- Every
docsNav[].linkmust be/docs/or start with/docs/— anything else is anav[]entry with extra steps, not a label for the docs mount.INVALID_TYPEotherwise. docsNavpresent withoutdocsconfigured isINVALID_TYPE— it would point at a mount that doesn’t exist.
Omitting docsNav (with docs set) gives one auto entry labelled docs
pointing at /docs/. That link leads to a page only when the docs tree has a
docs/index.md, so name real pages in docsNav if it has none. Each link is
joined onto base.
| Field | Type | Required | Default | Meaning |
|---|---|---|---|---|
forge |
"github" | "gitlab" |
yes | — | Target CI forge for the rendered workflow. |
packageManager |
"npm" | "bun" |
no | see note below | Package manager the rendered workflow’s install/exec steps use. pnpm/yarn are unsupported — a value outside the two is a loud config-load error rather than a silently broken rendered workflow. |
verifyCi |
boolean | no | none | When false, skips CI verification of rendered output against source data. |
ci is the one open object in the whole config shape: unlike every
other object here, unknown keys inside it are ignored rather than rejected
(see the top-level section above for why).
sources[]
Section titled “sources[]”Every entry is discriminated by exactly one of path | url | git; the
schema expresses this as a closed oneOf over three shapes, and the loader
enforces the same rule at runtime (SOURCE_DISCRIMINANT on zero or more
than one discriminant key present). Five fields are common to every variant:
| Field | Type | Required | Meaning |
|---|---|---|---|
label |
string | no | The index’s public name — shown by the catalog’s index-scope tabs, and the first /-segment of every package name this source publishes. Must be unique across sources[] (LABEL_CONFLICT) and must match that segment (LABEL_PREFIX_MISMATCH): a label may restate the name an index gives itself, never rename it. When absent it is derived from the source’s own data; loadConfig never invents a label itself. |
root |
boolean | no | Marks this source as the catalog’s self-mirror, served at the site root in addition to index/<label>/. Its packages keep bare /<ns>/<pkg> routes; every other index’s are qualified with their own name. At most one entry across sources[] may set this — MULTIPLE_ROOT otherwise. |
default |
boolean | no | Marks this source as the index the catalog view opens on — preselected on arrival, badged default in the scope tabs. Purely presentational: it moves no page’s URL. At most one entry may set this — MULTIPLE_DEFAULT otherwise. When no entry sets it, the root: true source (if any) is the default; a catalog with no root source needs this key to name one at all. |
excludeFromAll |
boolean | no | Keeps this source’s packages out of the catalog’s all tab — the grid, table, filters, keyword rail and the tab’s own count — for a development or staging index. The index still gets its own tab, and its packages stay in the catalog and keep their pages and routes. The command palette (⌘K) is not affected: it searches every index. Absent or false includes the index. Independent of root and default. On a one-index catalog there is no all tab, so the flag has no effect there; if every index of an aggregating catalog sets it, all is simply empty. |
ownerUrl |
string | no | Owner-profile link template for this source’s package pages, overriding the top-level ownerUrl — same shape and validation (an absolute http(s) URL containing {login} exactly once). For an aggregating catalog whose indexes’ owners live on different forges. Absent: the top-level ownerUrl, else https://github.com/{login}. |
| Field | Type | Required | Meaning |
|---|---|---|---|
path |
string | yes | Local directory read as the index root, resolved relative to the config file’s directory. Must stay inside it (PATH_ESCAPE otherwise). |
| Field | Type | Required | Meaning |
|---|---|---|---|
url |
string, pattern ^https:// |
yes | Base URL of a deployed catalog/index instance. https only — /config.json and /c/index.json are the only fetched files never digest-verified, so over plain http a network attacker could rewrite the enumeration and every downstream digest check would then pass against the attacker’s own digests. |
The schema’s pattern is a shape heuristic, anchored only at the start
of the string. The loader’s own check (assertPlausibleUrl) is
authoritative: it parses the value with new URL() and rejects anything
whose protocol isn’t literally https:.
| Field | Type | Required | Meaning |
|---|---|---|---|
git |
string | yes | Git remote to clone (shallow, depth 1). |
ref |
string | no | Branch, tag, or commit to check out. Defaults to the remote’s HEAD. |
dir |
string | no | Subdirectory within the checkout that holds the index root. |
Cross-entry rules
Section titled “Cross-entry rules”| Rule | Error code | Expressed in the JSON Schema? |
|---|---|---|
sources must be non-empty |
EMPTY_SOURCES |
yes (minItems: 1) |
Each entry sets exactly one of path/url/git |
SOURCE_DISCRIMINANT |
yes (oneOf over three closed shapes) |
At most one entry may set root: true |
MULTIPLE_ROOT |
yes (contains/minContains: 0/maxContains: 1) |
At most one entry may set default: true |
MULTIPLE_DEFAULT |
yes (same shape — both live inside allOf, since one schema object can hold only one contains) |
Two entries must not declare the same explicit label |
LABEL_CONFLICT |
no — array-element uniqueness keyed on an optional field isn’t expressed in the schema at all; loader-only |
base is the URL path prefix the site is served under. It is a leading and
trailing / with segments of letters, digits, ., _ and -. No segment may
be . or ... Valid values are / and /catalog/. The schema expresses the
shape as a pattern, and the loader checks it again.
{ "base": "/catalog/", "siteUrl": "https://ocx.sh/catalog/" }The default comes from siteUrl. When siteUrl carries a path, that path is
the base. When it is an origin only, or absent, the default is /. An
explicit base beside an origin-only siteUrl is always legal.
When both carry a path, they must be equal. The schema cannot compare two fields, so only the loader enforces this.
What base changes in the output:
- Every page link, asset URL and client-side data fetch carries the prefix.
nav[],footer.links[]anddocsNav[]links that start with/are joined onto it.faviconis joined onto it when a page links it, and so is every asset thecssbundle references.- Every pattern in
_headersis prefixed with it. ocx-catalog devserves under it.
The files themselves land at the same paths under --out for every base.
Your host decides where that tree is mounted. See
Output layout and Hosting and headers.
chrome
Section titled “chrome”chrome selects the page header and footer.
| Value | Header and footer | brand |
nav, footer, docsNav |
|---|---|---|---|
"neutral" (default) |
The mirror’s own, from brand, nav, footer and docsNav |
Required | Optional |
"ocx" |
The ocx.sh shell owns both | Rejected | Rejected |
Under "ocx", naming brand, nav, footer or docsNav fails with
CHROME_OCX_CONFLICT. The shell also supplies a favicon.svg at the site root
unless your publicDir ships one. Any value other than the two is
INVALID_TYPE.
Docs mount
Section titled “Docs mount”docs points at a directory of Markdown that the build mounts at
<base>docs/. The mount follows these rules:
- Only
**/*.mdfiles are mounted..mdxfiles and dot-files are skipped. - The page URL is the path without
.md, soguide/install.mdbecomes<base>docs/guide/install/. Anindex.mdserves its directory, sodocs/index.mdis<base>docs/andguide/index.mdis<base>docs/guide/. Two files that map to one route, such asfoo.mdandfoo/index.md, fail the build. - Each path segment may use letters, digits,
-,_and.. Anything else fails the build with exit65. - Frontmatter that is not valid YAML fails the build with exit
65. - Frontmatter
title(a string) names the page. Without it, the text of the page’s first#heading does, else the file name. - Frontmatter
description(a string) is the page’s meta description. - Frontmatter
order(a number) sorts the page in the sidebar. Pages without one sort last. - The sidebar groups pages by directory. A group heading links to the
directory’s
index.md. Groups sort by theorderof that index page, then by path. Pages sort byorder, then title. - VitePress-only syntax is not interpreted.
::: detailsblocks and{#id}heading anchors render as plain text. - Fenced code blocks are syntax-highlighted.
- Headings get generated ids. Link to those ids, not to a custom anchor.
- Links to pages are rewritten. A relative link, with or without
.md, resolves against its own file and becomes a directory route underbase.index.mdmaps to its directory, and?queryand#fragmentare kept. A root-relative link such as/docs/install/gainsbase. - A relative link or image to another file resolves against its own file and
is served from
<base>docs/. The build copies the tree’s images and downloads there. Markdown sources,.mdxfiles, dot-files and dot-directories are never copied. - A symbolic link in the tree fails the build with exit
65. So does a copied file that would replace a page, or overwrite a file already inpublicDir/docs/. - A link to a page or file that does not exist fails the build.
- External links open in a new tab with
rel="noreferrer". Left as written:mailto:and#fragment-only links. A link in raw HTML (<a href>) is not rewritten. - Every heading gets a permalink anchor.
Docs are trusted content, rendered at build time. Review a docs change like code.
Stylesheet
Section titled “Stylesheet”css is bundled with the theme’s styles, not copied. A relative @import and
a relative url() resolve from the file’s own directory, so a stylesheet can
pull in sibling files, fonts and images. The output is minified and
content-hashed under _astro/, so a changed file gets a new URL. The file must
exist and be a regular file, or the build fails with exit 65.
Every file the stylesheet imports or references must resolve inside the config
directory, symlinks followed. A root-relative or absolute url() counts too. One that
names no file on disk passes, so url(/fonts/x.woff2) stays a link to a
publicDir file.
Anything else fails the build with exit 65 and names the file. dev lets its
server read the whole config directory for this.
The one exception is a bare package name, such as @import "pkg/x.css". It may
resolve into any node_modules, including one above the config directory, as long
as the package is not a symlink pointing outside every node_modules. A relative
path into node_modules, such as @import "../node_modules/pkg/x.css", gets no
such exception.
Every theme rule sits inside a cascade layer, so any unlayered rule you write wins at any specificity, wherever the bundle places it. The package’s own component styles are scoped to their elements. A rule of yours that sets the same property on the same selector needs equal or higher specificity to win.
The theme keeps no stable selector contract. Class names, element structure and
data-slot attributes can change in any release. Only :root custom-property
overrides are expected to survive an upgrade. See
Branding and docs mount.
Reserved names
Section titled “Reserved names”The build writes several names at the top level of the output. A source
label or a root-source namespace that equals one of them would claim the same
path, so the build rejects it with INDEX_LABEL_RESERVED.
| Reserved | Why |
|---|---|
p, index, c, config.json |
The mirrored wire trees and root config |
data |
data/catalog/catalog.json |
docs |
The docs mount |
assets, public, _astro |
Static-site output directories |
404 |
The not-found page |
pagefind |
The search bundle |
robots.txt, _headers |
Files written at the root |
sitemap-* |
Any name starting sitemap- (the sitemap files) |
favicon* |
Any name starting favicon, in any format |
Each top-level entry of publicDir |
Copied to the root |
The file name of brand.logo |
Copied to the root |
The comparison ignores case, because macOS and Windows treat Docs and docs
as one directory. The check covers every non-root source label and every
namespace the root: true source publishes. A root source’s own label is
exempt, because its packages keep bare routes.
A 0.5.x config that loaded can fail here after an upgrade. Rename the index or move the namespace.
Path containment
Section titled “Path containment”Five fields are resolved relative to the config file’s own directory and
must resolve to that directory or a descendant of it: docs, css,
publicDir, brand.logo, and every sources[].path value. Escaping it
(any .. that survives resolution) is PATH_ESCAPE, naming the offending
key and both the raw and resolved path.
This check is lexical only — resolve()/relative() string math, never
realpath — so it does not follow symlinks. A symlink living inside the
config directory whose target resolves outside it passes this check despite
the eventual read landing outside the directory. loadConfig never reads
docs/css/publicDir/brand.logo/path off disk itself, so this is out
of scope for the loader.
The later reads differ. Only path and git sources are re-verified with
realpath, per file, by the source readers (src/sources/path.ts). The build
copies publicDir and brand.logo, bundles css and reads docs, with the lexical
check above as their only containment test. Do not place a symlink that
points outside the config directory in any of them. See
Security and trust model.
ownerUrl sits between the two: the schema’s pattern expresses “absolute
http(s) URL with {login} exactly once”, so a missing placeholder, a
doubled one, a non-http(s) scheme and a relative template are rejected by
schema and loader alike. The loader additionally requires the template to
parse with new URL().
siteUrl and nav[].link follow a related but distinct pattern worth
calling out explicitly: the JSON Schema declares only minLength: 1 for
siteUrl (its own description field says so — “src/config/load.ts
validates the shape beyond what this schema (minLength only) expresses”) and
only minLength: 1 for nav[].link (no schema-level shape check at all).
Both get real validation from the loader — siteUrl must parse as an
absolute http:/https: URL, nav[].link must satisfy the same-origin/
http(s)-only rule described above. A schema-only validator would accept
configs the loader rejects for both fields; this is deliberate, not a gap —
JSON Schema has no clean way to express “resolves to this same origin.”
footer.links[] reuses nav[]’s own navEntry schema definition, so it
carries the identical divergence.
docsNav[].link does not share that gap: its own schema entry
(docsNavEntry) carries "pattern": "^/docs/", which the loader’s own
/docs/-prefix check mirrors exactly, and which structurally forecloses
every open-redirect shape assertSafeNavLink otherwise guards against (a
protocol-relative // authority marker can never reach position 0 once
/docs/ occupies it). docsNav requiring docs to be set is likewise
expressed in the schema, via dependentRequired. Both rules agree between
schema and loader.
Example
Section titled “Example”{ "$schema": "https://cdn.jsdelivr.net/npm/@ocx-sh/catalog/src/config/schema/catalog.config.schema.json", "configVersion": 1, "sources": [ { "path": "../index", "root": true }, { "url": "https://mirror.example.com", "label": "mirror" }, { "git": "https://github.com/example/index.git", "ref": "main", "dir": "p", "label": "example", "excludeFromAll": true } ], "brand": { "title": "OCX Index", "wordmark": "index.ocx.sh", "logo": "./assets/logo.svg" }, "nav": [ { "text": "GitHub", "link": "https://github.com/ocx-sh/index" }, { "text": "Docs", "link": "/docs/" } ], "footer": { "links": [{ "text": "Status", "link": "/status" }] }, "docs": "./docs", "docsNav": [{ "text": "docs", "link": "/docs/" }], "css": "./theme/custom.css", "publicDir": "./public", "ci": { "forge": "github", "packageManager": "npm", "verifyCi": true }, "siteUrl": "https://index.ocx.sh", "ownerUrl": "https://gitlab.com/{login}", "description": "The public OCX package index.", "favicon": "/favicon.svg", "base": "/", "chrome": "neutral"}The $schema line above is for editor/IDE validation-as-you-type only —
loadConfig accepts it as an ordinary optional string field and never opens
or reads it at build or CI time.
Error codes at load time
Section titled “Error codes at load time”Every row below is a ConfigError (src/config/errors.ts); every command
that loads a config (build, dev, ci) maps every one of them to exit
65 (DATA) — see CLI.
| Code | Meaning |
|---|---|
MISSING_FILE |
Config file does not exist at the given path (ENOENT). |
READ_ERROR |
Config path exists but couldn’t be read — e.g. it names a directory, or a permission error. Distinct from MISSING_FILE, which is ENOENT only. |
INVALID_JSON |
Config file exists but is not valid JSON. |
INVALID_TYPE |
A field’s JSON type doesn’t match its expected type — includes an empty string on a field that requires non-empty, and an unparsable or wrong-protocol URL (siteUrl, sources[].url, nav[].link, ownerUrl, sources[].ownerUrl), and an ownerUrl or sources[].ownerUrl without exactly one {login}. |
UNKNOWN_KEY |
An unrecognized key at the top level, or inside a sources[] entry, brand, footer, or a nav[]/footer.links[]/docsNav[] entry. ci’s own keys are exempt. |
UNSUPPORTED_VERSION |
configVersion names a version this loader doesn’t support. |
SOURCE_DISCRIMINANT |
A sources[] entry has zero, or more than one, of path/url/git. |
EMPTY_SOURCES |
sources is present but empty. |
MULTIPLE_ROOT |
More than one sources[] entry sets root: true. |
MULTIPLE_DEFAULT |
More than one sources[] entry sets default: true. |
LABEL_CONFLICT |
Two sources[] entries declare the same explicit label. |
PATH_ESCAPE |
A css/docs/publicDir/brand.logo/path value resolves outside the config file’s directory. |
BASE_INVALID |
base, or the path of siteUrl as its default, is not a canonical URL path prefix. |
BASE_SITEURL_MISMATCH |
base and the path of siteUrl both carry a path and differ. |
CHROME_OCX_CONFLICT |
chrome: "ocx" is combined with brand, nav, footer or docsNav. |
OUT_DIR_OVERLAPS_INPUT |
The output directory equals or contains a configured input, or lies inside docs or publicDir. Raised by build and dev, not by loadConfig. |