Migrate docs by remorses · Pull Request #11 · interfere-inc/docs

Tommy D. Rossi (remorses) · 2026-07-27T01:44:04Z

This migrates the docs site from Mintlify to Holocron, an open-source Mintlify replacement that runs as a Vite plugin.

Preview:https://066d1346-interfere-docs-website.remorses.workers.dev/docs

What changed

Replaced mintlify with @holocron.so/vite as a Vite plugin
Added vite.config.ts with the holocron plugin
Flattened docs.json: inlined the $ref navigation, removed Mintlify-only fields (theme, background, contextual, styling, fonts), updated schema to holocron
Added hero section matching the interfere.com homepage layout (side-by-side heading + subtitle)
Set InterVariable font globally for body and all headings via style.css
Replaced all colored SVG sidebar icons with monochrome lucide icons so they adapt to light/dark mode
Added missing icons to pages that didn't have them (quickstart, onboarding, concepts, power-user, home)
Moved static assets (icons, images, fonts, sources) into public/

Self-hosted on Cloudflare Workers

The docs are now a worker named interfere-docs-website, served under the /docs base path. No more third-party hosting.

bun install
bunx wrangler login
bun run deploy

No reverse proxy needed

Today interfere.com/docs is reverse-proxied to Mintlify's hosted app (interfere.mintlify.site, confirmed by the x-vercel-project-id and x-matched-path: /_sites/[subdomain]/[[...slug]] response headers). Since interfere.com is already proxied through Cloudflare, that hop can go away entirely: wrangler.jsonc declares a route so the docs are served at the edge.

"routes": [{ "pattern": "interfere.com/docs*", "zone_name": "interfere.com" }]

Routes take precedence over a Custom Domain on the same hostname, so this only affects /docs and leaves the rest of interfere.com alone.

The pattern is /docs*, not /docs/*. Cloudflare route patterns cannot contain query parameters, and the only way to match a URL that has one is to end the pattern with a wildcard:

pattern	`/docs`	`/docs?utm=x`	`/docs/quickstart`	`/docsearch`
`interfere.com/docs`	yes	no	no	no
`interfere.com/docs/*`	no	no	yes	no
`interfere.com/docs*`	yes	yes	yes	yes

So /docs/* would miss the bare /docs, and a plain /docs would miss any shared or ad-tagged link. The tradeoff is that /docs* also matches a future top-level path starting with "docs"; if that ever comes up, a more specific route with no script attached bypasses Workers for it.

www is intentionally not routed, www.interfere.com already 301s to the apex with the path preserved.

Before merging

Deploy must run from the Cloudflare account that owns the interfere.com zone, otherwise the route can't be created
Deploying applies the route and cuts /docs over from Mintlify immediately, so the old proxy config (Vercel rewrite, Worker, nginx, or a dashboard Origin Rule) should be removed at the same time

- Replace mintlify with @holocron.so/vite as a Vite plugin - Add vite.config.ts with holocron() plugin - Flatten docs.json: inline navigation $ref, remove Mintlify-only fields, update schema to holocron.so - Add hero section matching interfere.com layout (side-by-side heading + subtitle) - Set InterVariable font globally for body and all headings via style.css - Replace all colored SVG sidebar icons with monochrome lucide icons - Add missing icons to pages without them (quickstart, onboarding, concepts, power-user, home) - Add public/hero-bg.mp4 for VideoBackgroundShader (currently unused but available) - Update tsconfig.json for ESM + JSX support - Switch to pnpm Session: ses_05fe1bff8ffe9ZwRSAl373wWS3

changeset-bot · 2026-07-27T01:44:12Z

⚠️ No Changeset found

Latest commit: e28d7ec

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

Vite only serves static files from public/, not from the project root. In Mintlify all root files are served as static, so these dirs were at the root. Moving them into public/ fixes broken images and logos on the deployed site. Session: ses_05fe1bff8ffe9ZwRSAl373wWS3

Session: ses_05fe1bff8ffe9ZwRSAl373wWS3

The base: /docs config works locally but breaks on holocron.so hosting because the hosting worker does not strip the base prefix from asset URLs. A fix is being worked on in a separate session. Session: ses_05fe1bff8ffe9ZwRSAl373wWS3

The original repo used bun. Remove pnpm-lock.yaml and pnpm-workspace.yaml, regenerate bun.lock for the Holocron dependencies. Session: ses_05fe1bff8ffe9ZwRSAl373wWS3

These are processed image cache files written by the holocron dev server. They were accidentally committed via git add -A during the initial migration. Added _holocron to .gitignore to prevent it happening again. Session: ses_05fe1bff8ffe9ZwRSAl373wWS3

The VideoBackgroundShader was removed from the hero component. This video file is no longer referenced anywhere. Session: ses_05fe1bff8ffe9ZwRSAl373wWS3

Points favicon to the same logo files used in the header, so the browser tab icon matches the site logo. Session: ses_05fe1bff8ffe9ZwRSAl373wWS3

Added left padding using CSS grid variables (--grid-nav-width + --grid-gap) so the hero "Ship software that never breaks" heading starts at the same horizontal position as "How it works" and all other content headings below. Session: ses_05fe1bff8ffe9ZwRSAl373wWS3

Removed sidebar+gap padding so hero aligns flush with the left edge. Reduced top padding from pt-8/lg:pt-16 to pt-4/lg:pt-8. Session: ses_05fe1bff8ffe9ZwRSAl373wWS3

Adds a self-hosted Cloudflare Workers deployment target for the docs site, served under the `/docs` base path so it can sit behind a route on the main domain. Changes: - `vite.config.ts` — restore `base: '/docs'` and add `@cloudflare/vite-plugin` with the `rsc` / `ssr` environment mapping holocron expects - `wrangler.jsonc` — worker `interfere-docs-website`, entry `spiceflow/cloudflare-entrypoint`, `nodejs_compat` - `package.json` — `deploy` script (`vite build && wrangler deploy`) plus `wrangler` and `@cloudflare/vite-plugin` devDependencies The `base: '/docs'` config was reverted in ab5156c because holocron.so hosting did not strip the base prefix on asset lookups. Self-hosting on Workers hits a different variant of the same problem: Cloudflare's Asset Worker resolves a request against the uploaded directory tree and deliberately does not strip Vite's `base` (cloudflare/workers-sdk#11857), so the built HTML referenced `/docs/assets/*` while the store only held `assets/*`. That is fixed upstream in `@holocron.so/vite`, which now nests the client build output under a folder matching the base whenever the Cloudflare plugin is in use — the layout Cloudflare documents for serving a subdirectory: dist/client/ .assetsignore docs/assets/app.js <- GET /docs/assets/app.js, served by the CDN docs/icons/logo.svg Deployed and verified: 139 referenced URLs on /docs return 200, same for /docs/quickstart and /docs/sdk/next-js. NOTE: requires the upstream holocron patch release; `^0.28.0` does not include the asset nesting fix yet. Session: ses_05fe1bff8ffe9ZwRSAl373wWS3

Picks up the upstream Cloudflare fix that nests the client build output under the Vite `base`, so `/docs/assets/*` resolves against the uploaded asset tree instead of 404ing. Previously the site only deployed correctly with a locally patched holocron build; 0.29.0 makes a clean `bun install && bun run deploy` produce a working Worker. Rebuilt and redeployed, all referenced URLs on /docs and /docs/quickstart return 200. Session: ses_05fe1bff8ffe9ZwRSAl373wWS3

interfere.com is proxied through Cloudflare, so the docs can be served by a Worker route at the edge instead of reverse-proxying /docs to a third party. Routes take precedence over a Custom Domain on the same hostname, so this wins over whatever serves the rest of interfere.com without touching it. Pattern choice, per Cloudflare's route matching rules: pattern /docs /docs?utm=x /docs/quickstart /docsearch interfere.com/docs yes no no no interfere.com/docs/* no no yes no interfere.com/docs* yes yes yes yes Route patterns cannot contain query parameters, and the only way to match a URL that has one is to end the pattern with a wildcard. So `/docs/*` misses the bare `/docs`, and a plain `/docs` misses `/docs?utm_source=...` — which any shared or ad-tagged link will have. `/docs*` is the only single pattern that covers all three. The tradeoff is that it also matches a future top-level path starting with "docs" such as /docsearch. Cloudflare's documented escape hatch is a more specific route with no script attached, which bypasses Workers for that path. www is intentionally not listed: www.interfere.com already 301s to the apex with the path preserved (verified on /docs and /docs/quickstart), so adding a www route would serve the docs on two hostnames. Note this route only applies when deployed from the Cloudflare account that owns the interfere.com zone. `wrangler versions upload` is unaffected since triggers are applied separately. Session: ses_05fe1bff8ffe9ZwRSAl373wWS3

/docs* also matches paths like /docsearch, but nothing on interfere.com starts with "docs" today, so those are 404s either way and only the 404 page changes. The precise alternative regresses a working URL: URL today /docs* /docs + /docs/* /docs 200 200 200 /docs?utm_source=x 200 200 404 <- regression /docs/quickstart 200 200 200 /docsthing 404 404 404 Also notes Cloudflare route specificity bug: adding /docs/* alongside /docs* does nothing, the broader pattern wins even for /docs/quickstart. https://developers.cloudflare.com/workers/platform/known-issues/ Session: ses_05fe1bff8ffe9ZwRSAl373wWS3

Tommy D. Rossi (remorses) · 2026-07-27T01:44:04Z

This migrates the docs site from Mintlify to Holocron, an open-source Mintlify replacement that runs as a Vite plugin.

Preview:https://066d1346-interfere-docs-website.remorses.workers.dev/docs

What changed

Replaced mintlify with @holocron.so/vite as a Vite plugin
Added vite.config.ts with the holocron plugin
Flattened docs.json: inlined the $ref navigation, removed Mintlify-only fields (theme, background, contextual, styling, fonts), updated schema to holocron
Added hero section matching the interfere.com homepage layout (side-by-side heading + subtitle)
Set InterVariable font globally for body and all headings via style.css
Replaced all colored SVG sidebar icons with monochrome lucide icons so they adapt to light/dark mode
Added missing icons to pages that didn't have them (quickstart, onboarding, concepts, power-user, home)
Moved static assets (icons, images, fonts, sources) into public/

Self-hosted on Cloudflare Workers

The docs are now a worker named interfere-docs-website, served under the /docs base path. No more third-party hosting.

bun install
bunx wrangler login
bun run deploy

No reverse proxy needed

Today interfere.com/docs is reverse-proxied to Mintlify's hosted app (interfere.mintlify.site, confirmed by the x-vercel-project-id and x-matched-path: /_sites/[subdomain]/[[...slug]] response headers). Since interfere.com is already proxied through Cloudflare, that hop can go away entirely: wrangler.jsonc declares a route so the docs are served at the edge.

"routes": [{ "pattern": "interfere.com/docs*", "zone_name": "interfere.com" }]

Routes take precedence over a Custom Domain on the same hostname, so this only affects /docs and leaves the rest of interfere.com alone.

The pattern is /docs*, not /docs/*. Cloudflare route patterns cannot contain query parameters, and the only way to match a URL that has one is to end the pattern with a wildcard:

pattern	`/docs`	`/docs?utm=x`	`/docs/quickstart`	`/docsearch`
`interfere.com/docs`	yes	no	no	no
`interfere.com/docs/*`	no	no	yes	no
`interfere.com/docs*`	yes	yes	yes	yes

So /docs/* would miss the bare /docs, and a plain /docs would miss any shared or ad-tagged link. The tradeoff is that /docs* also matches a future top-level path starting with "docs"; if that ever comes up, a more specific route with no script attached bypasses Workers for it.

www is intentionally not routed, www.interfere.com already 301s to the apex with the path preserved.

Before merging

Deploy must run from the Cloudflare account that owns the interfere.com zone, otherwise the route can't be created
Deploying applies the route and cuts /docs over from Mintlify immediately, so the old proxy config (Vercel rewrite, Worker, nginx, or a dashboard Origin Rule) should be removed at the same time

- Replace mintlify with @holocron.so/vite as a Vite plugin - Add vite.config.ts with holocron() plugin - Flatten docs.json: inline navigation $ref, remove Mintlify-only fields, update schema to holocron.so - Add hero section matching interfere.com layout (side-by-side heading + subtitle) - Set InterVariable font globally for body and all headings via style.css - Replace all colored SVG sidebar icons with monochrome lucide icons - Add missing icons to pages without them (quickstart, onboarding, concepts, power-user, home) - Add public/hero-bg.mp4 for VideoBackgroundShader (currently unused but available) - Update tsconfig.json for ESM + JSX support - Switch to pnpm Session: ses_05fe1bff8ffe9ZwRSAl373wWS3

changeset-bot · 2026-07-27T01:44:12Z