fix(site): permanent redirects for moved docs and marketing pages (#64305)

This commit is contained in:
Adam
2026-11-17 15:08:52 -06:00
committed by GitHub
Unverified
parent b03809b2d7
commit 3811714fab
6 changed files with 28 additions and 15 deletions
+1 -1
View File
@@ -45,7 +45,7 @@ export default defineConfig(({ mode }) => {
: [],
// The bare host is a custom domain (it also supplies the DNS record), and cf detaches any domain
// not listed here. docs.<host> is the old docs host: the Worker sends its URLs to the same path
// on the V1 docs at /v1/docs.
// under /docs.
domains: [host, `docs.${host}`],
workersDev: false,
previewUrls: false,
+1 -1
View File
@@ -27,7 +27,7 @@
- `script/build.ts` runs after the site's `vite build` (from `script/build.ts` at the site root): it builds the docs' stylesheet and script, prerenders every page, every content page's Markdown twin (`/docs/config.md`; the intro's is `/docs/index.md`), `llms.txt` and the sitemap into `.output/public`, builds the Pagefind index, and checks every link, that nothing loads from outside `/docs` and that no page takes a reserved file name. `llms.txt` and the sitemap list opencode.ai's URLs on dev.opencode.ai too, so dev never advertises its own.
- Pull requests that touch the site run the same build on its own (`.github/workflows/check-docs.yml`): `bun run generate`, then `bun src/docs/script/build.ts --out <dir>`.
- The Worker never renders docs. `middleware.ts` serves the prerendered files: docs URLs reach it first (`runWorkerFirst` in `cloudflare.config.ts`), so a page's URL answers `Accept: text/markdown` with its twin. `vite dev` has no prerendered files, so the development server renders on request.
- `/docs` still receives the V1 docs' old links, which had more pages and other languages (`/docs/ja/...`). `middleware.ts` redirects any `/docs` path that isn't a page here (`virtual:docs-pages`, the same list the build prerenders) to the same path on the V1 docs with a 302, so adding a page here takes its URL over. `route.ts` also answers the V1 app's other addresses (its language aliases, share links and schemas) and, ahead of docs.opencode.ai moving to this Worker, sends that host's paths to `/v1/docs`. The old `/v2` URLs redirect to `/docs` permanently (`src/lib/legacy.ts`).
- `/docs` still receives the V1 docs' old links, which had more pages and other languages (`/docs/ja/...`). `middleware.ts` redirects any `/docs` path that isn't a page here (`virtual:docs-pages`, the same list the build prerenders) to the same path on the V1 docs with a 302, so adding a page here takes its URL over. `route.ts` also answers the V1 app's other addresses (its language aliases, share links and schemas) and, ahead of docs.opencode.ai moving to this Worker, sends that host's paths to the same path under `/docs`. The old `/v2` URLs redirect to `/docs` permanently (`src/lib/legacy.ts`).
## Writing Style
+14 -3
View File
@@ -34,19 +34,30 @@ export function docsRoute(url: URL, accept: string, slugs: Record<DocsSet["id"],
/**
* docs.opencode.ai (and docs.dev.opencode.ai) served the V1 docs from their own app, under /docs and
* at its root: every address there is the same path on the V1 docs here, permanently.
* at its root: every address there is the same path under /docs here, permanently, which takes it to
* its V2 page or on to the V1 docs as for any other /docs path.
*/
export function docsHostRedirect(url: URL) {
if (!url.hostname.startsWith("docs.")) return
const path = url.pathname.replace(/^\/docs(?=\/|$)/, "") || "/"
return `https://${url.hostname.slice("docs.".length)}${v1Docs.base.slice(0, -1)}${path}${url.search}`
return `https://${url.hostname.slice("docs.".length)}${latestDocs.base.slice(0, -1)}${path}${url.search}`
}
// Pages that moved, by slug: V2's own move, and V1's Go and Zen pages, which became Console pages.
// Pages that moved, by slug: V2's own move, V1's Go and Zen pages, which became Console pages, and
// V1 pages whose V2 page has another address.
const moved = new Map([
["console/inference", "console/api/inference"],
["go", "console/go"],
["zen", "console/models"],
["rules", "instructions"],
["sdk", "build/sdk"],
["server", "api"],
["keybinds", "cli/keybinds"],
["tui", "cli/tui"],
["web", "cli/web"],
["acp", "cli/acp"],
["modes", "agents"],
["custom-tools", "build/plugins/server"],
])
// The V1 docs app's other names for its languages (its middleware), and English's.
+1 -1
View File
@@ -32,7 +32,7 @@ export function legacyRedirect(request: Legacy): Response | undefined {
// links (`/go` about 75k requests a day, `/zen` 46k). Exact paths only: /zen/v1/* and /zen/go/v1/*
// are the inference API, which a prefix match here would break.
const moved = (request.locale ? localizedMoves : moves).get(request.path.replace(/(.)\/$/, "$1"))
if (moved && read) return redirect(302, `${moved}${request.search}`, "no-store")
if (moved && read) return redirect(301, `${moved}${request.search}`)
// The legacy dashboard and its sign-in, now the Console. The V1 CLI's "create a key at /auth" and
// V1's usage-limit link /workspace/<id>/go (about 50k requests a day).
+10 -7
View File
@@ -67,7 +67,7 @@ describe("docs routes", () => {
})
test("send paths without a V2 page to the same path on the V1 docs, temporarily", () => {
for (const path of ["/docs/ja/", "/docs/ja/agents/", "/docs/zh-cn/config", "/docs/ide/", "/docs/sdk.md"])
for (const path of ["/docs/ja/", "/docs/ja/agents/", "/docs/zh-cn/config", "/docs/ide/", "/docs/lsp.md"])
expect(route(path)).toEqual({ type: "redirect", location: `/v1/docs${path.slice("/docs".length)}`, status: 302 })
expect(route("/docs/ide/?ref=app")).toEqual({ type: "redirect", location: "/v1/docs/ide/?ref=app", status: 302 })
})
@@ -80,6 +80,9 @@ describe("docs routes", () => {
})
expect(route("/docs/go")).toEqual({ type: "redirect", location: "/docs/console/go/", status: 301 })
expect(route("/docs/zen/")).toEqual({ type: "redirect", location: "/docs/console/models/", status: 301 })
expect(route("/docs/rules/")).toEqual({ type: "redirect", location: "/docs/instructions/", status: 301 })
expect(route("/docs/sdk")).toEqual({ type: "redirect", location: "/docs/build/sdk/", status: 301 })
expect(route("/docs/server/")).toEqual({ type: "redirect", location: "/docs/api", status: 301 })
})
test("leave the docs' own files to the assets, never to the V1 docs", () => {
@@ -131,13 +134,13 @@ describe("V1 docs routes", () => {
expect(route(path)).toEqual({ type: "missing" })
})
test("send docs.opencode.ai's addresses to the same path on the V1 docs", () => {
test("send docs.opencode.ai's addresses to the same path under /docs", () => {
const host = (url: string) => docsHostRedirect(new URL(url))
expect(host("https://docs.opencode.ai/")).toBe("https://opencode.ai/v1/docs/")
expect(host("https://docs.opencode.ai/docs")).toBe("https://opencode.ai/v1/docs/")
expect(host("https://docs.opencode.ai/docs/ide/?x=1")).toBe("https://opencode.ai/v1/docs/ide/?x=1")
expect(host("https://docs.opencode.ai/s/abc")).toBe("https://opencode.ai/v1/docs/s/abc")
expect(host("https://docs.dev.opencode.ai/docs/ja/")).toBe("https://dev.opencode.ai/v1/docs/ja/")
expect(host("https://docs.opencode.ai/")).toBe("https://opencode.ai/docs/")
expect(host("https://docs.opencode.ai/docs")).toBe("https://opencode.ai/docs/")
expect(host("https://docs.opencode.ai/docs/ide/?x=1")).toBe("https://opencode.ai/docs/ide/?x=1")
expect(host("https://docs.opencode.ai/s/abc")).toBe("https://opencode.ai/docs/s/abc")
expect(host("https://docs.dev.opencode.ai/docs/ja/")).toBe("https://dev.opencode.ai/docs/ja/")
expect(host("https://opencode.ai/docs/")).toBeUndefined()
})
})
+1 -2
View File
@@ -31,9 +31,8 @@ describe("legacy redirects", () => {
test("moved pages match exact paths only, keep the query and leave the inference API alone", () => {
const zen = get("/zen/", { search: "?ref=app" })
expect(zen?.status).toBe(302)
expect(zen?.status).toBe(301)
expect(zen?.headers.get("Location")).toBe("/console/models?ref=app")
expect(zen?.headers.get("Cache-Control")).toBe("no-store")
expect(get("/zen/go")?.headers.get("Location")).toBe("/console/go")
expect(get("/teams")?.headers.get("Location")).toBe("/console/teams")
for (const path of ["/zen/v1/models", "/zen/go/v1/chat/completions", "/go/v1", "/models.json", "/gopher"])