From a39e4db57b36bec7fc6d3e92a025d7cdbba4437f Mon Sep 17 00:00:00 2001
From: Lenny Chen <lenny.chen@temporal.io>
Date: Mon, 24 Aug 2026 15:14:03 -0700
Subject: [PATCH] fix: improve Markdown content negotiation

---
 api/markdown-not-found.js | 18 ++++++++++++++++++
 middleware.js             |  5 +++--
 vercel.json               | 11 +++++++++++
 3 files changed, 32 insertions(+), 2 deletions(-)
 create mode 100644 api/markdown-not-found.js

diff --git a/api/markdown-not-found.js b/api/markdown-not-found.js
new file mode 100644
index 0000000000..2dcd80916b
--- /dev/null
+++ b/api/markdown-not-found.js
@@ -0,0 +1,18 @@
+const body = `# Page not found
+
+This URL does not match a page in the Temporal documentation.
+
+## Where to look next
+
+- [Documentation index](https://docs.temporal.io/llms.txt)
+- [Documentation sitemap](https://docs.temporal.io/sitemap.xml)
+- [Temporal documentation home](https://docs.temporal.io/)
+`;
+
+module.exports = (_request, response) => {
+  response
+    .status(404)
+    .setHeader('Content-Type', 'text/markdown; charset=utf-8')
+    .setHeader('Vary', 'Accept, Accept-Encoding')
+    .send(body);
+};
diff --git a/middleware.js b/middleware.js
index 44f34188db..2b76470222 100644
--- a/middleware.js
+++ b/middleware.js
@@ -2,14 +2,15 @@ import { rewrite, next } from '@vercel/functions';
 
 export default function middleware(request) {
   const accept = request.headers.get('accept') || '';
+  const headers = { Vary: 'Accept, Accept-Encoding' };
 
   if (accept.includes('text/markdown')) {
     const url = new URL(request.url);
     const path = url.pathname.replace(/\/+$/, '') || '/index';
-    return rewrite(new URL(`${path}.md`, request.url));
+    return rewrite(new URL(`${path}.md`, request.url), { headers });
   }
 
-  return next();
+  return next({ headers });
 }
 
 export const config = {
diff --git a/vercel.json b/vercel.json
index fde161136a..978fa0e5b1 100644
--- a/vercel.json
+++ b/vercel.json
@@ -7,6 +7,17 @@
     {
       "source": "/img/og/:path*",
       "destination": "/img/assets/open-graph-shiny.jpg"
+    },
+    {
+      "source": "/:path((?!api/).*)",
+      "has": [
+        {
+          "type": "header",
+          "key": "accept",
+          "value": ".*text/markdown.*"
+        }
+      ],
+      "destination": "/api/markdown-not-found"
     }
   ],
   "headers": [