feat: enhance markdown URL handling for README files

Author: uniyalabhishek

src/plugins/llms/markdown.test.ts

@@ -34,6 +34,9 @@ test('toMarkdownUrl: converts internal doc-like paths and preserves query/hash',
   expect(toMarkdownUrl('/build/rofl/index.mdx?x=1#sec')).toBe(
     '/build/rofl.md?x=1#sec',
   );
+  expect(toMarkdownUrl('/build/rofl/README.mdx?x=1#sec')).toBe(
+    '/build/rofl.md?x=1#sec',
+  );
 });
 
 test('toMarkdownUrl: converts same-host absolute URLs when siteBase is provided', () => {
@@ -140,6 +143,8 @@ test('renderMarkdownFromCapturedTree: rewrites .mdx and index links to permalink
       link('/build/rofl/quickstart.mdx#prereq', 'Quickstart'),
       t(' '),
       link('/build/rofl/index.mdx#top', 'ROFL'),
+      t(' '),
+      link('/build/rofl/README.mdx#top', 'ROFL README'),
     ],
   });
   const docsByPermalink = new Map([
@@ -152,6 +157,7 @@ test('renderMarkdownFromCapturedTree: rewrites .mdx and index links to permalink
 
   expect(output).toContain('](/build/rofl/quickstart#prereq)');
   expect(output).toContain('](/build/rofl/#top)');
+  expect(output).not.toContain('/build/rofl/README.mdx');
 });
 
 test('renderMarkdownFromCapturedTree: linkTarget md rewrites internal links to .md mirrors', () => {
@@ -162,6 +168,8 @@ test('renderMarkdownFromCapturedTree: linkTarget md rewrites internal links to .
       t(' '),
       link('/build/rofl/index.mdx#top', 'ROFL'),
       t(' '),
+      link('/build/rofl/README.mdx#top', 'ROFL README'),
+      t(' '),
       link('../features/?x=1#sec', 'Features'),
     ],
   });
@@ -180,6 +188,7 @@ test('renderMarkdownFromCapturedTree: linkTarget md rewrites internal links to .
 
   expect(output).toContain('](/build/rofl/quickstart.md#prereq)');
   expect(output).toContain('](/build/rofl.md#top)');
+  expect(output).not.toContain('/build/rofl/README.mdx');
   expect(output).toContain('](/build/rofl/features.md?x=1#sec)');
 });
 

src/plugins/llms/markdown.ts

@@ -78,6 +78,12 @@ function toMarkdownPathname(pathname: string): string {
     return parent === '/' ? '/index.md' : `${parent}.md`;
   }
 
+  // Handle /foo/README -> /foo.md (common Docusaurus pattern)
+  if (/\/readme$/i.test(withoutExtension)) {
+    const parent = withoutExtension.slice(0, -'/README'.length) || '/';
+    return parent === '/' ? '/index.md' : `${parent}.md`;
+  }
+
   return `${withoutExtension}.md`;
 }
 
@@ -383,6 +389,13 @@ function findCanonicalPermalink(
       const indexed = checkPermalink(parent) ?? checkPermalink(parent + '/');
       if (indexed) return indexed;
     }
+
+    // Handle /foo/README.md -> /foo (common Docusaurus pattern)
+    if (/\/readme$/i.test(withoutExtension)) {
+      const parent = withoutExtension.slice(0, -'/README'.length) || '/';
+      const readmed = checkPermalink(parent) ?? checkPermalink(parent + '/');
+      if (readmed) return readmed;
+    }
   }
 
   return null;

src/remark/llms-capture.ts

@@ -2,7 +2,6 @@ import * as fs from 'fs';
 import * as path from 'path';
 
 import type {Transformer} from 'unified';
-import type {VFile} from 'vfile';
 
 import {
   captureDirForSite,
@@ -16,27 +15,6 @@ interface Options {
 
 let hasLoggedCaptureDir = false;
 
-function resolveSiteDir(vfile: VFile, options?: Options): string {
-  // Priority 1: Explicit option
-  if (typeof options?.siteDir === 'string' && options.siteDir.trim()) {
-    return options.siteDir;
-  }
-
-  // Priority 2: VFile data
-  const data = vfile?.data as Record<string, unknown> | undefined;
-  if (data && typeof data.siteDir === 'string' && data.siteDir.trim()) {
-    return data.siteDir;
-  }
-
-  // Priority 3: VFile cwd
-  if (typeof vfile?.cwd === 'string' && vfile.cwd.trim()) {
-    return vfile.cwd;
-  }
-
-  // Fallback: process cwd
-  return process.cwd();
-}
-
 function cleanupTempFile(tempFile: string): void {
   try {
     fs.rmSync(tempFile, {force: true});
@@ -67,12 +45,16 @@ function atomicWriteJson(filename: string, payload: unknown): void {
 }
 
 export default function remarkLlmsCapture(options: Options = {}): Transformer {
+  const siteDir =
+    typeof options.siteDir === 'string' && options.siteDir.trim()
+      ? options.siteDir
+      : process.cwd();
+
   return (tree, vfile) => {
     const sourcePath = vfile.history?.[0] ?? vfile.path;
     if (!sourcePath) return;
 
     try {
-      const siteDir = resolveSiteDir(vfile, options);
       const resolvedSource = path.isAbsolute(sourcePath)
         ? sourcePath
         : path.join(siteDir, sourcePath);