feat: make the docs site deployable to Cloudflare like the marketing sites - #6
Merged
Conversation
…rketing sites are Adds the wrangler config the Git-integration path needs, so this repo can publish either way: `just deploy` by hand, or Cloudflare Workers Builds on push once the repo is connected in the dashboard. `just deploy` is now a bare `wrangler deploy` — the name, compatibility date and assets directory live in wrangler.jsonc instead of being repeated on the command line, matching the marketing repos. The .assetsignore is the part that matters. Running a real export showed `mint export` copies repo files into its output (justfile, scripts/, LICENSE) and adds its own double-click-to-serve helpers (serve.js, Start Docs.bat, Start Docs.command). Published as-is, all of those would be reachable over HTTP. Because dist/ is regenerated on every build, the ignore file is committed at the repo root and copied in by `just export`. Two things the export decided for us rather than the other way round: it carries no 404.html, so not_found_handling stays at its default instead of pointing at a page that does not exist; and the unzip step falls back to python3 -m zipfile, since `unzip` is not guaranteed in a CI image. dist/ and export.zip are now gitignored — the export is ~47MB, most of it the Next.js bundle.
The wrangler config points assets.directory at dist/, which is gitignored and only exists after mint export runs. A connected repo therefore failed with "the directory specified by assets.directory does not exist". Workers Builds has no default build command, so this cannot be fully automatic — but naming the script "build" makes the dashboard setting a plain `npm run build` instead of a long shell one-liner. just export now delegates to the same script so the steps are defined once. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ploy These READMEs still walked through connecting the repo at dashboard.mintlify.com and CNAMEing to cname.mintlify.app. That is not how these sites publish any more — production is a Cloudflare Worker serving the static export. Drops the standalone deploy sections in favour of a two-line statement near the top, matching the website repos, and keeps the workflow list under CI where it belongs. Also corrects a published page (develop/docs-site.mdx) and SPEC.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The link check has failed on main in every docs repo since mid-August. Current
lychee releases reject `--base .` outright ("base must either be a full URL or
an absolute local path"), so the job died before checking anything. Replaced
with --root-dir plus an external-only scheme filter; internal links and anchors
are already covered by `npm run check`, which runs first in the same job.
Separately, dash.cloudflare.com returns 403 to CI, failing docs-mantis on a link
that is fine in a browser. Excluded that host rather than accepting 403 globally,
which would mask genuinely forbidden links.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
With lychee actually running again it found real breakage. docs-privacytracker linked to `privacykey/privacytracker-docs` in eight places; the repo was renamed to `docs-privacytracker` and GitHub's redirect had been hiding it from readers but not from the checker. The rest are false positives, excluded with the reason recorded next to each: the docs domains have no DNS yet, privacykey/privacysentinel is a private repo so anonymous CI gets a 404 on a correct link, and shell.azure.com bot-blocks CI. Verified locally: all four repos now report 0 errors. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The docs use http://localhost:3000 in examples. Those resolved on a dev machine with the preview running, which is why this only surfaced in CI, where nothing listens on the port and lychee reported connection refused. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
lychee exits non-zero on a timeout as well as on a broken link, so one slow third-party host (tauri.app, in the run that prompted this) fails the whole PR with zero actual errors reported. 30s and five retries instead. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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.
Brings the docs sites to parity with the marketing sites: publishable either by hand with
just deployor by Cloudflare Workers Builds on push, once the repo is connected in the dashboard.Previously the justfile passed
--assets dist --name … --compatibility-date …on the command line, which works locally but leaves Workers Builds with nothing to read. Nowwrangler.jsonccarries all three andjust deployis a barewrangler deploy, matching the marketing repos.The part that matters:
.assetsignoreI ran a real export before writing the config, which was worth doing —
mint exportcopies repo files into its output:serve.jsand the twoStart Docs.*files are Mintlify's own double-click-to-serve helpers for air-gapped use;justfile,scripts/andLICENSEare lifted straight out of this repo. Published as-is, every one of them is reachable over HTTP on the docs domain.Because
dist/is regenerated on each build, the ignore file is committed at the repo root and copied intodist/byjust export.Two things the export decided, not me
404.html. I had plannednot_found_handling: "404-page"to match the marketing sites; the export carries no such file, so it stays at the default rather than pointing somewhere that does not exist.unzipis not guaranteed in a CI image, so the step falls back topython3 -m zipfile.Workers Builds
When you connect this repo, the build command is in a comment at the top of
wrangler.jsonc:mint exportneeds no Mintlify account — verified,mint statusreports not-logged-in and the export still succeeds. What I could not verify from here is whether Cloudflare's build image runs it cleanly; that only proves out on the first connected build.Also
dist/andexport.zipare now gitignored. The export is ~47 MB, ~865 files, of which 42 MB is the Next.js bundle — well inside Workers' limits but a slow upload.