From d59c95b0931559ddd961668b21d94d804a975849 Mon Sep 17 00:00:00 2001
From: Satyajit Sahoo <satyajit.happy@gmail.com>
Date: Wed, 4 Mar 2026 13:34:45 +0100
Subject: [PATCH 1/2] Add support for .md URLs

---
 docusaurus.config.ts                        |   7 +-
 src/__tests__/process-markdown.test.ts      | 296 +++++++++++++++
 src/components/CopyMarkdownButton/index.tsx |  59 +--
 src/plugins/llms-txt.ts                     | 231 ++++++++----
 src/plugins/process-markdown.ts             | 391 ++++++++++++++++++++
 src/plugins/rehype-static-to-dynamic.ts     |   2 +-
 src/plugins/remark-raw-markdown.ts          |  13 -
 7 files changed, 884 insertions(+), 115 deletions(-)
 create mode 100644 src/__tests__/process-markdown.test.ts
 create mode 100644 src/plugins/process-markdown.ts
 delete mode 100644 src/plugins/remark-raw-markdown.ts

diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index fa7af6a8ef..adc2c88869 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -9,7 +9,6 @@ import rehypeCodeblockMeta from './src/plugins/rehype-codeblock-meta.ts';
 import rehypeStaticToDynamic from './src/plugins/rehype-static-to-dynamic.ts';
 import rehypeVideoAspectRatio from './src/plugins/rehype-video-aspect-ratio.ts';
 import remarkNpm2Yarn from './src/plugins/remark-npm2yarn.ts';
-import remarkRawMarkdown from './src/plugins/remark-raw-markdown.ts';
 import darkTheme from './src/themes/react-navigation-dark';
 import lightTheme from './src/themes/react-navigation-light';
 
@@ -175,7 +174,7 @@ const config: Config = {
           },
           breadcrumbs: false,
           sidebarCollapsed: false,
-          remarkPlugins: [remarkRawMarkdown, [remarkNpm2Yarn, { sync: true }]],
+          remarkPlugins: [[remarkNpm2Yarn, { sync: true }]],
           rehypePlugins: [
             [
               rehypeCodeblockMeta,
@@ -186,10 +185,10 @@ const config: Config = {
           ],
         },
         blog: {
-          remarkPlugins: [remarkRawMarkdown, [remarkNpm2Yarn, { sync: true }]],
+          remarkPlugins: [[remarkNpm2Yarn, { sync: true }]],
         },
         pages: {
-          remarkPlugins: [remarkRawMarkdown, [remarkNpm2Yarn, { sync: true }]],
+          remarkPlugins: [[remarkNpm2Yarn, { sync: true }]],
         },
         theme: {
           customCss: './src/css/custom.css',
diff --git a/src/__tests__/process-markdown.test.ts b/src/__tests__/process-markdown.test.ts
new file mode 100644
index 0000000000..e737645990
--- /dev/null
+++ b/src/__tests__/process-markdown.test.ts
@@ -0,0 +1,296 @@
+import dedent from 'dedent';
+import assert from 'node:assert';
+import { describe, test } from 'node:test';
+import { processMarkdown } from '../plugins/process-markdown.ts';
+
+describe('processMarkdown', () => {
+  test('strips MDX import statements', async () => {
+    const input = dedent`
+      import Tabs from '@theme/Tabs';
+      import TabItem from '@theme/TabItem';
+
+      Some content here.
+    `;
+
+    const { content: result } = await processMarkdown(input);
+    assert.ok(!result.includes('import'));
+    assert.ok(result.includes('Some content here.'));
+  });
+
+  test('transforms Tabs with two TabItems into labeled sections', async () => {
+    const input = dedent`
+      Before tabs.
+
+      <Tabs groupId="config" queryString="config">
+      <TabItem value="static" label="Static" default>
+
+      Static content here.
+
+      </TabItem>
+      <TabItem value="dynamic" label="Dynamic">
+
+      Dynamic content here.
+
+      </TabItem>
+      </Tabs>
+
+      After tabs.
+    `;
+
+    const { content: result } = await processMarkdown(input);
+
+    assert.ok(!result.includes('<Tabs'));
+    assert.ok(!result.includes('<TabItem'));
+    assert.ok(!result.includes('</Tabs>'));
+    assert.ok(!result.includes('</TabItem>'));
+    assert.ok(result.includes('**Static:**'));
+    assert.ok(result.includes('Static content here.'));
+    assert.ok(result.includes('**Dynamic:**'));
+    assert.ok(result.includes('Dynamic content here.'));
+    assert.ok(result.includes('Before tabs.'));
+    assert.ok(result.includes('After tabs.'));
+  });
+
+  test('transforms nested Tabs', async () => {
+    const input = dedent`
+      <Tabs groupId='framework' queryString="framework">
+      <TabItem value='expo' label='Expo' default>
+
+      Expo instructions.
+
+      </TabItem>
+      <TabItem value='community-cli' label='Community CLI'>
+
+      CLI instructions.
+
+      <Tabs>
+      <TabItem value='kotlin' label='Kotlin' default>
+
+      Kotlin code.
+
+      </TabItem>
+      <TabItem value='java' label='Java'>
+
+      Java code.
+
+      </TabItem>
+      </Tabs>
+
+      More CLI content.
+
+      </TabItem>
+      </Tabs>
+    `;
+
+    const { content: result } = await processMarkdown(input);
+
+    assert.ok(!result.includes('<Tabs'));
+    assert.ok(!result.includes('<TabItem'));
+    assert.ok(result.includes('**Expo:**'));
+    assert.ok(result.includes('Expo instructions.'));
+    assert.ok(result.includes('**Community CLI:**'));
+    assert.ok(result.includes('CLI instructions.'));
+    assert.ok(result.includes('**Kotlin:**'));
+    assert.ok(result.includes('Kotlin code.'));
+    assert.ok(result.includes('**Java:**'));
+    assert.ok(result.includes('Java code.'));
+  });
+
+  test('handles single TabItem without label', async () => {
+    const input = dedent`
+      <Tabs>
+      <TabItem value="only" label="Only Option">
+
+      Only content.
+
+      </TabItem>
+      </Tabs>
+    `;
+
+    const { content: result } = await processMarkdown(input);
+
+    assert.ok(!result.includes('<Tabs'));
+    // Single tab should not have a label
+    assert.ok(!result.includes('**Only Option:**'));
+    assert.ok(result.includes('Only content.'));
+  });
+
+  test('transforms static2dynamic code fences', async () => {
+    const input = dedent`
+      Before code.
+
+      \`\`\`js name="Example" snack static2dynamic
+      import * as React from 'react';
+      import { createStaticNavigation } from '@react-navigation/native';
+      import { createNativeStackNavigator } from '@react-navigation/native-stack';
+
+      function HomeScreen() {
+        return null;
+      }
+
+      const MyStack = createNativeStackNavigator({
+        screens: {
+          Home: HomeScreen,
+        },
+      });
+
+      const Navigation = createStaticNavigation(MyStack);
+
+      export default function App() {
+        return <Navigation />;
+      }
+      \`\`\`
+
+      After code.
+    `;
+
+    const { content: result } = await processMarkdown(input);
+
+    assert.ok(result.includes('**Static:**'));
+    assert.ok(result.includes('**Dynamic:**'));
+    // The dynamic version should have NavigationContainer
+    assert.ok(result.includes('NavigationContainer'));
+    // Meta attributes should be stripped from fence lines
+    assert.ok(!result.includes('static2dynamic'));
+    // Check that 'snack' doesn't appear in fence meta (it may appear in code content)
+    assert.ok(!result.match(/^```\w*.*snack/m));
+    assert.ok(!result.match(/^```\w*.*name=/m));
+    assert.ok(result.includes('Before code.'));
+    assert.ok(result.includes('After code.'));
+  });
+
+  test('strips code fence meta attributes', async () => {
+    const input = dedent`
+      \`\`\`js name="Test" snack
+      const x = 1;
+      \`\`\`
+
+      \`\`\`bash npm2yarn
+      npm install something
+      \`\`\`
+    `;
+
+    const { content: result } = await processMarkdown(input);
+
+    assert.ok(!result.includes('name='));
+    assert.ok(!result.includes('snack'));
+    assert.ok(!result.includes('npm2yarn'));
+    assert.ok(result.includes('```js'));
+    assert.ok(result.includes('```bash'));
+    assert.ok(result.includes('const x = 1;'));
+    assert.ok(result.includes('npm install something'));
+  });
+
+  test('converts admonitions to blockquotes', async () => {
+    const input = dedent`
+      Some text.
+
+      :::warning
+
+      This is a warning.
+
+      ::::
+
+      More text.
+    `;
+
+    const { content: result } = await processMarkdown(input);
+
+    assert.ok(!result.includes(':::'));
+    assert.ok(result.includes('> **Warning:**'));
+    assert.ok(result.includes('> This is a warning.'));
+    assert.ok(result.includes('Some text.'));
+    assert.ok(result.includes('More text.'));
+  });
+
+  test('converts info admonitions', async () => {
+    const input = dedent`
+      :::info
+
+      Some info here.
+
+      ::::
+    `;
+
+    const { content: result } = await processMarkdown(input);
+
+    assert.ok(result.includes('> **Info:**'));
+    assert.ok(result.includes('> Some info here.'));
+  });
+
+  test('cleans up extra blank lines', async () => {
+    const input = 'Line 1.\n\n\n\n\nLine 2.';
+    const { content: result } = await processMarkdown(input);
+
+    assert.ok(!result.includes('\n\n\n'));
+    assert.ok(result.includes('Line 1.\n\nLine 2.'));
+  });
+
+  test('handles Tabs with code blocks inside', async () => {
+    const input = dedent`
+      <Tabs groupId="config" queryString="config">
+      <TabItem value="static" label="Static" default>
+
+      \`\`\`js
+      const x = createStackNavigator({});
+      \`\`\`
+
+      </TabItem>
+      <TabItem value="dynamic" label="Dynamic">
+
+      \`\`\`js
+      function MyStack() {
+        return <Stack.Navigator />;
+      }
+      \`\`\`
+
+      </TabItem>
+      </Tabs>
+    `;
+
+    const { content: result } = await processMarkdown(input);
+
+    assert.ok(result.includes('**Static:**'));
+    assert.ok(result.includes('createStackNavigator'));
+    assert.ok(result.includes('**Dynamic:**'));
+    assert.ok(result.includes('Stack.Navigator'));
+    assert.ok(!result.includes('<Tabs'));
+  });
+
+  test('preserves content outside of MDX constructs', async () => {
+    const input = dedent`
+      # Title
+
+      Regular paragraph with **bold** and [links](https://example.com).
+
+      - List item 1
+      - List item 2
+
+      > A blockquote.
+    `;
+
+    const { content: result } = await processMarkdown(input);
+
+    assert.strictEqual(result, input);
+  });
+
+  test('strips frontmatter and returns parsed data', async () => {
+    const input = dedent`
+      ---
+      id: getting-started
+      title: Getting started
+      description: Learn how to get started
+      ---
+
+      Some content here.
+    `;
+
+    const { frontmatter, content } = await processMarkdown(input);
+
+    assert.strictEqual(frontmatter.title, 'Getting started');
+    assert.strictEqual(frontmatter.description, 'Learn how to get started');
+    assert.strictEqual(frontmatter.id, 'getting-started');
+    assert.ok(!content.includes('---'));
+    assert.ok(content.includes('Some content here.'));
+  });
+});
diff --git a/src/components/CopyMarkdownButton/index.tsx b/src/components/CopyMarkdownButton/index.tsx
index 6475d9a76a..a38662d3a4 100644
--- a/src/components/CopyMarkdownButton/index.tsx
+++ b/src/components/CopyMarkdownButton/index.tsx
@@ -1,4 +1,3 @@
-import { useDoc } from '@docusaurus/plugin-content-docs/client';
 import { useEffect, useRef, useState } from 'react';
 import styles from './styles.module.css';
 
@@ -10,22 +9,36 @@ const ACTIONS = [
 
 type ActionType = (typeof ACTIONS)[number];
 
-export function CopyButton() {
-  const { frontMatter } = useDoc();
-
-  const markdown =
-    'rawMarkdown' in frontMatter && typeof frontMatter.rawMarkdown === 'string'
-      ? frontMatter.rawMarkdown
-      : null;
+function getMdPath() {
+  return `${window.location.pathname.replace(/\/$/, '')}.md`;
+}
 
+export function CopyButton() {
   const [isOpen, setIsOpen] = useState(false);
   const [isVisible, setIsVisible] = useState(false);
   const [copied, setCopied] = useState(false);
 
+  const markdownRef = useRef<Promise<string | null> | undefined>(undefined);
+
   const containerRef = useRef<HTMLDivElement>(null);
   const dropdownRef = useRef<HTMLDivElement>(null);
   const buttonRef = useRef<HTMLButtonElement>(null);
 
+  const loadMarkdown = () => {
+    const promise = fetch(getMdPath())
+      .then((res) => (res.ok ? res.text() : null))
+      .catch(() => null);
+
+    markdownRef.current = promise;
+
+    return promise;
+  };
+
+  // Preload the .md file on mount so it's ready when the user clicks copy
+  useEffect(() => {
+    loadMarkdown();
+  }, []);
+
   useEffect(() => {
     if (!isOpen) {
       return;
@@ -58,27 +71,29 @@ export function CopyButton() {
   };
 
   const onAction = (action: ActionType) => {
-    const prompt = `Read from ${window.location.href} so I can ask questions about it.`;
-
     switch (action.value) {
       case 'copy':
-        if (markdown) {
-          navigator.clipboard.writeText(markdown).then(() => {
-            setCopied(true);
-            setTimeout(() => setCopied(false), 2000);
+        (markdownRef.current ?? loadMarkdown())
+          .then((markdown) => markdown ?? loadMarkdown())
+          .then((markdown) => {
+            if (markdown) {
+              navigator.clipboard.writeText(markdown).then(() => {
+                setCopied(true);
+                setTimeout(() => setCopied(false), 2000);
+              });
+            }
           });
-        }
 
         break;
       case 'chatgpt':
-      case 'claude':
-        window.open(
-          `${action.href}?q=${encodeURIComponent(prompt)}`,
+      case 'claude': {
+        const mdUrl = `${window.location.origin}${getMdPath()}`;
+        const prompt = `Read from ${mdUrl} so I can ask questions about it.`;
 
-          '_blank'
-        );
+        window.open(`${action.href}?q=${encodeURIComponent(prompt)}`, '_blank');
 
         break;
+      }
     }
 
     onClose();
@@ -127,10 +142,6 @@ export function CopyButton() {
     }
   };
 
-  if (!markdown) {
-    return null;
-  }
-
   return (
     <div className={styles.container} ref={containerRef} onKeyDown={onKeyDown}>
       <button
diff --git a/src/plugins/llms-txt.ts b/src/plugins/llms-txt.ts
index aa17e3cb8c..d0a66f0d01 100644
--- a/src/plugins/llms-txt.ts
+++ b/src/plugins/llms-txt.ts
@@ -1,15 +1,13 @@
+import type { LoadContext, Plugin } from '@docusaurus/types';
 import fs from 'node:fs';
 import path from 'node:path';
 import util from 'node:util';
-import type { LoadContext, Plugin } from '@docusaurus/types';
 import versionsData from '../../versions.json';
-
-type FrontMatterData = Record<string, string>;
-
-type ParsedFrontMatter = {
-  data: FrontMatterData;
-  content: string;
-};
+import {
+  buildMarkdownDocument,
+  parseFrontmatter,
+  processMarkdown,
+} from './process-markdown.ts';
 
 type SidebarCategory = {
   type: 'category';
@@ -20,6 +18,7 @@ type SidebarCategory = {
 type SidebarItem = string | SidebarCategory | Record<string, unknown>;
 
 type FullDoc = {
+  id: string;
   title: string;
   url: string;
   content: string;
@@ -99,49 +98,6 @@ function normalizeRootItems(value: unknown): SidebarItem[] {
   return [];
 }
 
-/**
- * Parses frontmatter from markdown content.
- * Extracts metadata like title and description, and returns the cleaned content.
- *
- * @param {string} fileContent - Raw markdown file content.
- * @returns {{data: Object, content: string}} - Parsed data and stripped content.
- */
-function parseFrontMatter(fileContent: string): ParsedFrontMatter {
-  const frontMatterRegex = /^---\n([\s\S]+?)\n---\n/;
-  const match = fileContent.match(frontMatterRegex);
-
-  if (!match) {
-    return { data: {}, content: fileContent };
-  }
-
-  const frontMatterBlock = match[1];
-  const content = fileContent.replace(frontMatterRegex, '');
-
-  const data: FrontMatterData = {};
-
-  frontMatterBlock.split('\n').forEach((line) => {
-    const parts = line.split(':');
-
-    if (parts.length >= 2) {
-      const key = parts[0].trim();
-
-      let value = parts.slice(1).join(':').trim();
-
-      // Remove surrounding quotes if present
-      if (
-        (value.startsWith("'") && value.endsWith("'")) ||
-        (value.startsWith('"') && value.endsWith('"'))
-      ) {
-        value = value.slice(1, -1);
-      }
-
-      data[key] = value;
-    }
-  });
-
-  return { data, content };
-}
-
 /**
  * Recursively processes sidebar items to generate the LLM index and collect full docs.
  * Handles different sidebar structures (flat arrays, categories).
@@ -173,7 +129,7 @@ function processSidebar(
 
       if (fs.existsSync(filePath)) {
         const fileContent = fs.readFileSync(filePath, 'utf8');
-        const { data, content } = parseFrontMatter(fileContent);
+        const { data, content } = parseFrontmatter(fileContent);
 
         const title = data.title || id;
         const description = data.description || '';
@@ -188,6 +144,7 @@ function processSidebar(
         }\n`;
 
         fullDocsList.push({
+          id,
           title,
           url: fullUrl,
           content,
@@ -219,18 +176,18 @@ function processSidebar(
 }
 
 /**
- * Generates the llms.txt and llms-full.txt files for a specific version.
+ * Generates the llms.txt, llms-full.txt, and individual .md files for a specific version.
  *
  * @returns {Array<string>} - List of generated filenames.
  */
-function generateForVersion(
+async function generateForVersion(
   siteDir: string,
   outDir: string,
   version: string,
   outputPrefix: string,
   isLatest: boolean,
   baseUrl: string
-): string[] {
+): Promise<string[]> {
   const docsPath = path.join(siteDir, 'versioned_docs', `version-${version}`);
   const sidebarPath = path.join(
     siteDir,
@@ -275,31 +232,110 @@ function generateForVersion(
 
   fs.writeFileSync(path.join(outDir, summaryFilename), llmsTxt);
 
-  // 2. Generate Full Content (llms-full.txt)
+  // The llms.txt URL for this version (used as sitemap link in .md files)
+  const llmsTxtUrl = `${baseUrl}/${summaryFilename}`;
+
+  // 2. Process all docs in parallel
+  const processedDocs = await Promise.all(
+    docs.map(async (doc) => {
+      const { content: processedContent } = await processMarkdown(doc.content);
+      return { ...doc, processedContent };
+    })
+  );
+
+  // 3. Generate Full Content (llms-full.txt)
   let llmsFullTxt = `# React Navigation ${version} Documentation\n\n`;
 
-  docs.forEach((doc) => {
+  processedDocs.forEach((doc) => {
     llmsFullTxt += `## ${doc.title}\n\n`;
     llmsFullTxt += `Source: ${doc.url}\n\n`;
-    llmsFullTxt += `${doc.content.trim()}\n\n---\n\n`;
+    llmsFullTxt += `${doc.processedContent}\n\n---\n\n`;
   });
 
-  // Determine full filename (e.g., llms-v8.x -> llms-full-v8.x.txt)
-  let fullFilename;
+  const fullFilename = isLatest
+    ? 'llms-full.txt'
+    : `llms-full-${version}.txt`;
+
+  fs.writeFileSync(path.join(outDir, fullFilename), llmsFullTxt);
+
+  // 4. Generate individual .md files for each doc
+  const mdFiles = processedDocs.map((doc) => {
+    const urlPath = isLatest
+      ? `/docs/${doc.id}`
+      : `/docs/${version}/${doc.id}`;
+
+    const mdFilePath = path.join(outDir, `${urlPath}.md`);
+    const mdDir = path.dirname(mdFilePath);
+
+    fs.mkdirSync(mdDir, { recursive: true });
+
+    const mdContent = buildMarkdownDocument(doc.processedContent, {
+      title: doc.title,
+      version,
+      sitemapUrl: llmsTxtUrl,
+      sitemapLabel: summaryFilename,
+    });
 
-  if (outputPrefix === 'llms') {
-    fullFilename = 'llms-full.txt';
-  } else {
-    if (outputPrefix.includes('llms-')) {
-      fullFilename = outputPrefix.replace('llms-', 'llms-full-') + '.txt';
-    } else {
-      fullFilename = outputPrefix + '-full.txt';
+    fs.writeFileSync(mdFilePath, mdContent + '\n');
+
+    return `${urlPath}.md`;
+  });
+
+  return [summaryFilename, fullFilename, ...mdFiles];
+}
+
+async function serveMarkdown(
+  siteDir: string,
+  baseUrl: string,
+  latestVersion: string,
+  reqPath: string
+): Promise<string | null> {
+  // Parse URL: /docs/[version/]<id>.md
+  const match = reqPath.match(/^\/docs\/(.+)\.md$/);
+
+  if (!match) {
+    return null;
+  }
+
+  const pathPart = match[1];
+
+  // Check if first segment is a known version
+  let version = latestVersion;
+  let docId = pathPart;
+
+  const firstSlash = pathPart.indexOf('/');
+
+  if (firstSlash !== -1) {
+    const possibleVersion = pathPart.substring(0, firstSlash);
+
+    if (versions.includes(possibleVersion)) {
+      version = possibleVersion;
+      docId = pathPart.substring(firstSlash + 1);
     }
   }
 
-  fs.writeFileSync(path.join(outDir, fullFilename), llmsFullTxt);
+  const docsPath = path.join(siteDir, 'versioned_docs', `version-${version}`);
+  const filePath = path.join(docsPath, `${docId}.md`);
 
-  return [summaryFilename, fullFilename];
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  const fileContent = fs.readFileSync(filePath, 'utf8');
+  const { frontmatter, content } = await processMarkdown(fileContent);
+
+  const isLatest = version === latestVersion;
+  const summaryFilename = isLatest ? 'llms.txt' : `llms-${version}.txt`;
+  const llmsTxtUrl = `${baseUrl}/${summaryFilename}`;
+
+  return (
+    buildMarkdownDocument(content, {
+      title: frontmatter.title || docId,
+      version,
+      sitemapUrl: llmsTxtUrl,
+      sitemapLabel: summaryFilename,
+    }) + '\n'
+  );
 }
 
 export default function llmsTxtPlugin(
@@ -308,6 +344,55 @@ export default function llmsTxtPlugin(
 ): Plugin {
   return {
     name: 'llms.txt',
+
+    configureWebpack() {
+      const { latestVersion } = options;
+
+      if (!latestVersion) {
+        return {};
+      }
+
+      return {
+        devServer: {
+          setupMiddlewares(middlewares: unknown[]) {
+            middlewares.unshift({
+              name: 'llms-txt',
+              middleware: (
+                req: { originalUrl: string },
+                res: {
+                  type: (t: string) => void;
+                  status: (s: number) => typeof res;
+                  send: (b: string) => void;
+                  end: () => void;
+                },
+                next: () => void
+              ) => {
+                serveMarkdown(
+                  context.siteDir,
+                  context.siteConfig.url,
+                  latestVersion,
+                  req.originalUrl
+                )
+                  .then((content) => {
+                    if (content) {
+                      res.type('text/markdown');
+                      res.send(content);
+                    } else {
+                      next();
+                    }
+                  })
+                  .catch(() => {
+                    res.status(500).end();
+                  });
+              },
+            });
+
+            return middlewares;
+          },
+        },
+      } as Record<string, unknown>;
+    },
+
     async postBuild({ siteDir, outDir }) {
       const { latestVersion } = options;
       const baseUrl = context.siteConfig.url;
@@ -316,14 +401,14 @@ export default function llmsTxtPlugin(
         throw new Error('[llms.txt] "latestVersion" option is required.');
       }
 
-      const generatedFiles = [];
+      const generatedFiles: string[] = [];
 
-      versions.forEach((version) => {
+      for (const version of versions) {
         const isLatest = version === latestVersion;
         // Prefix: 'llms' for latest, 'llms-vX.x' for others
         const outputPrefix = isLatest ? 'llms' : `llms-${version}`;
 
-        const files = generateForVersion(
+        const files = await generateForVersion(
           siteDir,
           outDir,
           version,
@@ -333,7 +418,7 @@ export default function llmsTxtPlugin(
         );
 
         generatedFiles.push(...files);
-      });
+      }
 
       console.log(
         `${util.styleText(['magenta', 'bold'], '[llms.txt]')} Wrote ${generatedFiles.length} files in build output.`
diff --git a/src/plugins/process-markdown.ts b/src/plugins/process-markdown.ts
new file mode 100644
index 0000000000..1aba36b4fe
--- /dev/null
+++ b/src/plugins/process-markdown.ts
@@ -0,0 +1,391 @@
+import { convertStaticToDynamic } from './rehype-static-to-dynamic.ts';
+
+type TabItem = {
+  label: string;
+  content: string;
+};
+
+type TabsBlock = {
+  start: number;
+  end: number;
+  items: TabItem[];
+};
+
+type FrontMatterData = Record<string, string>;
+
+export type ProcessedMarkdown = {
+  frontmatter: FrontMatterData;
+  content: string;
+};
+
+/**
+ * Parse frontmatter and process raw MDX markdown into clean, LLM-friendly markdown.
+ *
+ * - Parses and strips YAML frontmatter
+ * - Strips MDX import statements
+ * - Transforms <Tabs>/<TabItem> into labeled sections
+ * - Converts static2dynamic code fences into static + dynamic sections
+ * - Strips code fence meta attributes (snack, name, static2dynamic, npm2yarn, etc.)
+ * - Converts Docusaurus admonitions (:::note, :::warning, etc.) to blockquotes
+ * - Cleans up extra blank lines
+ */
+export async function processMarkdown(
+  rawContent: string
+): Promise<ProcessedMarkdown> {
+  const { data: frontmatter, content: contentWithoutFrontmatter } =
+    parseFrontmatter(rawContent);
+
+  let result = contentWithoutFrontmatter;
+
+  // Strip MDX import statements
+  result = stripImports(result);
+
+  // Transform <Tabs>/<TabItem> blocks (handles nesting)
+  result = transformTabs(result);
+
+  // Transform static2dynamic code fences
+  result = await transformStatic2Dynamic(result);
+
+  // Strip code fence meta attributes
+  result = stripCodeFenceMeta(result);
+
+  // Convert admonitions to blockquotes
+  result = convertAdmonitions(result);
+
+  // Clean up extra blank lines (max 2 consecutive)
+  result = result.replace(/\n{3,}/g, '\n\n');
+
+  return { frontmatter, content: result.trim() };
+}
+
+type BuildDocumentOptions = {
+  title?: string;
+  version?: string;
+  sitemapUrl?: string;
+  sitemapLabel?: string;
+};
+
+/**
+ * Build a complete markdown document with header metadata.
+ */
+export function buildMarkdownDocument(
+  processedContent: string,
+  options: BuildDocumentOptions = {}
+): string {
+  const { title, version, sitemapUrl, sitemapLabel } = options;
+  const parts: string[] = [];
+
+  if (title) {
+    parts.push(`# ${title}`);
+  }
+
+  if (version) {
+    parts.push(`Version: ${version}`);
+  }
+
+  if (sitemapUrl && sitemapLabel) {
+    parts.push(`Sitemap: [${sitemapLabel}](${sitemapUrl})`);
+  }
+
+  parts.push(processedContent);
+
+  return parts.join('\n\n');
+}
+
+/**
+ * Parse YAML frontmatter block and return data + content without frontmatter.
+ */
+export function parseFrontmatter(fileContent: string): {
+  data: FrontMatterData;
+  content: string;
+} {
+  const frontMatterRegex = /^---\n([\s\S]+?)\n---\n/;
+  const match = fileContent.match(frontMatterRegex);
+
+  if (!match) {
+    return { data: {}, content: fileContent };
+  }
+
+  const frontMatterBlock = match[1];
+  const content = fileContent.replace(frontMatterRegex, '');
+
+  const data: FrontMatterData = {};
+
+  frontMatterBlock.split('\n').forEach((line) => {
+    const parts = line.split(':');
+
+    if (parts.length >= 2) {
+      const key = parts[0].trim();
+
+      let value = parts.slice(1).join(':').trim();
+
+      // Remove surrounding quotes if present
+      if (
+        (value.startsWith("'") && value.endsWith("'")) ||
+        (value.startsWith('"') && value.endsWith('"'))
+      ) {
+        value = value.slice(1, -1);
+      }
+
+      data[key] = value;
+    }
+  });
+
+  return { data, content };
+}
+
+/**
+ * Remove MDX import lines (e.g. `import Tabs from '@theme/Tabs'`)
+ */
+function stripImports(content: string): string {
+  return (
+    content
+      // Single-line: import X from 'y'
+      .replace(/^import\s+.*?from\s+['"].*?['"];?\s*$/gm, '')
+      // Multi-line: import { ... } from 'y'
+      .replace(/^import\s*\{[^}]*\}\s*from\s*['"].*?['"];?\s*$/gm, '')
+  );
+}
+
+/**
+ * Transform all <Tabs>/<TabItem> blocks into plain markdown sections.
+ * Handles nested tabs by processing innermost first.
+ */
+function transformTabs(content: string): string {
+  // Process repeatedly until no more <Tabs> blocks remain
+  // (handles nesting by resolving innermost first)
+  let result = content;
+  let iterations = 0;
+  const maxIterations = 20;
+
+  while (result.includes('<Tabs') && iterations < maxIterations) {
+    const block = findInnermostTabsBlock(result);
+
+    if (!block) {
+      break;
+    }
+
+    const replacement = renderTabsAsMarkdown(block.items);
+    result =
+      result.slice(0, block.start) + replacement + result.slice(block.end);
+
+    iterations++;
+  }
+
+  return result;
+}
+
+/**
+ * Find the innermost (most deeply nested) <Tabs> block.
+ * This ensures nested tabs are resolved before their parents.
+ */
+function findInnermostTabsBlock(content: string): TabsBlock | null {
+  // Find all <Tabs opening positions
+  const tabsOpenRegex = /<Tabs[^>]*>/g;
+  let lastInnermost: { openStart: number; openEnd: number } | null = null;
+  let match: RegExpExecArray | null;
+
+  while ((match = tabsOpenRegex.exec(content)) !== null) {
+    const openStart = match.index;
+    const openEnd = openStart + match[0].length;
+
+    // Check if there's another <Tabs before the closing </Tabs>
+    const closingPos = content.indexOf('</Tabs>', openEnd);
+
+    if (closingPos === -1) {
+      continue;
+    }
+
+    const between = content.slice(openEnd, closingPos);
+
+    // If no nested <Tabs inside, this is an innermost block
+    if (!between.includes('<Tabs')) {
+      lastInnermost = { openStart, openEnd };
+      break;
+    }
+  }
+
+  if (!lastInnermost) {
+    return null;
+  }
+
+  const { openStart, openEnd } = lastInnermost;
+  const closingTag = '</Tabs>';
+  const closingPos = content.indexOf(closingTag, openEnd);
+
+  if (closingPos === -1) {
+    return null;
+  }
+
+  const innerContent = content.slice(openEnd, closingPos);
+  const items = parseTabItems(innerContent);
+
+  return {
+    start: openStart,
+    end: closingPos + closingTag.length,
+    items,
+  };
+}
+
+/**
+ * Parse <TabItem> elements from the inner content of a <Tabs> block.
+ */
+function parseTabItems(content: string): TabItem[] {
+  const items: TabItem[] = [];
+  const tabItemRegex =
+    /<TabItem\s+[^>]*label=['"]([^'"]+)['"][^>]*>([\s\S]*?)(?=<\/TabItem>)/g;
+
+  let match: RegExpExecArray | null;
+
+  while ((match = tabItemRegex.exec(content)) !== null) {
+    items.push({
+      label: match[1],
+      content: match[2].trim(),
+    });
+  }
+
+  // If regex didn't match (e.g. label comes after value), try alternative order
+  if (items.length === 0) {
+    const altRegex =
+      /<TabItem\s+[^>]*?(?:label=['"]([^'"]+)['"]|value=['"]([^'"]+)['"])[^>]*>([\s\S]*?)(?=<\/TabItem>)/g;
+
+    while ((match = altRegex.exec(content)) !== null) {
+      const label = match[1] || match[2] || 'Tab';
+      items.push({
+        label,
+        content: match[3].trim(),
+      });
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Render parsed tab items as plain markdown with bold labels.
+ */
+function renderTabsAsMarkdown(items: TabItem[]): string {
+  if (items.length === 0) {
+    return '';
+  }
+
+  // If only one tab, just render its content without label
+  if (items.length === 1) {
+    return items[0].content;
+  }
+
+  return items
+    .map((item) => `**${item.label}:**\n\n${item.content}`)
+    .join('\n\n');
+}
+
+/**
+ * Find and transform code fences with `static2dynamic` in their meta.
+ * Generates both static and dynamic versions.
+ */
+async function transformStatic2Dynamic(content: string): Promise<string> {
+  // Match code fences with static2dynamic in meta
+  const fenceRegex = /^(```\w*)\s+([^\n]*static2dynamic[^\n]*)\n([\s\S]*?)^```$/gm;
+  const matches: { fullMatch: string; lang: string; meta: string; code: string }[] = [];
+
+  let match: RegExpExecArray | null;
+
+  while ((match = fenceRegex.exec(content)) !== null) {
+    matches.push({
+      fullMatch: match[0],
+      lang: match[1].replace('```', ''),
+      meta: match[2],
+      code: match[3],
+    });
+  }
+
+  // Process all static2dynamic blocks in parallel
+  const conversions = await Promise.all(
+    matches.map(async (m) => {
+      try {
+        const dynamicCode = await convertStaticToDynamic(m.code);
+        const cleanMeta = cleanCodeFenceMeta(m.meta);
+        const langTag = m.lang || 'js';
+        const metaSuffix = cleanMeta ? ` ${cleanMeta}` : '';
+
+        const staticSection =
+          `**Static:**\n\n\`\`\`${langTag}${metaSuffix}\n${m.code}\`\`\``;
+        const dynamicSection =
+          `**Dynamic:**\n\n\`\`\`${langTag}${metaSuffix}\n${dynamicCode}\n\`\`\``;
+
+        return {
+          original: m.fullMatch,
+          replacement: `${staticSection}\n\n${dynamicSection}`,
+        };
+      } catch {
+        // If conversion fails, keep the original code without static2dynamic meta
+        const cleanMeta = cleanCodeFenceMeta(m.meta);
+        const metaSuffix = cleanMeta ? ` ${cleanMeta}` : '';
+
+        return {
+          original: m.fullMatch,
+          replacement: `\`\`\`${m.lang}${metaSuffix}\n${m.code}\`\`\``,
+        };
+      }
+    })
+  );
+
+  let result = content;
+
+  for (const { original, replacement } of conversions) {
+    result = result.replace(original, replacement);
+  }
+
+  return result;
+}
+
+/**
+ * Clean code fence meta by removing MDX-specific attributes.
+ * Removes: static2dynamic, snack, npm2yarn, name="...", dependencies="..."
+ */
+function cleanCodeFenceMeta(meta: string): string {
+  return meta
+    .replace(/\bstatic2dynamic\b/g, '')
+    .replace(/\bsnack\b/g, '')
+    .replace(/\bnpm2yarn\b/g, '')
+    .replace(/\bname=["'][^"']*["']/g, '')
+    .replace(/\bdependencies=["'][^"']*["']/g, '')
+    .trim()
+    .replace(/\s+/g, ' ');
+}
+
+/**
+ * Strip meta attributes from all code fences (not just static2dynamic ones).
+ */
+function stripCodeFenceMeta(content: string): string {
+  return content.replace(
+    /^(```\w*)[ \t]+([^\n]*?)$/gm,
+    (_match, lang: string, meta: string) => {
+      const cleaned = cleanCodeFenceMeta(meta);
+      return cleaned ? `${lang} ${cleaned}` : lang;
+    }
+  );
+}
+
+/**
+ * Convert Docusaurus admonitions (:::note, :::warning, etc.) to blockquotes.
+ *
+ * :::warning          >  > **Warning:**
+ * Content here   =>   >  > Content here
+ * ::::               >
+ */
+function convertAdmonitions(content: string): string {
+  return content.replace(
+    /^:::(\w+)\s*\n([\s\S]*?)^:::+\s*$/gm,
+    (_match, type: string, body: string) => {
+      const label = type.charAt(0).toUpperCase() + type.slice(1);
+      const trimmedBody = body.trim();
+      const quoted = trimmedBody
+        .split('\n')
+        .map((line) => `> ${line}`)
+        .join('\n');
+
+      return `> **${label}:**\n>\n${quoted}`;
+    }
+  );
+}
diff --git a/src/plugins/rehype-static-to-dynamic.ts b/src/plugins/rehype-static-to-dynamic.ts
index d3efeb0159..2126edd0e3 100644
--- a/src/plugins/rehype-static-to-dynamic.ts
+++ b/src/plugins/rehype-static-to-dynamic.ts
@@ -232,7 +232,7 @@ export default function rehypeStaticToDynamic() {
  * 5. Post-process: Inject comments into formatted code
  *    - Comments are injected as strings since Prettier may move/remove AST comments
  */
-async function convertStaticToDynamic(code: string): Promise<string> {
+export async function convertStaticToDynamic(code: string): Promise<string> {
   // Parse the code into AST using recast with comment attachment enabled
   const ast = recast.parse(code, {
     parser: {
diff --git a/src/plugins/remark-raw-markdown.ts b/src/plugins/remark-raw-markdown.ts
deleted file mode 100644
index 4ae2ce34d4..0000000000
--- a/src/plugins/remark-raw-markdown.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-type RemarkFile = {
-  data: Record<string, any>;
-  value: unknown;
-};
-
-const plugin = () => {
-  return (_tree: unknown, file: RemarkFile) => {
-    file.data.frontMatter = file.data.frontMatter || {};
-    file.data.frontMatter.rawMarkdown = file.value;
-  };
-};
-
-export default plugin;

From 543fc0423df4ee02fdb1f44aa7aaf2d9a125adf6 Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Wed, 4 Mar 2026 13:10:27 +0000
Subject: [PATCH 2/2] [autofix.ci] apply automated fixes

---
 src/plugins/llms-txt.ts         |  8 ++------
 src/plugins/process-markdown.ts | 16 ++++++++++------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/src/plugins/llms-txt.ts b/src/plugins/llms-txt.ts
index d0a66f0d01..0ef2c7d6cf 100644
--- a/src/plugins/llms-txt.ts
+++ b/src/plugins/llms-txt.ts
@@ -252,17 +252,13 @@ async function generateForVersion(
     llmsFullTxt += `${doc.processedContent}\n\n---\n\n`;
   });
 
-  const fullFilename = isLatest
-    ? 'llms-full.txt'
-    : `llms-full-${version}.txt`;
+  const fullFilename = isLatest ? 'llms-full.txt' : `llms-full-${version}.txt`;
 
   fs.writeFileSync(path.join(outDir, fullFilename), llmsFullTxt);
 
   // 4. Generate individual .md files for each doc
   const mdFiles = processedDocs.map((doc) => {
-    const urlPath = isLatest
-      ? `/docs/${doc.id}`
-      : `/docs/${version}/${doc.id}`;
+    const urlPath = isLatest ? `/docs/${doc.id}` : `/docs/${version}/${doc.id}`;
 
     const mdFilePath = path.join(outDir, `${urlPath}.md`);
     const mdDir = path.dirname(mdFilePath);
diff --git a/src/plugins/process-markdown.ts b/src/plugins/process-markdown.ts
index 1aba36b4fe..881a13dce7 100644
--- a/src/plugins/process-markdown.ts
+++ b/src/plugins/process-markdown.ts
@@ -285,8 +285,14 @@ function renderTabsAsMarkdown(items: TabItem[]): string {
  */
 async function transformStatic2Dynamic(content: string): Promise<string> {
   // Match code fences with static2dynamic in meta
-  const fenceRegex = /^(```\w*)\s+([^\n]*static2dynamic[^\n]*)\n([\s\S]*?)^```$/gm;
-  const matches: { fullMatch: string; lang: string; meta: string; code: string }[] = [];
+  const fenceRegex =
+    /^(```\w*)\s+([^\n]*static2dynamic[^\n]*)\n([\s\S]*?)^```$/gm;
+  const matches: {
+    fullMatch: string;
+    lang: string;
+    meta: string;
+    code: string;
+  }[] = [];
 
   let match: RegExpExecArray | null;
 
@@ -308,10 +314,8 @@ async function transformStatic2Dynamic(content: string): Promise<string> {
         const langTag = m.lang || 'js';
         const metaSuffix = cleanMeta ? ` ${cleanMeta}` : '';
 
-        const staticSection =
-          `**Static:**\n\n\`\`\`${langTag}${metaSuffix}\n${m.code}\`\`\``;
-        const dynamicSection =
-          `**Dynamic:**\n\n\`\`\`${langTag}${metaSuffix}\n${dynamicCode}\n\`\`\``;
+        const staticSection = `**Static:**\n\n\`\`\`${langTag}${metaSuffix}\n${m.code}\`\`\``;
+        const dynamicSection = `**Dynamic:**\n\n\`\`\`${langTag}${metaSuffix}\n${dynamicCode}\n\`\`\``;
 
         return {
           original: m.fullMatch,