Keep the Read the Docs URL scheme as canonical

Nothing changes for existing links — they serve content directly instead
of redirecting:

- the latest build mounts at /en/latest (default basePath), versioned
  builds at /en/vX.Y.Z, matching RTD's tag URLs
- page routes carry the .html suffix via a custom loader url, so every
  internal link, sidebar entry, and search result points at the exact
  legacy URL (/en/latest/howto/select.html) and the exported file is the
  page itself — no edge rewrite rules needed
- scripts/fix-html-ext.mjs renames Next's <route>.html.html exports and
  moves the per-segment prefetch dirs (which squat on the page's own
  path) to out-segments/; object storage holds both key shapes, and
  filesystem hosts fall back to the full-page RSC payload
- redirects shrink to: / and /en/ → /en/latest/, plus the carried-over
  upload → push rule, all generated into out-root/ for the bucket root
- version switcher and workflows updated for the /en/<version> prefixes;
  only /en/latest is indexable

Verified with a headless-browser click-through: client-side navigation,
anchored cross-page links, and versioned builds all work.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Thc5nWNbxfQ67pVDcNSkxC

Author: claude

.github/workflows/deploy.yml

@@ -54,12 +54,17 @@ jobs:
           AWS_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
           AWS_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
           AWS_DEFAULT_REGION: auto
-        # The root prefix is the latest build; versioned snapshots live under
-        # v*/ and versions.json is owned by the release workflow — never
-        # delete either from here.
+        # The latest build lives under en/latest/; versioned snapshots
+        # (en/vX.Y.Z/) and versions.json belong to the release workflow.
+        # out-segments/ holds per-segment prefetch payloads whose keys
+        # (howto/select.html/__next.*.txt) can only coexist with the page
+        # keys (howto/select.html) in object storage — upload it second, and
+        # keep the first sync's --delete away from those keys.
         run: |
-          aws s3 sync out/ "s3://${{ secrets.R2_BUCKET }}/" \
-            --endpoint-url "https://${{ secrets.R2_ACCOUNT_ID }}.r2.cloudflarestorage.com" \
-            --delete \
-            --exclude "v*" \
-            --exclude "versions.json"
+          ENDPOINT="https://${{ secrets.R2_ACCOUNT_ID }}.r2.cloudflarestorage.com"
+          aws s3 sync out/ "s3://${{ secrets.R2_BUCKET }}/en/latest/" \
+            --endpoint-url "$ENDPOINT" --delete --exclude "*.html/__next.*"
+          aws s3 sync out-segments/ "s3://${{ secrets.R2_BUCKET }}/en/latest/" \
+            --endpoint-url "$ENDPOINT"
+          aws s3 cp out-root/ "s3://${{ secrets.R2_BUCKET }}/" \
+            --endpoint-url "$ENDPOINT" --recursive

.github/workflows/release.yml

@@ -53,8 +53,9 @@ jobs:
         run: npm run build
         env:
           # Static export bakes absolute asset/link/search paths, so the
-          # version prefix must be set at build time.
-          NEXT_PUBLIC_BASE_PATH: /${{ env.TAG }}
+          # version prefix must be set at build time. /en/vX.Y.Z matches the
+          # old Read the Docs tag URLs.
+          NEXT_PUBLIC_BASE_PATH: /en/${{ env.TAG }}
 
       - uses: actions/upload-artifact@v4
         with:
@@ -70,8 +71,10 @@ jobs:
           ENDPOINT: https://${{ secrets.R2_ACCOUNT_ID }}.r2.cloudflarestorage.com
           BUCKET: ${{ secrets.R2_BUCKET }}
         run: |
-          aws s3 sync out/ "s3://${BUCKET}/${TAG}/" \
-            --endpoint-url "$ENDPOINT" --delete
+          aws s3 sync out/ "s3://${BUCKET}/en/${TAG}/" \
+            --endpoint-url "$ENDPOINT" --delete --exclude "*.html/__next.*"
+          aws s3 sync out-segments/ "s3://${BUCKET}/en/${TAG}/" \
+            --endpoint-url "$ENDPOINT"
 
           # Append this version to versions.json at the domain root; every
           # snapshot fetches it at runtime, so old snapshots list new versions.

.gitignore

@@ -4,6 +4,8 @@ node_modules/
 # Next.js build output
 .next/
 out/
+out-root/
+out-segments/
 
 # fumadocs-mdx generated files
 .source/

README.md

@@ -63,54 +63,65 @@ of the sidebar). Anything unexpected — an unknown `toc.yaml` field, a page
 without a title — fails the build loudly: that's the contract-drift alarm.
 `content/` is generated output; never commit or hand-edit it.
 
-`npm run build` emits the static site to `out/` (plain HTML/CSS/JS, servable
-from any static host that resolves `/howto/select` to `howto/select.html`),
-then `scripts/redirects.mjs` adds redirect stubs for legacy URLs.
+`npm run build` emits the static site to `out/`, then the postbuild scripts
+align filenames with the `.html` routes (see below) and generate the
+domain-root redirect objects in `out-root/`.
 
-## URL scheme and redirects
+## URL scheme
 
-Pages are mounted at the domain root: `docs.sqlc.dev/howto/select`. The old
-Read the Docs URLs redirect:
+The site keeps the Read the Docs URL scheme byte-for-byte, so existing links
+never change or even redirect:
 
 ```
-/en/latest/<path>.html  →  /<path>       (301)
-/en/latest/             →  /
-/howto/upload           →  /howto/push   (carried over from the old rediraffe config)
+/en/latest/howto/select.html    the current docs (canonical)
+/en/latest/                     section index
+/en/v1.32.0/howto/select.html   versioned snapshots (same scheme RTD used for tags)
+/                               redirects to /en/latest/
+/en/latest/howto/upload.html    redirects to /en/latest/howto/push.html
+                                (carried over from the old rediraffe config)
 ```
 
-These should be real 301s at the hosting edge (e.g. Cloudflare Bulk
-Redirects). As a belt-and-braces fallback the build also emits meta-refresh
-stubs (with canonical links and `noindex`) under `out/en/latest/`, so legacy
-links work on any static host even before edge rules exist. Old RTD tag URLs
-(`/en/v1.29.0/...`) can redirect to `/` until versioned builds cover them.
+Page routes carry the `.html` suffix (a custom `url` in `lib/source.ts`), so
+every internal link, search result, and sidebar entry points at the exact
+legacy URL and the exported file *is* the page — no edge rewrite rules
+needed. Next's export writes `<route>.html.html` plus a per-segment prefetch
+directory squatting on the page's own path; `scripts/fix-html-ext.mjs`
+renames the former and moves the latter to `out-segments/`, whose keys can
+coexist with the page keys in object storage (flat keyspace) but not on a
+filesystem. Hosts serving `out/` alone (local preview, GitHub Pages) still
+work: the segment prefetch probes 404 and the client falls back to the
+full-page `.txt` payload.
 
 ## Versioning
 
 Versions are immutable build artifacts, not branches:
 
-- The root serves latest, rebuilt on every `main` docs change.
-- The release workflow builds a tag with `NEXT_PUBLIC_BASE_PATH=/v1.32.0`
+- `/en/latest` serves the current docs, rebuilt on every `main` docs change.
+- The release workflow builds a tag with `NEXT_PUBLIC_BASE_PATH=/en/v1.32.0`
   (static export bakes absolute asset/link/search paths, so the prefix is a
-  build-time setting) and uploads it to the `/v1.32.0/` prefix, once, forever.
+  build-time setting) and uploads it to the `en/v1.32.0/` prefix, once,
+  forever.
 - `versions.json` at the domain root, appended by each release, drives the
   version-switcher dropdown; every snapshot fetches it at runtime so old
   snapshots list new versions.
 - Versioned builds set `noindex` so stale versions never outrank current
   docs in search engines.
 - Versioning starts at the first tag that contains `docs/toc.yaml`; older
-  tags are not backfilled.
+  tags are not backfilled. Old RTD tag URLs for those (`/en/v1.29.0/...`)
+  can redirect to `/en/latest/` at the edge.
 
 ## CI
 
 - **CI** (`ci.yml`): ingest + build + typecheck on every PR and push to main.
 - **Deploy latest docs** (`deploy.yml`): runs on `repository_dispatch`
   (type `docs-updated`), manual dispatch, and a daily cron as a safety net.
-  Ingests sqlc@main, builds, syncs `out/` to the R2 bucket root — excluding
-  `v*/` and `versions.json`, which belong to releases.
+  Ingests sqlc@main, builds, syncs `out/` + `out-segments/` to the
+  `en/latest/` prefix and the `out-root/` redirect objects to the bucket
+  root.
 - **Deploy versioned docs** (`release.yml`): takes a tag (manual input or
   `repository_dispatch` type `docs-release` with `{"tag": "v1.32.0"}`),
-  builds it under its version prefix, syncs to that prefix, and appends the
-  tag to `versions.json`.
+  builds it under `/en/<tag>`, syncs to that prefix, and appends the tag to
+  `versions.json`.
 
 Deploys need these repository secrets: `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`,
 `R2_SECRET_ACCESS_KEY`, `R2_BUCKET`. Until they exist, the deploy step is

app/(docs)/[[...slug]]/page.tsx

@@ -13,9 +13,18 @@ import type { Metadata } from 'next';
 import { createRelativeLink } from '@/lib/relative-link';
 import { gitConfig } from '@/lib/shared';
 
+// Routes carry the .html suffix of the legacy Read the Docs URLs
+// (/howto/select.html); page slugs in the source do not.
+function toSlugs(slug: string[] | undefined): string[] | undefined {
+  if (!slug || slug.length === 0) return slug;
+  const last = slug[slug.length - 1];
+  if (!last.endsWith('.html')) return slug;
+  return [...slug.slice(0, -1), last.slice(0, -'.html'.length)];
+}
+
 export default async function Page(props: PageProps<'/[[...slug]]'>) {
   const params = await props.params;
-  const page = source.getPage(params.slug);
+  const page = source.getPage(toSlugs(params.slug));
   if (!page) notFound();
 
   const MDX = page.data.body;
@@ -45,12 +54,15 @@ export default async function Page(props: PageProps<'/[[...slug]]'>) {
 }
 
 export async function generateStaticParams() {
-  return source.generateParams();
+  return source.generateParams().map(({ slug }) => {
+    if (!slug || slug.length === 0) return { slug };
+    return { slug: [...slug.slice(0, -1), `${slug[slug.length - 1]}.html`] };
+  });
 }
 
 export async function generateMetadata(props: PageProps<'/[[...slug]]'>): Promise<Metadata> {
   const params = await props.params;
-  const page = source.getPage(params.slug);
+  const page = source.getPage(toSlugs(params.slug));
   if (!page) notFound();
 
   return {

app/layout.tsx

@@ -7,19 +7,20 @@ const inter = Inter({
   subsets: ['latin'],
 });
 
+// Resolved (with default) via next.config.mjs `env`.
+const basePath = process.env.NEXT_PUBLIC_BASE_PATH;
+
 export const metadata: Metadata = {
-  metadataBase: new URL(
-    `https://docs.sqlc.dev${process.env.NEXT_PUBLIC_BASE_PATH ?? ''}`,
-  ),
+  metadataBase: new URL(`https://docs.sqlc.dev${basePath}`),
   title: {
     template: '%s — sqlc',
     default: 'sqlc Documentation',
   },
   // Versioned snapshots must never outrank the current docs in search
-  // engines: only the root (latest) build is indexable.
-  ...(process.env.NEXT_PUBLIC_BASE_PATH
-    ? { robots: { index: false, follow: false } }
-    : {}),
+  // engines: only the /en/latest build is indexable.
+  ...(basePath === '/en/latest'
+    ? {}
+    : { robots: { index: false, follow: false } }),
 };
 
 export default function Layout({ children }: LayoutProps<'/'>) {

components/version-switcher.tsx

@@ -7,8 +7,11 @@ interface VersionsFile {
   versions?: string[];
 }
 
-// The version prefix this build was mounted under ('' for latest).
-const CURRENT = process.env.NEXT_PUBLIC_BASE_PATH ?? '';
+// The URL prefix this build was mounted under, following the Read the Docs
+// scheme: /en/latest for the current docs, /en/vX.Y.Z for snapshots.
+// Resolved (with default) via next.config.mjs `env`.
+const CURRENT = process.env.NEXT_PUBLIC_BASE_PATH ?? '/en/latest';
+const LATEST = '/en/latest';
 
 /**
  * Version dropdown driven by /versions.json at the domain root. The file is
@@ -19,7 +22,7 @@ export function VersionSwitcher() {
   const [versions, setVersions] = useState<string[]>([]);
 
   useEffect(() => {
-    // Absolute path on purpose: from a /vX.Y.Z page this still hits the
+    // Absolute path on purpose: from an /en/vX.Y.Z page this still hits the
     // domain root, where versions.json lives.
     fetch('/versions.json')
       .then((res) => (res.ok ? (res.json() as Promise<VersionsFile>) : null))
@@ -31,7 +34,7 @@ export function VersionSwitcher() {
       });
   }, []);
 
-  if (versions.length === 0 && CURRENT === '') return null;
+  if (versions.length === 0 && CURRENT === LATEST) return null;
 
   function switchTo(prefix: string) {
     const path = window.location.pathname.slice(CURRENT.length);
@@ -45,16 +48,16 @@ export function VersionSwitcher() {
       value={CURRENT}
       onChange={(e) => switchTo(e.target.value)}
     >
-      <option value="">latest</option>
+      <option value={LATEST}>latest</option>
       {versions.map((v) => (
-        <option key={v} value={`/${v}`}>
+        <option key={v} value={`/en/${v}`}>
           {v}
         </option>
       ))}
       {/* Keep the baked-in version selectable even if versions.json is
           unreachable or does not list it. */}
-      {CURRENT !== '' && !versions.includes(CURRENT.slice(1)) && (
-        <option value={CURRENT}>{CURRENT.slice(1)}</option>
+      {CURRENT !== LATEST && !versions.some((v) => `/en/${v}` === CURRENT) && (
+        <option value={CURRENT}>{CURRENT.replace('/en/', '')}</option>
       )}
     </select>
   );

lib/source.ts

@@ -19,6 +19,10 @@ const docs = defineDocs({
 // See https://fumadocs.dev/docs/headless/source-api for more info
 export const source = loader({
   baseUrl: docsRoute,
+  // Keep the Read the Docs URLs byte-for-byte: pages live at
+  // <basePath>/howto/select.html, matching what RTD served at
+  // /en/latest/howto/select.html. The section index stays at /.
+  url: (slugs) => (slugs.length === 0 ? '/' : `/${slugs.join('/')}.html`),
   source: docs.toFumadocsSource(),
   plugins: [],
 });

next.config.mjs

@@ -2,16 +2,22 @@ import { createMDX } from 'fumadocs-mdx/next';
 
 const withMDX = createMDX();
 
-// Versioned builds are mounted under a path prefix (e.g. /v1.32.0). Static
-// export bakes absolute asset/link/search paths, so the prefix must be set at
-// build time. NEXT_PUBLIC_ so client components (version switcher) see it too.
-const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? '';
+// The whole site keeps the Read the Docs URL scheme: the latest build is
+// mounted at /en/latest, versioned builds at /en/vX.Y.Z (set
+// NEXT_PUBLIC_BASE_PATH). Static export bakes absolute asset/link/search
+// paths, so the prefix must be set at build time.
+const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? '/en/latest';
 
 /** @type {import('next').NextConfig} */
 const config = {
   output: 'export',
   reactStrictMode: true,
-  ...(basePath === '' ? {} : { basePath }),
+  basePath,
+  env: {
+    // Inline the resolved value (default included) for server and client
+    // alike — components must never see the raw, possibly-unset variable.
+    NEXT_PUBLIC_BASE_PATH: basePath,
+  },
 };
 
 export default withMDX(config);

package.json

@@ -4,8 +4,8 @@
   "private": true,
   "scripts": {
     "ingest": "node scripts/ingest.mjs",
-    "build": "next build",
-    "postbuild": "node scripts/redirects.mjs",
+    "build": "node -e \"require('fs').rmSync('out', {recursive: true, force: true})\" && next build",
+    "postbuild": "node scripts/fix-html-ext.mjs && node scripts/redirects.mjs",
     "dev": "next dev",
     "start": "serve out",
     "types:check": "next typegen && tsc --noEmit"