Skip to content
ocx
install

Config schema

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.

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": { "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.

{
"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[].link must be /docs/ or start with /docs/ — anything else is a nav[] entry with extra steps, not a label for the docs mount. INVALID_TYPE otherwise.
  • docsNav present without docs configured is INVALID_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).

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).
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[] and docsNav[] links that start with / are joined onto it.
  • favicon is joined onto it when a page links it, and so is every asset the css bundle references.
  • Every pattern in _headers is prefixed with it.
  • ocx-catalog dev serves 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 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 points at a directory of Markdown that the build mounts at <base>docs/. The mount follows these rules:

  • Only **/*.md files are mounted. .mdx files and dot-files are skipped.
  • The page URL is the path without .md, so guide/install.md becomes <base>docs/guide/install/. An index.md serves its directory, so docs/index.md is <base>docs/ and guide/index.md is <base>docs/guide/. Two files that map to one route, such as foo.md and foo/index.md, fail the build.
  • Each path segment may use letters, digits, -, _ and .. Anything else fails the build with exit 65.
  • 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 the order of that index page, then by path. Pages sort by order, then title.
  • VitePress-only syntax is not interpreted. ::: details blocks 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 under base. index.md maps to its directory, and ?query and #fragment are kept. A root-relative link such as /docs/install/ gains base.
  • 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, .mdx files, 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 in publicDir/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.

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.

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.

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.

catalog.config.json
{
"$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.

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.