mintlify · peppermintc · Jan 21, 2026
diff --git a/packages/mdx/.prettierignore b/packages/mdx/.prettierignore
@@ -0,0 +1 @@
+test/fixtures
diff --git a/packages/mdx/package.json b/packages/mdx/package.json
@@ -60,7 +60,8 @@
     "type": "tsc --noEmit",
     "lint": "eslint . --cache",
     "format": "prettier . --write",
-    "format:check": "prettier . --check"
+    "format:check": "prettier . --check",
+    "test": "vitest"
   },
   "author": "Mintlify, Inc.",
   "license": "MIT",
@@ -84,8 +85,12 @@
     "prettier-plugin-tailwindcss": "^0.6.8",
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
+    "rehype-stringify": "^10.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
     "rimraf": "^5.0.1",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.17"
   },
   "peerDependencies": {
     "@radix-ui/react-popover": "^19.2.1",

diff --git a/packages/mdx/test/fixtures/link-support.md b/packages/mdx/test/fixtures/link-support.md
@@ -0,0 +1,27 @@
+```js Link Testing icon="js" lines twoslash
+import { useEffect, useState } from 'react';
+
+// @link Component
+export function Component() {
+  //            ^?
+  return <div>{count}</div>;
+}
+
+// @link OtherFunction: #hola-there
+export function OtherFunction() {
+  //            ^?
+  return <div>{count}</div>;
+}
+
+// @link ExternalLink: https://google.com
+export function ExternalLink() {
+  //            ^?
+  const str =
+    "Don't worry, only hover targets with ExternalLink will be affected, not random strings";
+  return <div>{count}</div>;
+}
+```
+
+### Component
+
+Hello world from the `Component` section
diff --git a/packages/mdx/test/fixtures/link-support.out.html b/packages/mdx/test/fixtures/link-support.out.html
diff --git a/packages/mdx/test/fixtures/mock-hast-tree.ts b/packages/mdx/test/fixtures/mock-hast-tree.ts
@@ -0,0 +1,28 @@
+import type { Root } from 'hast';
+
+const MOCK_HAST_TREE: Root = {
+  type: 'root',
+  children: [
+    {
+      type: 'element',
+      tagName: 'pre',
+      properties: {},
+      children: [
+        {
+          type: 'element',
+          tagName: 'code',
+          properties: { className: ['language-js'] },
+          children: [
+            {
+              type: 'text',
+              value: "console.log('Hello World!');",
+            },
+          ],
+          data: { meta: 'index.js {1}' },
+        },
+      ],
+    },
+  ],
+};
+
+export { MOCK_HAST_TREE };
diff --git a/packages/mdx/test/fixtures/syntax-highlight.md b/packages/mdx/test/fixtures/syntax-highlight.md
@@ -0,0 +1,44 @@
+## JavaScript
+
+```js index.js {2}
+console.log('Hello, world!');
+function add(a, b) {
+  return a + b;
+}
+
+function subtract(a, b) {
+  return a - b;
+}
+```
+
+## Python
+
+```python index.py {1-2,4-5}
+def add(a, b):
+    return a + b
+
+def subtract(a, b):
+    return a - b
+```
+
+## Java
+
+```java {3}
+public class Main {
+    public static void main(String[] args) {
+        System.out.println("Hello, World!");
+    }
+}
+```
+
+## C#
+
+```csharp index.cs {1,3-4}
+public class Program
+{
+    public static void Main(string[] args)
+    {
+        Console.WriteLine("Hello, World!");
+    }
+}
+```
diff --git a/packages/mdx/test/fixtures/syntax-highlight.out.html b/packages/mdx/test/fixtures/syntax-highlight.out.html
@@ -0,0 +1,33 @@
+<h2>JavaScript</h2>
+<pre class="shiki shiki-themes github-light-default dark-plus" style="background-color:#ffffff;--shiki-dark-bg:#0B0C0E;color:#1f2328;--shiki-dark:#D4D4D4" language="javascript"><code language="javascript"><span class="line"><span style="color:#1F2328;--shiki-dark:#9CDCFE">console</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">.</span><span style="color:#8250DF;--shiki-dark:#DCDCAA">log</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">(</span><span style="color:#0A3069;--shiki-dark:#CE9178">'Hello, world!'</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">);</span></span>
+<span class="line"><span style="color:#CF222E;--shiki-dark:#569CD6">function</span><span style="color:#8250DF;--shiki-dark:#DCDCAA"> add</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">(</span><span style="color:#953800;--shiki-dark:#9CDCFE">a</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">, </span><span style="color:#953800;--shiki-dark:#9CDCFE">b</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">) {</span></span>
+<span class="line"><span style="color:#CF222E;--shiki-dark:#C586C0">  return</span><span style="color:#1F2328;--shiki-dark:#9CDCFE"> a</span><span style="color:#CF222E;--shiki-dark:#D4D4D4"> +</span><span style="color:#1F2328;--shiki-dark:#9CDCFE"> b</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">;</span></span>
+<span class="line"><span style="color:#1F2328;--shiki-dark:#D4D4D4">}</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#CF222E;--shiki-dark:#569CD6">function</span><span style="color:#8250DF;--shiki-dark:#DCDCAA"> subtract</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">(</span><span style="color:#953800;--shiki-dark:#9CDCFE">a</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">, </span><span style="color:#953800;--shiki-dark:#9CDCFE">b</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">) {</span></span>
+<span class="line"><span style="color:#CF222E;--shiki-dark:#C586C0">  return</span><span style="color:#1F2328;--shiki-dark:#9CDCFE"> a</span><span style="color:#CF222E;--shiki-dark:#D4D4D4"> -</span><span style="color:#1F2328;--shiki-dark:#9CDCFE"> b</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">;</span></span>
+<span class="line"><span style="color:#1F2328;--shiki-dark:#D4D4D4">}</span></span>
+<span class="line"></span></code></pre>
+<h2>Python</h2>
+<pre class="shiki shiki-themes github-light-default dark-plus" style="background-color:#ffffff;--shiki-dark-bg:#0B0C0E;color:#1f2328;--shiki-dark:#D4D4D4" language="python"><code language="python"><span class="line"><span style="color:#CF222E;--shiki-dark:#569CD6">def</span><span style="color:#8250DF;--shiki-dark:#DCDCAA"> add</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">(</span><span style="color:#1F2328;--shiki-dark:#9CDCFE">a</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">, </span><span style="color:#1F2328;--shiki-dark:#9CDCFE">b</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">):</span></span>
+<span class="line"><span style="color:#CF222E;--shiki-dark:#C586C0">    return</span><span style="color:#1F2328;--shiki-dark:#D4D4D4"> a </span><span style="color:#CF222E;--shiki-dark:#D4D4D4">+</span><span style="color:#1F2328;--shiki-dark:#D4D4D4"> b</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#CF222E;--shiki-dark:#569CD6">def</span><span style="color:#8250DF;--shiki-dark:#DCDCAA"> subtract</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">(</span><span style="color:#1F2328;--shiki-dark:#9CDCFE">a</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">, </span><span style="color:#1F2328;--shiki-dark:#9CDCFE">b</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">):</span></span>
+<span class="line"><span style="color:#CF222E;--shiki-dark:#C586C0">    return</span><span style="color:#1F2328;--shiki-dark:#D4D4D4"> a </span><span style="color:#CF222E;--shiki-dark:#D4D4D4">-</span><span style="color:#1F2328;--shiki-dark:#D4D4D4"> b</span></span>
+<span class="line"></span></code></pre>
+<h2>Java</h2>
+<pre class="shiki shiki-themes github-light-default dark-plus" style="background-color:#ffffff;--shiki-dark-bg:#0B0C0E;color:#1f2328;--shiki-dark:#D4D4D4" language="java"><code language="java"><span class="line"><span style="color:#CF222E;--shiki-dark:#569CD6">public</span><span style="color:#CF222E;--shiki-dark:#569CD6"> class</span><span style="color:#953800;--shiki-dark:#4EC9B0"> Main</span><span style="color:#1F2328;--shiki-dark:#D4D4D4"> {</span></span>
+<span class="line"><span style="color:#CF222E;--shiki-dark:#569CD6">    public</span><span style="color:#CF222E;--shiki-dark:#569CD6"> static</span><span style="color:#CF222E;--shiki-dark:#4EC9B0"> void</span><span style="color:#8250DF;--shiki-dark:#DCDCAA"> main</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">(</span><span style="color:#CF222E;--shiki-dark:#4EC9B0">String</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">[] </span><span style="color:#953800;--shiki-dark:#9CDCFE">args</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">) {</span></span>
+<span class="line"><span style="color:#1F2328;--shiki-dark:#9CDCFE">        System</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">.</span><span style="color:#1F2328;--shiki-dark:#9CDCFE">out</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">.</span><span style="color:#8250DF;--shiki-dark:#DCDCAA">println</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">(</span><span style="color:#0A3069;--shiki-dark:#CE9178">"Hello, World!"</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">);</span></span>
+<span class="line"><span style="color:#1F2328;--shiki-dark:#D4D4D4">    }</span></span>
+<span class="line"><span style="color:#1F2328;--shiki-dark:#D4D4D4">}</span></span>
+<span class="line"></span></code></pre>
+<h2>C#</h2>
+<pre class="shiki shiki-themes github-light-default dark-plus" style="background-color:#ffffff;--shiki-dark-bg:#0B0C0E;color:#1f2328;--shiki-dark:#D4D4D4" language="csharp"><code language="csharp"><span class="line"><span style="color:#CF222E;--shiki-dark:#569CD6">public</span><span style="color:#CF222E;--shiki-dark:#569CD6"> class</span><span style="color:#953800;--shiki-dark:#4EC9B0"> Program</span></span>
+<span class="line"><span style="color:#1F2328;--shiki-dark:#D4D4D4">{</span></span>
+<span class="line"><span style="color:#CF222E;--shiki-dark:#569CD6">    public</span><span style="color:#CF222E;--shiki-dark:#569CD6"> static</span><span style="color:#CF222E;--shiki-dark:#569CD6"> void</span><span style="color:#8250DF;--shiki-dark:#DCDCAA"> Main</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">(</span><span style="color:#CF222E;--shiki-dark:#569CD6">string</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">[] </span><span style="color:#953800;--shiki-dark:#9CDCFE">args</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">)</span></span>
+<span class="line"><span style="color:#1F2328;--shiki-dark:#D4D4D4">    {</span></span>
+<span class="line"><span style="color:#1F2328;--shiki-dark:#9CDCFE">        Console</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">.</span><span style="color:#8250DF;--shiki-dark:#DCDCAA">WriteLine</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">(</span><span style="color:#0A3069;--shiki-dark:#CE9178">"Hello, World!"</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">);</span></span>
+<span class="line"><span style="color:#1F2328;--shiki-dark:#D4D4D4">    }</span></span>
+<span class="line"><span style="color:#1F2328;--shiki-dark:#D4D4D4">}</span></span>
+<span class="line"></span></code></pre>
diff --git a/packages/mdx/test/fixtures/twoslash.md b/packages/mdx/test/fixtures/twoslash.md
@@ -0,0 +1,102 @@
+### Twoslash disabled without any additional configs or filenames
+
+```ts
+// This is a tooltip that will appear on the next line
+const myVariable = 'hello world';
+//    ^?
+
+// This is the second line
+// You can include [links](#anchor) in your hover content
+function myFunction() {
+  //     ^?
+  return myVariable;
+}
+```
+
+### Twoslash enabled without any additional configs or filenames
+
+```ts twoslash
+// This is a tooltip that will appear on the next line
+const myVariable = 'hello world';
+//    ^?
+
+// This is the second line
+// You can include [links](#anchor) in your hover content
+function myFunction() {
+  //     ^?
+  return myVariable;
+}
+```
+
+### Twoslash disabled with additional configs and filename
+
+```js something_with_external_packages.tsx icon="js" lines
+import { useEffect, useState } from 'react';
+
+export function Component() {
+  //            ^?
+  const [count, setCount] = useState(0);
+  //     ^?     ^?
+
+  useEffect(() => {
+    setTimeout(() => setCount(count + 1), 1000);
+    // ^?
+  }, [count]);
+
+  return <div>{count}</div>;
+}
+```
+
+### Twoslash enabled with additional configs
+
+```js something_with_external_packages.tsx icon="js" lines twoslash
+import { useEffect, useState } from 'react';
+
+export function Component() {
+  //            ^?
+  const [count, setCount] = useState(0);
+  //     ^?     ^?
+
+  useEffect(() => {
+    setTimeout(() => setCount(count + 1), 1000);
+    // ^?
+  }, [count]);
+
+  return <div>{count}</div>;
+}
+```
+
+### Twoslash cut before
+
+```ts twoslash
+type PermissionResult =
+  | {
+      behavior: 'allow';
+      updatedInput: ToolInput;
+      updatedPermissions?: PermissionUpdate[];
+    }
+  | {
+      behavior: 'deny';
+      message: string;
+      interrupt?: boolean;
+    };
+
+type ToolInput = string[];
+
+type PermissionUpdate = {
+  name: string;
+  permission: Array<number>;
+};
+
+// ---cut-before---
+
+type CanUseTool = (
+  toolName: string,
+  input: ToolInput,
+  options: {
+    signal: AbortSignal;
+    suggestions?: PermissionUpdate[];
+    //            ^?
+  }
+) => Promise<PermissionResult>;
+```