fix(cli): don't rewrite @/ imports inside MDX code blocks

packages/cli/cli/changes/unreleased/fix-at-prefix-imports-in-code-blocks.yml

@@ -0,0 +1,4 @@
+- summary: |
+    Fix `@/`-prefixed imports inside fenced code blocks and inline code being rewritten to relative
+    paths. Code samples are now rendered verbatim; only real MDX imports are resolved.
+  type: fix

packages/cli/docs-markdown-utils/src/__test__/transformAtPrefixImports.test.ts

@@ -196,6 +196,56 @@ Some content here.
 <Banner />`);
     });
 
+    it("should not transform imports inside fenced code blocks", () => {
+        const markdown = `---
+title: Tutorial
+---
+
+import { Banner } from '@/components/Banner'
+
+Update the imports:
+
+\`\`\`jsx showLineNumbers={false} title="content-fallback.tsx"
+import { Flex, ProgressCircle } from "@/components/ui/big-design";
+\`\`\`
+
+<Banner />`;
+        const absolutePathToMarkdownFile = AbsoluteFilePath.of("/path/to/fern/pages/guides/test.mdx");
+
+        const result = transformAtPrefixImports({
+            markdown,
+            absolutePathToFernFolder,
+            absolutePathToMarkdownFile
+        });
+
+        expect(result).toBe(`---
+title: Tutorial
+---
+
+import { Banner } from '../../components/Banner'
+
+Update the imports:
+
+\`\`\`jsx showLineNumbers={false} title="content-fallback.tsx"
+import { Flex, ProgressCircle } from "@/components/ui/big-design";
+\`\`\`
+
+<Banner />`);
+    });
+
+    it("should not transform imports inside inline code", () => {
+        const markdown = `Write \`import { Flex } from "@/components/ui/big-design"\` at the top.`;
+        const absolutePathToMarkdownFile = AbsoluteFilePath.of("/path/to/fern/pages/test.mdx");
+
+        const result = transformAtPrefixImports({
+            markdown,
+            absolutePathToFernFolder,
+            absolutePathToMarkdownFile
+        });
+
+        expect(result).toBe(markdown);
+    });
+
     it("should handle imports in sibling directories", () => {
         const markdown = `import { Banner } from '@/docs/components/Banner'`;
         const absolutePathToMarkdownFile = AbsoluteFilePath.of("/path/to/fern/pages/guides/test.mdx");

packages/cli/docs-markdown-utils/src/transformAtPrefixImports.ts

@@ -1,4 +1,58 @@
 import { AbsoluteFilePath, dirname, RelativeFilePath, relative } from "@fern-api/fs-utils";
+import grayMatter from "gray-matter";
+import { CONTINUE, visit } from "unist-util-visit";
+import { parseMarkdownToTree } from "./parseMarkdownToTree.js";
+
+/**
+ * Match import statements with '@/' prefix
+ * Handles various import formats:
+ * - import { X } from '@/path'
+ * - import X from '@/path'
+ * - import * as X from '@/path'
+ * - import '@/path'
+ */
+const IMPORT_REGEX = /(import\s+(?:(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+)?['"])@\/([^'"]+)(['"])/g;
+
+interface Range {
+    start: number;
+    end: number;
+}
+
+/**
+ * Byte ranges of fenced code blocks and inline code spans. Import statements inside them are
+ * documentation samples, not MDX imports, and must be rendered verbatim.
+ */
+function getCodeRanges(markdown: string): Range[] | undefined {
+    const { content } = grayMatter(markdown);
+    // `parseMarkdownToTree` strips frontmatter, so node offsets are relative to the body.
+    if (!markdown.endsWith(content)) {
+        return undefined;
+    }
+    const bodyOffset = markdown.length - content.length;
+
+    try {
+        const tree = parseMarkdownToTree(markdown);
+        const ranges: Range[] = [];
+        visit(
+            tree,
+            (node: unknown) => {
+                const type = (node as { type?: string }).type;
+                return type === "code" || type === "inlineCode";
+            },
+            (node) => {
+                const start = node.position?.start.offset;
+                const end = node.position?.end.offset;
+                if (start != null && end != null) {
+                    ranges.push({ start: start + bodyOffset, end: end + bodyOffset });
+                }
+                return CONTINUE;
+            }
+        );
+        return ranges;
+    } catch {
+        return undefined;
+    }
+}
 
 /**
  * Transforms import statements with '@/' prefix to relative paths.
@@ -25,28 +79,32 @@ export function transformAtPrefixImports({
     absolutePathToFernFolder: AbsoluteFilePath;
     absolutePathToMarkdownFile: AbsoluteFilePath;
 }): string {
-    // Match import statements with '@/' prefix
-    // Handles various import formats:
-    // - import { X } from '@/path'
-    // - import X from '@/path'
-    // - import * as X from '@/path'
-    // - import '@/path'
-    const importRegex = /(import\s+(?:(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+)?['"])@\/([^'"]+)(['"])/g;
+    if (!markdown.includes("@/")) {
+        return markdown;
+    }
 
     const mdxDir = dirname(absolutePathToMarkdownFile);
+    const codeRanges = getCodeRanges(markdown);
 
-    return markdown.replace(importRegex, (match, prefix, importPath, suffix) => {
-        // Compute the absolute path of the imported file (from fern folder root)
-        const absoluteImportPath = AbsoluteFilePath.of(`${absolutePathToFernFolder}/${importPath}`);
+    return markdown.replace(
+        IMPORT_REGEX,
+        (match, prefix: string, importPath: string, suffix: string, offset: number) => {
+            if (codeRanges?.some((range) => offset >= range.start && offset < range.end)) {
+                return match;
+            }
 
-        // Compute the relative path from the MDX file's directory to the imported file
-        let relativePath = relative(mdxDir, absoluteImportPath);
+            // Compute the absolute path of the imported file (from fern folder root)
+            const absoluteImportPath = AbsoluteFilePath.of(`${absolutePathToFernFolder}/${importPath}`);
 
-        // Ensure the path starts with './' or '../' for proper module resolution
-        if (!relativePath.startsWith(".") && !relativePath.startsWith("/")) {
-            relativePath = RelativeFilePath.of(`./${relativePath}`);
-        }
+            // Compute the relative path from the MDX file's directory to the imported file
+            let relativePath = relative(mdxDir, absoluteImportPath);
+
+            // Ensure the path starts with './' or '../' for proper module resolution
+            if (!relativePath.startsWith(".") && !relativePath.startsWith("/")) {
+                relativePath = RelativeFilePath.of(`./${relativePath}`);
+            }
 
-        return `${prefix}${relativePath}${suffix}`;
-    });
+            return `${prefix}${relativePath}${suffix}`;
+        }
+    );
 }