Migrate docs - #11
Open
Tommy D. Rossi (remorses) wants to merge 14 commits into
Open
Conversation
- 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
|
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
Tommy D. Rossi (remorses)
marked this pull request as ready for review
July 28, 2026 15:29
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)
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
mintlifywith@holocron.so/viteas a Vite pluginvite.config.tswith the holocron plugindocs.json: inlined the$refnavigation, removed Mintlify-only fields (theme,background,contextual,styling,fonts), updated schema to holocronstyle.csspublic/Self-hosted on Cloudflare Workers
The docs are now a worker named
interfere-docs-website, served under the/docsbase path. No more third-party hosting.No reverse proxy needed
Today
interfere.com/docsis reverse-proxied to Mintlify's hosted app (interfere.mintlify.site, confirmed by thex-vercel-project-idandx-matched-path: /_sites/[subdomain]/[[...slug]]response headers). Since interfere.com is already proxied through Cloudflare, that hop can go away entirely:wrangler.jsoncdeclares a route so the docs are served at the edge.Routes take precedence over a Custom Domain on the same hostname, so this only affects
/docsand 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:/docs/docs?utm=x/docs/quickstart/docsearchinterfere.com/docsinterfere.com/docs/*interfere.com/docs*So
/docs/*would miss the bare/docs, and a plain/docswould 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.wwwis intentionally not routed,www.interfere.comalready 301s to the apex with the path preserved.Before merging
interfere.comzone, otherwise the route can't be created/docsover from Mintlify immediately, so the old proxy config (Vercel rewrite, Worker, nginx, or a dashboard Origin Rule) should be removed at the same time