coder · nickvigilante · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
@@ -1153,6 +1153,11 @@ jobs:
           cd offlinedocs
           pnpm lint
 
+      - name: Test
+        run: |
+          cd offlinedocs
+          pnpm test
+
       - name: Build
         # no `-j` flag as `make` fails with:
         # coderd/rbac/object_gen.go:1:1: syntax error: package statement must be first

diff --git a/docs/about/contributing/documentation.md b/docs/about/contributing/documentation.md
@@ -33,7 +33,7 @@ following third-party references:
 ## Tools
 
 This repository runs [Vale](https://vale.sh/) on `docs/` as part of CI to enforce prose style.
-The configuration is the repo-root `.vale.ini`, and the curated rule set is documented in [`docs/.style/style-guide/`](../../.style/style-guide/README.md).
+The configuration is the repo-root `.vale.ini`, and the curated rule set is documented in [`docs/.style/style-guide/`](https://github.com/coder/coder/tree/main/docs/.style/style-guide).
 Run the same checks locally with `make lint/prose`.
 Vale runs in advisory mode in this iteration: warnings surface as inline PR annotations, but they don't block the build.
 

diff --git a/offlinedocs/.eslintrc.json b/offlinedocs/.eslintrc.json
diff --git a/offlinedocs/.gitignore b/offlinedocs/.gitignore
@@ -11,10 +11,22 @@
 # next.js
 /.next/
 /out/
+next-env.d.ts
 
 # production
 /build
 
+# fumadocs-mdx generated index
+/.source
+
+# generated docs content (synced from ../docs by scripts/sync-docs.mjs);
+# keep the directory itself so fumadocs-mdx has a source dir on a clean checkout
+/content/docs/*
+!/content/docs/.gitkeep
+
+# doc images copied into the bundle by the sync step
+/public/images/
+
 # misc
 .DS_Store
 *.pem
@@ -31,6 +43,3 @@ pnpm-debug.log*
 
 # typescript
 *.tsbuildinfo
-
-# content
-public/images/
diff --git a/offlinedocs/.prettierignore b/offlinedocs/.prettierignore
@@ -1 +1,6 @@
 **/pnpm-lock.yaml
+.next/
+out/
+.source/
+content/docs/
+public/images/
diff --git a/offlinedocs/content/docs/.gitkeep b/offlinedocs/content/docs/.gitkeep
diff --git a/offlinedocs/next-env.d.ts b/offlinedocs/next-env.d.ts
diff --git a/offlinedocs/next.config.js b/offlinedocs/next.config.js
diff --git a/offlinedocs/next.config.mjs b/offlinedocs/next.config.mjs
@@ -0,0 +1,53 @@
+// Next.js configuration for the offlinedocs static export. It wires the Fumadocs
+// MDX plugin into the build (createMDX/withMDX) and produces the
+// coder_docs_<version>.tgz artifact the release pipeline ships for offline use.
+// Each build setting is documented at its field below.
+
+import { createMDX } from "fumadocs-mdx/next";
+
+const withMDX = createMDX();
+
+/** @type {import('next').NextConfig} */
+const config = {
+	// Pin the workspace root to this folder. offlinedocs has its own
+	// package.json + lockfile inside the coder/coder repo, and Next would
+	// otherwise infer the repo root (which also has a lockfile) as the root.
+	turbopack: {
+		root: import.meta.dirname,
+	},
+	// Emit a fully static site into out/ so the docs bundle is self-contained
+	// and can be served by any static file host with no Node server. This is
+	// what the release pipeline tars into coder_docs_<version>.tgz for
+	// offline/airgapped use.
+	//
+	// Only export for production builds (`next build`). Under `output: export`
+	// Next installs an optional catch-all route that rejects any path
+	// generateStaticParams did not prerender. In dev that turns incidental
+	// requests into hard errors instead of clean 404s - most notably a stale
+	// /serviceWorker.js still registered at the dev origin by a prior site (a
+	// local coder server or the old offlinedocs, both of which used :3000),
+	// plus favicon probes and similar. When next dev errors on those, the page
+	// renders but never becomes interactive; the symptom reported in UAT was
+	// "nothing in the UI is clickable" (OS tabs, theme toggle, etc.). Gating
+	// export to production keeps next dev on Next's normal server (clean 404s),
+	// so local dev stays interactive, while next build still produces the full
+	// static export.
+	//
+	// Running the docs anywhere: if a machine shows a dead or unclickable page
+	// from an earlier session, a stale service worker is cached - unregister it
+	// (DevTools > Application > Service workers > Unregister) and hard-reload.
+	// The dev server also runs on :26337 (see the package.json scripts), not
+	// :3000, to stay off that shared origin.
+	output: process.env.NODE_ENV === "production" ? "export" : undefined,
+	// Canonical URLs end in a slash and every route is emitted as
+	// <route>/index.html, which is what a plain static file server expects.
+	trailingSlash: true,
+	// Doc images are copied into the bundle (refer to scripts/sync-docs.mjs)
+	// and served as-is; next/image optimization needs a running server,
+	// which a static export does not have.
+	images: {
+		unoptimized: true,
+	},
+};
+
+export default withMDX(config);
diff --git a/offlinedocs/package.json b/offlinedocs/package.json
@@ -1,60 +1,51 @@
 {
 	"name": "coder-docs-generator",
 	"private": true,
+	"description": "Generates the self-contained, offline Coder documentation bundle from the coder/coder docs corpus using Fumadocs.",
 	"scripts": {
-		"dev": "pnpm copy-images && next dev",
+		"sync": "node scripts/sync-docs.mjs",
+		"dev": "pnpm sync && next dev -p 26337",
 		"build": "next build",
-		"start": "next start",
-		"export": "pnpm copy-images && next build",
-		"copy-images": "sh ./scripts/copyImages.sh",
+		"export": "pnpm sync && next build",
+		"postinstall": "fumadocs-mdx",
 		"lint": "pnpm run lint:types",
-		"lint:types": "tsc --noEmit",
-		"format": "prettier --cache --write './**/*.{css,html,js,json,jsx,md,ts,tsx,yaml,yml}'",
-		"format:check": "prettier --cache --check './**/*.{css,html,js,json,jsx,md,ts,tsx,yaml,yml}'"
+		"lint:types": "pnpm sync && fumadocs-mdx && next typegen && node scripts/ensure-source.mjs && tsc --noEmit",
+		"format": "prettier --cache --write './**/*.{css,js,jsx,json,mjs,ts,tsx,yaml,yml}'",
+		"format:check": "prettier --cache --check './**/*.{css,js,jsx,json,mjs,ts,tsx,yaml,yml}'",
+		"test": "node --test 'scripts/**/*.test.mjs' && node --import tsx --test 'src/mdx-plugins/**/*.test.ts' && node --import tsx --import ./test/jsdom-setup.mjs --test 'src/components/**/*.test.tsx'"
 	},
 	"dependencies": {
-		"@chakra-ui/react": "2.10.10",
-		"@emotion/react": "11.14.0",
-		"@emotion/styled": "11.14.1",
-		"archiver": "8.0.0",
-		"framer-motion": "^10.18.0",
-		"front-matter": "4.0.2",
-		"lodash": "4.18.1",
-		"next": "15.5.23",
-		"react": "18.3.1",
-		"react-dom": "18.3.1",
-		"react-icons": "5.7.0",
-		"react-markdown": "10.1.0",
-		"rehype-raw": "7.0.0",
-		"remark-gfm": "4.0.1",
-		"sanitize-html": "2.17.6"
+		"@fontsource-variable/geist": "5.3.0",
+		"@fontsource-variable/geist-mono": "5.3.0",
+		"@phosphor-icons/react": "2.1.10",
+		"fumadocs-core": "16.10.5",
+		"fumadocs-mdx": "15.0.12",
+		"fumadocs-ui": "16.10.5",
+		"next": "16.2.9",
+		"react": "19.2.7",
+		"react-dom": "19.2.7",
+		"rehype-raw": "7.0.0"
 	},
 	"devDependencies": {
-		"@types/lodash": "4.17.25",
+		"@tailwindcss/postcss": "4.3.1",
+		"@types/mdx": "2.0.14",
 		"@types/node": "22.20.1",
-		"@types/react": "18.3.12",
-		"@types/react-dom": "18.3.1",
-		"@types/sanitize-html": "2.16.1",
-		"eslint": "8.57.1",
-		"eslint-config-next": "14.2.35",
-		"prettier": "3.9.6",
+		"@types/react": "19.2.17",
+		"@types/react-dom": "19.2.3",
+		"jsdom": "25.0.1",
+		"postcss": "8.5.15",
+		"prettier": "3.9.4",
+		"tailwindcss": "4.3.1",
+		"tsx": "4.23.12",
 		"typescript": "6.0.3"
 	},
 	"engines": {
-		"npm": ">=9.0.0 <10.0.0",
 		"node": ">=22.0.0 <25.0.0"
 	},
 	"pnpm": {
 		"overrides": {
-			"@babel/runtime": "7.26.10",
-			"brace-expansion": "1.1.13",
-			"minimatch": "5.1.8",
-			"glob@>=10": "10.5.0",
-			"postcss": "8.5.10",
-			"js-yaml": "3.14.2",
-			"yaml": "1.10.3",
-			"flatted": "3.4.2",
-			"mdast-util-to-hast": "13.2.1"
+			"picomatch": "2.3.2",
+			"js-yaml": "4.1.1"
 		}
 	}
 }