fix: serve markdown via routing middleware for Accept: text/markdown

AGENTS.md

@@ -75,7 +75,8 @@ tsconfig.base.json             # shared compilerOptions + @vp-* path aliases (${
   them as `"catalog:"`. Add new shared deps there. There must be exactly one copy of `vue`, `vitepress` and
   `@voidzero-dev/vitepress-theme` (`pnpm dedupe --check` runs in CI).
 - One `pnpm-lock.yaml` at the root; never edit it by hand.
-- Each app keeps its own `vercel.json` (redirects, headers, `Accept: text/markdown` rewrite) — Vercel projects
+- Each app keeps its own `vercel.json` (redirects, headers) and `middleware.ts` (Vercel Routing Middleware for
+  `Accept: text/markdown` negotiation; the two copies must stay identical) — Vercel projects
   point at `apps/docs` and `apps/developer-docs` as Root Directory.
 - Header buttons come from `themeConfig.nav` items flagged `planeButton: "primary" | "secondary"`.
 

apps/developer-docs/AGENTS.md

@@ -26,7 +26,8 @@ pnpm --filter developer-docs check:types
   - **`docs/api-reference/`** — REST API endpoint docs (180+ endpoints across 30+ resource categories)
   - **`docs/self-hosting/`** — Deployment and configuration guides
   - **`docs/dev-tools/`** — Webhooks, OAuth apps, agents, MCP server docs
-- **`vercel.json`** — cleanUrls, headers, redirects, `Accept: text/markdown` rewrite (per-app Vercel project)
+- **`vercel.json`** — cleanUrls, headers, redirects (per-app Vercel project)
+- **`middleware.ts`** — Vercel Routing Middleware: `Accept: text/markdown` → `/path.md` with `Vary: Accept` (mirror of `apps/docs/middleware.ts`)
 - Shared visual identity (header, layout, tokens, `Card`/`CardGroup`/`Tags`, Copy page menu, cookie consent)
   lives in `packages/theme` — never fork it here.
 

apps/developer-docs/docs/.vitepress/config.mts

@@ -67,7 +67,7 @@ export default extendConfig(
             details:
               "This documentation covers self-hosting (Docker, Kubernetes, and more), the REST API reference for projects, work items, cycles, modules, states, pages, and more, plus developer tools including OAuth apps, webhooks, agents, and the MCP server.",
             // Per-page .md versions are already emitted by buildEnd() for the
-            // `Accept: text/markdown` rewrite in vercel.json, so the plugin only
+            // `Accept: text/markdown` negotiation in middleware.ts, so the plugin only
             // owns llms.txt / llms-full.txt.
             generateLLMFriendlyDocsForEachPage: false,
             // Don't inject invisible LLM-hint markup into rendered pages.
@@ -96,7 +96,7 @@ export default extendConfig(
         },
       },
       buildEnd(siteConfig) {
-        // Copy source .md files into dist/ for Accept: text/markdown negotiation.
+        // Copy source .md files into dist/ for Accept: text/markdown negotiation (see middleware.ts).
         const srcDir = siteConfig.srcDir;
         const outDir = siteConfig.outDir;
 

apps/developer-docs/middleware.ts

@@ -0,0 +1,59 @@
+/**
+ * Vercel Routing Middleware for developers.plane.so — markdown content negotiation.
+ *
+ * Requests that prefer `text/markdown` over `text/html` are rewritten to the page's
+ * markdown source (`/foo` → `/foo.md`, `/` → `/index.md`); buildEnd() in
+ * docs/.vitepress/config.mts copies those files into dist/. Every other request
+ * falls through to the HTML page. Both variants carry `Vary: Accept` so
+ * downstream caches keep them apart (https://acceptmarkdown.com).
+ *
+ * This lives in middleware rather than a `rewrites` entry in vercel.json
+ * because vercel.json rewrites are only evaluated after the filesystem: with
+ * cleanUrls the static foo.html always matched first, so the rewrite never
+ * ran and agents got HTML. Middleware runs before the filesystem and before
+ * the CDN cache, and the rewritten path gives the markdown variant its own
+ * cache key.
+ *
+ * Mirror of apps/docs/middleware.ts — keep the two in sync.
+ */
+import { next, rewrite } from "@vercel/functions";
+import Negotiator from "negotiator";
+
+export const config = {
+  // Page URLs only. Skip the Vite asset dir and known static-file extensions
+  // (.md, sitemap.xml, llms.txt, images, fonts, ...). Listed
+  // explicitly instead of "contains a dot" because some page slugs contain
+  // version numbers.
+  matcher: [
+    "/((?!assets/|.*\\.(?:md|html|xml|txt|json|js|mjs|css|map|png|jpe?g|gif|svg|webp|avif|ico|woff2?|ttf|otf|pdf|zip)$).*)",
+  ],
+};
+
+const VARY_ACCEPT = { Vary: "Accept" };
+const HTML = "text/html; charset=utf-8";
+const MARKDOWN = "text/markdown; charset=utf-8";
+const REPRESENTATIONS = [HTML, MARKDOWN];
+
+function prefersMarkdown(accept: string | null): boolean {
+  try {
+    const negotiator = new Negotiator({ headers: { accept: accept ?? undefined } });
+    const explicitlyAcceptsMarkdown = negotiator
+      .mediaTypes()
+      .some((mediaType) => mediaType.toLowerCase() === "text/markdown");
+    return explicitlyAcceptsMarkdown && negotiator.mediaType(REPRESENTATIONS) === MARKDOWN;
+  } catch {
+    // Fall back to HTML when the header cannot be parsed.
+    return false;
+  }
+}
+
+export default function middleware(request: Request): Response {
+  if (!prefersMarkdown(request.headers.get("accept"))) {
+    return next({ headers: VARY_ACCEPT });
+  }
+
+  const url = new URL(request.url);
+  const path = url.pathname.replace(/\/+$/, "");
+  url.pathname = path === "" ? "/index.md" : `${path}.md`;
+  return rewrite(url, { headers: VARY_ACCEPT });
+}

apps/developer-docs/package.json

@@ -24,9 +24,12 @@
     "check:types": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@plane/docs-theme": "workspace:*"
+    "@plane/docs-theme": "workspace:*",
+    "@vercel/functions": "catalog:",
+    "negotiator": "catalog:"
   },
   "devDependencies": {
+    "@types/negotiator": "catalog:",
     "@types/node": "catalog:",
     "@voidzero-dev/vitepress-theme": "catalog:",
     "mermaid": "catalog:",

apps/developer-docs/tsconfig.json

@@ -1,5 +1,10 @@
 {
   "extends": "../../tsconfig.base.json",
-  "include": ["docs/.vitepress/**/*.ts", "docs/.vitepress/**/*.mts", "docs/.vitepress/**/*.vue"],
+  "include": [
+    "middleware.ts",
+    "docs/.vitepress/**/*.ts",
+    "docs/.vitepress/**/*.mts",
+    "docs/.vitepress/**/*.vue"
+  ],
   "exclude": ["docs/.vitepress/cache", "docs/.vitepress/dist", "docs/.vitepress/.temp"]
 }

apps/developer-docs/vercel.json

@@ -120,12 +120,5 @@
       "source": "/dev-tools/mcp-server-claude-code",
       "destination": "/dev-tools/mcp-server#claude-code"
     }
-  ],
-  "rewrites": [
-    {
-      "source": "/:path*",
-      "has": [{ "type": "header", "key": "accept", "value": ".*text/markdown.*" }],
-      "destination": "/:path*.md"
-    }
   ]
 }

apps/docs/AGENTS.md

@@ -36,7 +36,8 @@ docs/
   ai/                          # Plane AI features
   support/                     # Keyboard shortcuts, get help
   templates/                   # Page, project, work-item templates
-vercel.json                    # cleanUrls, headers, redirects, Accept: text/markdown rewrite
+vercel.json                    # cleanUrls, headers, redirects
+middleware.ts                  # Vercel Routing Middleware: Accept: text/markdown → /path.md (+ Vary: Accept)
 ```
 
 ## Content conventions

apps/docs/docs/.vitepress/config.ts

@@ -56,7 +56,7 @@ const config = defineConfig({
         details:
           "This documentation covers workspaces, projects, work items, cycles, modules, pages and wikis, integrations, importers, automations, and Plane AI.",
         // Per-page .md versions are already emitted by buildEnd() for the
-        // `Accept: text/markdown` rewrite in vercel.json, so the plugin only
+        // `Accept: text/markdown` negotiation in middleware.ts, so the plugin only
         // owns llms.txt / llms-full.txt.
         generateLLMFriendlyDocsForEachPage: false,
         // Don't inject invisible LLM-hint markup into rendered pages.
@@ -73,7 +73,7 @@ const config = defineConfig({
   },
 
   buildEnd(siteConfig) {
-    // Copy source .md files into dist/ for Accept: text/markdown negotiation.
+    // Copy source .md files into dist/ for Accept: text/markdown negotiation (see middleware.ts).
     const srcDir = siteConfig.srcDir;
     const outDir = siteConfig.outDir;
 

apps/docs/middleware.ts

@@ -0,0 +1,59 @@
+/**
+ * Vercel Routing Middleware for docs.plane.so — markdown content negotiation.
+ *
+ * Requests that prefer `text/markdown` over `text/html` are rewritten to the page's
+ * markdown source (`/foo` → `/foo.md`, `/` → `/index.md`); buildEnd() in
+ * docs/.vitepress/config.ts copies those files into dist/. Every other request
+ * falls through to the HTML page. Both variants carry `Vary: Accept` so
+ * downstream caches keep them apart (https://acceptmarkdown.com).
+ *
+ * This lives in middleware rather than a `rewrites` entry in vercel.json
+ * because vercel.json rewrites are only evaluated after the filesystem: with
+ * cleanUrls the static foo.html always matched first, so the rewrite never
+ * ran and agents got HTML. Middleware runs before the filesystem and before
+ * the CDN cache, and the rewritten path gives the markdown variant its own
+ * cache key.
+ *
+ * Mirror of apps/developer-docs/middleware.ts — keep the two in sync.
+ */
+import { next, rewrite } from "@vercel/functions";
+import Negotiator from "negotiator";
+
+export const config = {
+  // Page URLs only. Skip the Vite asset dir and known static-file extensions
+  // (.md, sitemap.xml, llms.txt, images, fonts, ...). Listed
+  // explicitly instead of "contains a dot" because some page slugs contain
+  // version numbers.
+  matcher: [
+    "/((?!assets/|.*\\.(?:md|html|xml|txt|json|js|mjs|css|map|png|jpe?g|gif|svg|webp|avif|ico|woff2?|ttf|otf|pdf|zip)$).*)",
+  ],
+};
+
+const VARY_ACCEPT = { Vary: "Accept" };
+const HTML = "text/html; charset=utf-8";
+const MARKDOWN = "text/markdown; charset=utf-8";
+const REPRESENTATIONS = [HTML, MARKDOWN];
+
+function prefersMarkdown(accept: string | null): boolean {
+  try {
+    const negotiator = new Negotiator({ headers: { accept: accept ?? undefined } });
+    const explicitlyAcceptsMarkdown = negotiator
+      .mediaTypes()
+      .some((mediaType) => mediaType.toLowerCase() === "text/markdown");
+    return explicitlyAcceptsMarkdown && negotiator.mediaType(REPRESENTATIONS) === MARKDOWN;
+  } catch {
+    // Fall back to HTML when the header cannot be parsed.
+    return false;
+  }
+}
+
+export default function middleware(request: Request): Response {
+  if (!prefersMarkdown(request.headers.get("accept"))) {
+    return next({ headers: VARY_ACCEPT });
+  }
+
+  const url = new URL(request.url);
+  const path = url.pathname.replace(/\/+$/, "");
+  url.pathname = path === "" ? "/index.md" : `${path}.md`;
+  return rewrite(url, { headers: VARY_ACCEPT });
+}

apps/docs/package.json

@@ -19,9 +19,12 @@
     "check:types": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@plane/docs-theme": "workspace:*"
+    "@plane/docs-theme": "workspace:*",
+    "@vercel/functions": "catalog:",
+    "negotiator": "catalog:"
   },
   "devDependencies": {
+    "@types/negotiator": "catalog:",
     "@types/node": "catalog:",
     "@voidzero-dev/vitepress-theme": "catalog:",
     "typescript": "catalog:",

apps/docs/tsconfig.json

@@ -1,5 +1,10 @@
 {
   "extends": "../../tsconfig.base.json",
-  "include": ["docs/.vitepress/**/*.ts", "docs/.vitepress/**/*.mts", "docs/.vitepress/**/*.vue"],
+  "include": [
+    "middleware.ts",
+    "docs/.vitepress/**/*.ts",
+    "docs/.vitepress/**/*.mts",
+    "docs/.vitepress/**/*.vue"
+  ],
   "exclude": ["docs/.vitepress/cache", "docs/.vitepress/dist", "docs/.vitepress/.temp"]
 }

apps/docs/vercel.json

@@ -305,12 +305,5 @@
       "source": "/core-concepts/pages/nested-pages",
       "destination": "/pages/nested-pages"
     }
-  ],
-  "rewrites": [
-    {
-      "source": "/:path*",
-      "has": [{ "type": "header", "key": "accept", "value": ".*text/markdown.*" }],
-      "destination": "/:path*.md"
-    }
   ]
 }