questdb · jerrinot · May 18, 2026 · May 19, 2026
diff --git a/plugins/raw-markdown/index.js b/plugins/raw-markdown/index.js
@@ -8,10 +8,11 @@ const {
   prependFrontmatter,
   normalizeNewLines,
 } = require("./convert-components")
+const { getMarkdownUrl } = require("../../src/utils/markdown-url")
 
 module.exports = () => ({
   name: "raw-markdown",
-  async postBuild({ outDir, plugins }) {
+  async postBuild({ siteConfig, outDir, plugins }) {
     const docsPath = path.join(__dirname, "../../documentation")
     const outputBase = outDir
 
@@ -110,6 +111,32 @@ module.exports = () => ({
 
           fs.writeFileSync(outputFile, processedContent, "utf8")
           fileCount++
+
+          // Advertise the .md companion in the rendered HTML's <head> so
+          // HTML-parsing agents can discover it without sniffing URL patterns.
+          // URL format matches CopyPageButton via the shared getMarkdownUrl
+          // helper. Assumes docusaurus.config.js keeps `trailingSlash: true`
+          // so HTML lands at ${urlPath}/index.html.
+          const htmlPath = urlPath
+            ? path.join(outputBase, urlPath, "index.html")
+            : path.join(outputBase, "index.html")
+          if (fs.existsSync(htmlPath)) {
+            const pageUrl = urlPath
+              ? path.posix.join(siteConfig.baseUrl, urlPath)
+              : siteConfig.baseUrl
+            const mdHref = getMarkdownUrl(pageUrl, siteConfig.baseUrl)
+            const tag = `<link rel="alternate" type="text/markdown" href="${mdHref}">`
+            const html = fs.readFileSync(htmlPath, "utf8")
+            if (!html.includes('type="text/markdown"')) {
+              const idx = html.lastIndexOf("</head>")
+              if (idx === -1) {
+                console.warn(`[raw-markdown] No </head> found in ${htmlPath}; skipping alternate link`)
+              } else {
+                const patched = html.slice(0, idx) + tag + html.slice(idx)
+                fs.writeFileSync(htmlPath, patched, "utf8")
+              }
+            }
+          }
         }
       }
     }

diff --git a/src/theme/CopyPageButton/index.tsx b/src/theme/CopyPageButton/index.tsx
@@ -6,6 +6,7 @@ import IconCopy from "@theme/Icon/Copy"
 import IconSuccess from "@theme/Icon/Success"
 import Chevron from "@theme/Chevron"
 import { ArrowTopRightOnSquareIcon } from "@heroicons/react/16/solid"
+import { getMarkdownUrl } from "../../utils/markdown-url"
 
 import styles from "./styles.module.css"
 
@@ -46,13 +47,10 @@ export default function CopyPageButton(): JSX.Element {
 
   const { siteConfig } = useDocusaurusContext()
 
-  const basePath = siteConfig.baseUrl.replace(/\/$/, "")
   const pathname = typeof window !== "undefined"
-    ? window.location.pathname.replace(/\/$/, "")
+    ? window.location.pathname
     : ""
-  const markdownUrl = pathname === basePath
-    ? basePath + "/index.md"
-    : pathname + ".md"
+  const markdownUrl = getMarkdownUrl(pathname, siteConfig.baseUrl)
 
   const pageUrl = siteConfig.url + markdownUrl
   const chatPrompt = `I'd like to ask some questions about ${pageUrl}.\n\n`

diff --git a/src/utils/markdown-url.js b/src/utils/markdown-url.js
@@ -0,0 +1,16 @@
+// Shared rule for translating a doc page URL to its `.md` companion.
+// Used by:
+//  - src/theme/CopyPageButton (runtime, via window.location.pathname)
+//  - plugins/raw-markdown (build time, via siteConfig.baseUrl + urlPath)
+// Plain JS (CommonJS) so the Docusaurus plugin can `require()` it directly;
+// `allowJs: true` in tsconfig.json lets the TSX side import it with types.
+
+function getMarkdownUrl(pathname, basePath) {
+  const normalized = pathname.replace(/\/$/, "")
+  const normalizedBase = (basePath || "").replace(/\/$/, "")
+  return normalized === normalizedBase
+    ? `${normalizedBase}/index.md`
+    : `${normalized}.md`
+}
+
+module.exports = { getMarkdownUrl }
diff --git a/static/_headers b/static/_headers
@@ -12,6 +12,7 @@
   Access-Control-Allow-Origin: *
   Access-Control-Allow-Methods: GET, OPTIONS
   Cache-Control: public, max-age=60
+  X-Robots-Tag: noindex
 
 /*/web-console/*.json
   Access-Control-Allow-Origin: *