These behaviours are deliberate. A deployer needs to know them before picking a host or a config shape. Each section says what happens and what to do about it.
One build serves one URL prefix
Section titled “One build serves one URL prefix”The site is built for a single URL prefix. Set base in catalog.config.json,
or give siteUrl a path, and every link, asset and data fetch carries that
prefix. The default is /.
A build is not portable between prefixes. To serve the same catalog under a
different prefix, rebuild with a different base. ocx-catalog dev serves
under the same base, so the preview URL includes it.
Consequence: a GitHub Pages project site at /<repo>/ works when you set
"base": "/<repo>/". See Config schema
and Hosting and headers.
_headers is Cloudflare Pages and Netlify format only
Section titled “_headers is Cloudflare Pages and Netlify format only”ocx-catalog build writes a _headers file in the Cloudflare Pages and
Netlify path-pattern format. It sets two headers on every mirrored /p/*
prefix: Content-Security-Policy: sandbox and X-Content-Type-Options: nosniff.
Under a base, every pattern is prefixed with it.
The product treats those headers as a hard deployment precondition. They
are the one control that sandboxes untrusted, same-origin mirrored content.
On any host that does not read the file format, _headers ships but is inert.
Consequence: on GitHub Pages, a raw S3 bucket, or a self-managed nginx or Caddy server, recreate the two headers in that host’s own mechanism. Or accept the risk knowingly. See Hosting and headers.
Bunny CDN deploys
Section titled “Bunny CDN deploys”ocx.sh/catalog/ is served from Bunny CDN. Three facts apply to any Bunny
deploy of a catalog build.
_headers is not read on Bunny
Section titled “_headers is not read on Bunny”Bunny ignores _headers. The sandbox comes from an edge rule named
catalog-sandbox, owned by the ocx.sh website deploy. It sets both headers
at /catalog/p/* and /catalog/index/*/p/*. A Bunny deploy without that rule
serves mirrored content unsandboxed.
Removed packages stay reachable
Section titled “Removed packages stay reachable”The deploy prune deletes stale .html files only. A package removed from the
index loses its detail page, but its wire files keep answering. That covers
/catalog/p/<ns>/<pkg>.json and everything beneath it.
Those files stay reachable until a bunny:gc task exists. Taking down a
hostile package therefore needs a manual delete in Bunny. Removing it from the
index is not enough.
Deployment gate before a release goes live
Section titled “Deployment gate before a release goes live”Before ocx.sh/catalog/ serves a new build, probe one package root and one
per-index package root:
curl -sI https://ocx.sh/catalog/p/<ns>/<pkg>.jsoncurl -sI https://ocx.sh/catalog/index/<label>/p/<ns>/<pkg>.jsonBoth responses must carry these two headers:
content-security-policy: sandboxx-content-type-options: nosniffIf either header is missing, do not publish. This package never runs the probe. The deployer does.
The docs mount renders a restricted Markdown dialect
Section titled “The docs mount renders a restricted Markdown dialect”The docs directory is mounted at /docs/**. The sidebar is generated from
the tree: directories become groups, and pages sort by frontmatter order,
then title. The mount has these limits:
- Only
.mdfiles are mounted as pages..mdxfiles are ignored. - VitePress-only syntax is not interpreted.
::: detailsblocks and{#id}heading anchors show as plain text. - A symbolic link in the tree fails the build with exit
65. So does a copied file that would take a page’s place or overwrite one inpublicDir/docs/. - Fenced code blocks are syntax-highlighted. The build log shows no warning for it.
- The build rewrites links to pages. A relative link, with or without
.md, resolves against its own file and becomes a directory route underbase. A root-relative link such as/docs/install/gainsbase. - External links open in a new tab.
mailto:and#fragmentlinks are left alone. - A relative link to another file resolves against its own file. It is served
from
<base>docs/, where the build copies the tree’s images and downloads. - A link to a page or file that does not exist fails the build.
- A link inside raw HTML (
<a href>) is not rewritten. docs/index.mdis the page at/docs/, and<dir>/index.mdis the page at/docs/<dir>/. Without adocs/index.md, there is no page at/docs/, so name pages that exist indocsNav.
Consequence: a docs tree written for VitePress needs a small pass before
it renders cleanly. Drop the {#id} suffixes and rewrite raw HTML anchors. See Branding and docs mount.
The palette searches page titles, headings and an excerpt
Section titled “The palette searches page titles, headings and an excerpt”The Mod+K palette searches packages by name, title, description and keywords,
ranked by relevance (see Search and versions).
With a docs mount it also searches docs pages, in a “Docs” group. A docs page
matches on its title, its headings (the first 20) and the first 600 characters
of its text. It does not search the full text of a page, and it does not index
.mdx files.
The docs index is data/catalog/docs-index.json. The build writes it only when
docs is set, and the palette fetches it on the first open.
View and sort choices live in the URL. The browser also remembers the view, the sort and the install-pin level under the 0.5.x keys, and a URL wins over them.
README links to files the mirror lacks become text
Section titled “README links to files the mirror lacks become text”A README link survives when it is an absolute http(s) or mailto: URL, or a
#fragment. A relative link or image survives when the mirror holds the file.
Any other link becomes its text, and any other image is dropped. A link to a
LICENSE or a docs/ page that the index never published is therefore plain
text.
chrome: "ocx" is experimental
Section titled “chrome: "ocx" is experimental”chrome: "ocx" renders the ocx.sh header and footer. It exists for the
ocx.sh deployment and carries no stability promise between releases. It also
rejects brand, nav, footer and docsNav, because the shell owns them. Use the
default neutral chrome for any other site.
ocx-catalog ci supports two forges and deploys nothing
Section titled “ocx-catalog ci supports two forges and deploys nothing”The Forge type in src/ci/types.ts accepts only "github" and "gitlab".
On either forge the rendered workflow builds the site and stops.
templates/ci/github-ci.yml runs ocx-catalog build.
templates/ci/gitlab-ci.yml runs the same build and uploads dist as an
artifact. Neither template publishes to any host.
Consequence: the deploy step is yours to add to the generated workflow.
ocx-catalog ci gives you the build, not the publish.
What to check before choosing a host
Section titled “What to check before choosing a host”- Which URL prefix will serve the site, and does
basematch it? - Does the host read a Cloudflare Pages or Netlify
_headersfile? If not, are you translating the two headers yourself or accepting the risk knowingly? - On Bunny, is the
catalog-sandboxedge rule in place, and did both probe commands show the headers?
Full host-by-host answers: Hosting and headers.