[ { "path": ".eslintrc.cjs", "content": "module.exports = {\n extends: ['@mintlify/eslint-config-typescript'],\n parserOptions: {\n tsconfigRootDir: __dirname,\n project: './tsconfig.json',\n },\n ignorePatterns: ['.eslintrc.cjs', 'dist'],\n overrides: [\n {\n files: ['*.js'],\n extends: ['plugin:@typescript-eslint/disable-type-checked'],\n },\n ],\n};\n" }, { "path": ".gitignore", "content": "# NPM\nnode_modules/\n.eslintcache\nyarn-error.log\n\n# Output\ndist/\n\n# Misc\n.DS_Store\n\n# TypeScript\n*.tsbuildinfo\n\n# yarn\n.pnp.*\n.yarn/*\n!.yarn/patches\n!.yarn/plugins\n!.yarn/releases\n!.yarn/sdks\n!.yarn/versions" }, { "path": ".prettierignore", "content": "/dist\n/node_modules\n\n.next" }, { "path": ".prettierrc", "content": "\"@mintlify/prettier-config/config.js\"\n" }, { "path": ".yarnrc.yml", "content": "nodeLinker: node-modules" }, { "path": "examples/app-router/.eslintrc.json", "content": "{\n \"extends\": \"next/core-web-vitals\"\n}\n" }, { "path": "examples/app-router/.gitignore", "content": "# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.\n\n# dependencies\n/node_modules\n/.pnp\n.pnp.js\n.yarn/install-state.gz\n\n# testing\n/coverage\n\n# next.js\n/.next/\n/out/\n\n# production\n/build\n\n# misc\n.DS_Store\n*.pem\n\n# debug\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\n\n# local env files\n.env*.local\n\n# vercel\n.vercel\n\n# typescript\n*.tsbuildinfo\nnext-env.d.ts\n" }, { "path": "examples/app-router/app/globals.css", "content": "@tailwind base;\n@tailwind components;\n@tailwind utilities;\n\n@layer base {\n :root {\n --primary-light: 85 215 153;\n }\n}\n\n/* modified from https://github.com/shikijs/shiki/blob/main/packages/twoslash/style-rich.css */\n/* ===== Basic ===== */\n:root {\n --twoslash-border-color: #8888;\n --twoslash-underline-color: currentColor;\n --twoslash-highlighted-border: #c37d0d50;\n --twoslash-highlighted-bg: #c37d0d20;\n --twoslash-popup-bg: #f8f8f8;\n --twoslash-popup-color: inherit;\n --twoslash-popup-shadow: rgba(0, 0, 0, 0.08) 0px 1px 4px;\n --twoslash-docs-color: #888;\n --twoslash-docs-font: sans-serif;\n --twoslash-code-font: inherit;\n --twoslash-code-font-size: 1em;\n --twoslash-matched-color: inherit;\n --twoslash-unmatched-color: #888;\n --twoslash-cursor-color: #8888;\n --twoslash-error-color: #d45656;\n --twoslash-error-bg: #d4565620;\n --twoslash-warn-color: #c37d0d;\n --twoslash-warn-bg: #c37d0d20;\n --twoslash-tag-color: #3772cf;\n --twoslash-tag-bg: #3772cf20;\n --twoslash-tag-warn-color: var(--twoslash-warn-color);\n --twoslash-tag-warn-bg: var(--twoslash-warn-bg);\n --twoslash-tag-annotate-color: #1ba673;\n --twoslash-tag-annotate-bg: #1ba67320;\n --twoslash-text-size: 0.8rem;\n --twoslash-docs-tag-style: italic;\n}\n\n/* Respect people's wishes to not have animations */\n@media (prefers-reduced-motion: reduce) {\n .twoslash * {\n transition: none !important;\n }\n}\n\n/* ===== Hover Info ===== */\n.twoslash:hover .twoslash-hover {\n border-color: var(--twoslash-underline-color);\n}\n\n.twoslash .twoslash-hover {\n border-bottom: 1px dotted transparent;\n transition-timing-function: ease;\n transition: border-color 0.3s;\n position: relative;\n}\n\n\n/* ===== Popup Override ===== */\n.mint-twoslash-popover {\n background: var(--twoslash-popup-bg);\n color: var(--twoslash-popup-color);\n border: 1px solid var(--twoslash-border-color);\n border-radius: 4px;\n pointer-events: auto;\n text-align: left;\n box-shadow: var(--twoslash-popup-shadow);\n display: inline-flex;\n flex-direction: column;\n}\n\n.mint-twoslash-popover-pre {\n display: flex;\n font-size: var(--twoslash-text-size);\n font-family: var(--twoslash-code-font);\n}\n\n.mint-twoslash-popover:hover {\n user-select: auto;\n}\n\n.twoslash .twoslash-popup-arrow {\n display: none;\n}\n\n.twoslash-popup-code,\n.twoslash-popup-error,\n.twoslash-popup-docs {\n padding: 6px 8px !important;\n}\n\n.mint-twoslash-popover .twoslash-popup-docs {\n color: var(--twoslash-docs-color);\n font-family: var(--twoslash-docs-font);\n font-size: var(--twoslash-text-size);\n max-width: unset;\n}\n\n.mint-twoslash-popover .twoslash-popup-error {\n color: var(--twoslash-error-color);\n background-color: var(--twoslash-error-bg);\n font-family: var(--twoslash-docs-font);\n font-size: var(--twoslash-text-size);\n}\n\n.mint-twoslash-popover .twoslash-popup-docs-tags {\n display: flex;\n flex-direction: column;\n font-family: var(--twoslash-docs-font);\n}\n\n.mint-twoslash-popover .twoslash-popup-docs-tag-name {\n margin-right: 0.5em;\n font-style: var(--twoslash-docs-tag-style);\n}\n\n.mint-twoslash-popover .twoslash-popup-docs-tag-name {\n font-family: var(--twoslash-code-font);\n}\n\n/* ===== Query Line ===== */\n.mint-twoslash-popover .twoslash-query-line .twoslash-popup-container {\n position: relative;\n margin-bottom: 1.4em;\n transform: translateY(0.6em);\n}\n\n/* ===== Error Line ===== */\n.mint-twoslash-popover .twoslash-error-line {\n position: relative;\n background-color: var(--twoslash-error-bg);\n border-left: 3px solid var(--twoslash-error-color);\n color: var(--twoslash-error-color);\n padding: 6px 12px;\n margin: 0.2em 0;\n min-width: 100%;\n width: max-content;\n}\n\n.mint-twoslash-popover .twoslash-error-line.twoslash-error-level-warning {\n background-color: var(--twoslash-warn-bg);\n border-left: 3px solid var(--twoslash-warn-color);\n color: var(--twoslash-warn-color);\n}\n\n.mint-twoslash-popover .twoslash-error {\n background: url(\"data:image/svg+xml,%3Csvg%20xmlns%3D'http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg'%20viewBox%3D'0%200%206%203'%20enable-background%3D'new%200%200%206%203'%20height%3D'3'%20width%3D'6'%3E%3Cg%20fill%3D'%23c94824'%3E%3Cpolygon%20points%3D'5.5%2C0%202.5%2C3%201.1%2C3%204.1%2C0'%2F%3E%3Cpolygon%20points%3D'4%2C0%206%2C2%206%2C0.6%205.4%2C0'%2F%3E%3Cpolygon%20points%3D'0%2C2%201%2C3%202.4%2C3%200%2C0.6'%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E\") repeat-x bottom left;\n padding-bottom: 2px;\n}\n\n.mint-twoslash-popover .twoslash-error.twoslash-error-level-warning {\n background: url(\"data:image/svg+xml,%3Csvg%20xmlns%3D'http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg'%20viewBox%3D'0%200%206%203'%20enable-background%3D'new%200%200%206%203'%20height%3D'3'%20width%3D'6'%3E%3Cg%20fill%3D'%23c37d0d'%3E%3Cpolygon%20points%3D'5.5%2C0%202.5%2C3%201.1%2C3%204.1%2C0'%2F%3E%3Cpolygon%20points%3D'4%2C0%206%2C2%206%2C0.6%205.4%2C0'%2F%3E%3Cpolygon%20points%3D'0%2C2%201%2C3%202.4%2C3%200%2C0.6'%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E\") repeat-x bottom left;\n padding-bottom: 2px;\n}\n\n/* ===== Completeions ===== */\n.mint-twoslash-popover .twoslash-completion-cursor {\n position: relative;\n}\n\n.mint-twoslash-popover .twoslash-completion-cursor .twoslash-completion-list {\n user-select: none;\n position: absolute;\n top: 0;\n left: 0;\n transform: translate(0, 1.2em);\n margin: 3px 0 0 -1px;\n display: inline-block;\n z-index: 8;\n box-shadow: var(--twoslash-popup-shadow);\n background: var(--twoslash-popup-bg);\n border: 1px solid var(--twoslash-border-color);\n}\n\n.twoslash-completion-list {\n width: 240px;\n font-size: var(--twoslash-text-size);\n padding: 4px;\n display: flex;\n flex-direction: column;\n gap: 4px;\n}\n\n.twoslash-completion-list:hover {\n user-select: auto;\n}\n\n.twoslash-completion-list::before {\n background-color: var(--twoslash-cursor-color);\n width: 2px;\n position: absolute;\n top: -1.6em;\n height: 1.4em;\n left: -1px;\n content: ' ';\n}\n\n.twoslash-completion-list li {\n overflow: hidden;\n display: flex;\n align-items: center;\n gap: 0.25em;\n line-height: 1em;\n}\n\n.twoslash-completion-list li span.twoslash-completions-unmatched {\n color: var(--twoslash-unmatched-color);\n}\n\n.twoslash-completion-list .deprecated {\n text-decoration: line-through;\n opacity: 0.5;\n}\n\n.twoslash-completion-list li span.twoslash-completions-matched {\n color: var(--twoslash-matched-color);\n}\n\n/* Highlights */\n.twoslash-highlighted {\n background-color: var(--twoslash-highlighted-bg);\n border: 1px solid var(--twoslash-highlighted-border);\n padding: 1px 2px;\n margin: -1px -3px;\n border-radius: 4px;\n}\n\n/* Icons */\n.twoslash-completion-list .twoslash-completions-icon {\n color: var(--twoslash-unmatched-color);\n width: 1em;\n flex: none;\n}\n\n/* Custom Tags */\n.mint-twoslash-popover .twoslash-tag-line {\n position: relative;\n background-color: var(--twoslash-tag-bg);\n border-left: 3px solid var(--twoslash-tag-color);\n color: var(--twoslash-tag-color);\n padding: 6px 10px;\n margin: 0.2em 0;\n display: flex;\n align-items: center;\n gap: 0.3em;\n min-width: 100%;\n width: max-content;\n}\n\n.mint-twoslash-popover .twoslash-tag-line .twoslash-tag-icon {\n width: 1.1em;\n color: inherit;\n}\n\n.mint-twoslash-popover .twoslash-tag-line.twoslash-tag-error-line {\n background-color: var(--twoslash-error-bg);\n border-left: 3px solid var(--twoslash-error-color);\n color: var(--twoslash-error-color);\n}\n\n.mint-twoslash-popover .twoslash-tag-line.twoslash-tag-warn-line {\n background-color: var(--twoslash-tag-warn-bg);\n border-left: 3px solid var(--twoslash-tag-warn-color);\n color: var(--twoslash-tag-warn-color);\n}\n\n.mint-twoslash-popover .twoslash-tag-line.twoslash-tag-annotate-line {\n background-color: var(--twoslash-tag-annotate-bg);\n border-left: 3px solid var(--twoslash-tag-annotate-color);\n color: var(--twoslash-tag-annotate-color);\n}\n" }, { "path": "examples/app-router/app/layout.tsx", "content": "import type { Metadata } from 'next';\n\nimport '@/app/globals.css';\n\nexport const metadata: Metadata = {\n title: 'Create Next App',\n description: 'Generated by create next app',\n};\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n return (\n \n {children}\n \n );\n}\n" }, { "path": "examples/app-router/app/loading.tsx", "content": "export default function Loading() {\n return <>Loading...;\n}\n" }, { "path": "examples/app-router/app/page.tsx", "content": "import { MDXRemote } from '@mintlify/mdx/rsc';\nimport { promises as fs } from 'fs';\n\nexport default async function Home() {\n const data = await fs.readFile(process.cwd() + '/examples/highlight-example.mdx', 'utf8');\n\n return (\n
\n \n
\n );\n}\n" }, { "path": "examples/app-router/examples/highlight-example.mdx", "content": "---\ntitle: 'Line Highlighting'\ndescription: 'Highlights specific lines and/or line ranges'\n---\n\nThis MDX file demonstrates syntax highlighting for various programming languages.\n\n## JavaScript\n\n```js index.js {2}\nconsole.log('Hello, world!');\nfunction add(a, b) {\n return a + b;\n}\n\nfunction subtract(a, b) {\n return a - b;\n}\n```\n\n## Python\n\n```python index.py {1-2,4-5}\ndef add(a, b):\n return a + b\n\ndef subtract(a, b):\n return a - b\n```\n\n## Java\n\n```java {3}\npublic class Main {\n public static void main(String[] args) {\n System.out.println(\"Hello, World!\");\n }\n}\n```\n\n## C#\n\n```csharp index.cs {1,3-4}\npublic class Program\n{\n public static void Main(string[] args)\n {\n Console.WriteLine(\"Hello, World!\");\n }\n}\n```\n\n## Testing Twoslash\n\n### Twoslash disabled without any additional configs or filenames\n\n```ts\n// This is a tooltip that will appear on the next line\nconst myVariable = 'hello world';\n// ^?\n\n// This is the second line\n// You can include [links](#anchor) in your hover content\nfunction myFunction() {\n // ^?\n return myVariable;\n}\n```\n\n### Twoslash enabled without any additional configs or filenames\n\n```ts twoslash\n// This is a tooltip that will appear on the next line\nconst myVariable = 'hello world';\n// ^?\n\n// This is the second line\n// You can include [links](#anchor) in your hover content\nfunction myFunction() {\n // ^?\n return myVariable;\n}\n```\n\n### Twoslash disabled with additional configs and filename\n\n```js something_with_external_packages.tsx icon=\"js\" lines\nimport { useEffect, useState } from 'react';\n\nexport function Component() {\n // ^?\n const [count, setCount] = useState(0);\n // ^? ^?\n\n useEffect(() => {\n setTimeout(() => setCount(count + 1), 1000);\n // ^?\n }, [count]);\n\n return
{count}
;\n}\n```\n\n### Twoslash enabled with additional configs\n\n```js something_with_external_packages.tsx icon=\"js\" lines twoslash\nimport { useEffect, useState } from 'react';\n\nexport function Component() {\n // ^?\n const [count, setCount] = useState(0);\n // ^? ^?\n\n useEffect(() => {\n setTimeout(() => setCount(count + 1), 1000);\n // ^?\n }, [count]);\n\n return
{count}
;\n}\n```\n\n## Link support\n\n```js Link Testing icon=\"js\" lines twoslash\nimport { useEffect, useState } from 'react';\n\n// @link Component\nexport function Component() {\n // ^?\n return
{count}
;\n}\n\n// @link OtherFunction: #hola-there\nexport function OtherFunction() {\n // ^?\n return
{count}
;\n}\n\n// @link ExternalLink: https://google.com\nexport function ExternalLink() {\n // ^?\n const str =\n \"Don't worry, only hover targets with ExternalLink will be affected, not random strings\";\n return
{count}
;\n}\n```\n\n```ts twoslash\ntype PermissionResult =\n | {\n behavior: 'allow';\n updatedInput: ToolInput;\n updatedPermissions?: PermissionUpdate[];\n }\n | {\n behavior: 'deny';\n message: string;\n interrupt?: boolean;\n };\n\ntype ToolInput = string[];\n\ntype PermissionUpdate = {\n name: string;\n permission: Array;\n};\n\n// ---cut-before---\n\ntype CanUseTool = (\n toolName: string,\n input: ToolInput,\n options: {\n signal: AbortSignal;\n suggestions?: PermissionUpdate[];\n // ^?\n }\n) => Promise;\n```\n\n### Component\n\nHello world from the `Component` section\n" }, { "path": "examples/app-router/next.config.js", "content": "const path = require('path');\n\n/** @type {import('next').NextConfig} */\nconst nextConfig = {\n serverExternalPackages: ['@shikijs/twoslash'],\n outputFileTracingIncludes: {\n '/render': [\n path.relative(\n process.cwd(),\n path.resolve(require.resolve('typescript/package.json'), '..', 'lib', 'lib.*.d.ts')\n ),\n './node_modules/@types/node/**',\n ],\n },\n};\n\nmodule.exports = nextConfig;\n" }, { "path": "examples/app-router/package.json", "content": "{\n \"name\": \"app-router\",\n \"version\": \"0.1.0\",\n \"private\": true,\n \"scripts\": {\n \"dev\": \"next dev\",\n \"build\": \"next build\",\n \"start\": \"next start\",\n \"lint\": \"next lint\"\n },\n \"dependencies\": {\n \"@mintlify/mdx\": \"workspace:^\",\n \"@radix-ui/react-popover\": \"^1.1.15\",\n \"next\": \"16.0.9\",\n \"react\": \"^19.2.1\",\n \"react-dom\": \"^19.2.1\"\n },\n \"devDependencies\": {\n \"@tailwindcss/typography\": \"^0.5.10\",\n \"@types/node\": \"^20\",\n \"@types/react\": \"^19.2.1\",\n \"@types/react-dom\": \"^19.2.1\",\n \"autoprefixer\": \"^10.0.1\",\n \"eslint\": \"^8\",\n \"eslint-config-next\": \"16.0.7\",\n \"postcss\": \"^8\",\n \"tailwindcss\": \"^3.3.0\",\n \"typescript\": \"^5\"\n }\n}\n" }, { "path": "examples/app-router/postcss.config.js", "content": "module.exports = {\n plugins: {\n tailwindcss: {},\n autoprefixer: {},\n },\n};\n" }, { "path": "examples/app-router/readme.md", "content": "## Getting Started\n\nThis is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) and it uses the [App Router](https://nextjs.org/docs/app). It also uses [Tailwind CSS](https://tailwindcss.com/) for styling.\n\nYou can check out the code at [https://github.com/mintlify/mdx/blob/main/examples/app-router/app/page.tsx](https://github.com/mintlify/mdx/blob/main/examples/app-router/app/page.tsx) to understand how to parse your markdown using [@mintlify/mdx](https://www.npmjs.com/package/@mintlify/mdx).\n\n## Demo\n\nYou can check out the demo of [this page](https://github.com/mintlify/mdx/blob/main/examples/app-router/app/page.tsx) at [https://mdx-app-router.vercel.app](https://mdx-app-router.vercel.app).\n\n## How to use\n\n1. Use the `MDXRemote` component directly inside your async React Server Component.\n\n ```tsx\n import { MDXRemote } from '@mintlify/mdx/rsc';\n\n export default async function Home() {\n const source: `---\n title: Title\n ---\n\n ## Markdown H2\n `;\n\n return (\n
\n \n
\n );\n }\n ```\n" }, { "path": "examples/app-router/tailwind.config.ts", "content": "import type { Config } from 'tailwindcss';\n\nconst config: Config = {\n content: [\n './pages/**/*.{js,ts,jsx,tsx,mdx}',\n './components/**/*.{js,ts,jsx,tsx,mdx}',\n './app/**/*.{js,ts,jsx,tsx,mdx}',\n ],\n theme: {\n extend: {\n backgroundImage: {\n 'gradient-radial': 'radial-gradient(var(--tw-gradient-stops))',\n 'gradient-conic': 'conic-gradient(from 180deg at 50% 50%, var(--tw-gradient-stops))',\n },\n },\n },\n plugins: [require('@tailwindcss/typography')],\n};\nexport default config;\n" }, { "path": "examples/app-router/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"target\": \"es5\",\n \"lib\": [\"dom\", \"dom.iterable\", \"esnext\"],\n \"allowJs\": true,\n \"skipLibCheck\": true,\n \"strict\": true,\n \"noEmit\": true,\n \"esModuleInterop\": true,\n \"module\": \"esnext\",\n \"moduleResolution\": \"bundler\",\n \"resolveJsonModule\": true,\n \"isolatedModules\": true,\n \"jsx\": \"preserve\",\n \"incremental\": true,\n \"plugins\": [\n {\n \"name\": \"next\"\n }\n ],\n \"paths\": {\n \"@/*\": [\"./*\"]\n }\n },\n \"include\": [\"next-env.d.ts\", \"**/*.ts\", \"**/*.tsx\", \".next/types/**/*.ts\"],\n \"exclude\": [\"node_modules\"]\n}\n" }, { "path": "examples/pages-router/.eslintrc.json", "content": "{\n \"extends\": \"next/core-web-vitals\"\n}\n" }, { "path": "examples/pages-router/.gitignore", "content": "# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.\n\n# dependencies\n/node_modules\n/.pnp\n.pnp.js\n.yarn/install-state.gz\n\n# testing\n/coverage\n\n# next.js\n/.next/\n/out/\n\n# production\n/build\n\n# misc\n.DS_Store\n*.pem\n\n# debug\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\n\n# local env files\n.env*.local\n\n# vercel\n.vercel\n\n# typescript\n*.tsbuildinfo\nnext-env.d.ts\n" }, { "path": "examples/pages-router/eslint.config.mjs", "content": "import { defineConfig } from \"eslint/config\";\nimport nextCoreWebVitals from \"eslint-config-next/core-web-vitals\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\nexport default defineConfig([{\n extends: [...nextCoreWebVitals],\n}]);" }, { "path": "examples/pages-router/examples/highlight-example.mdx", "content": "---\ntitle: 'Line Highlighting'\ndescription: 'Highlights specific lines and/or line ranges'\n---\n\nThis MDX file demonstrates syntax highlighting for various programming languages.\n\n## JavaScript\n\n```js index.js {2}\nconsole.log('Hello, world!');\nfunction add(a, b) {\n return a + b;\n}\n\nfunction subtract(a, b) {\n return a - b;\n}\n```\n\n## Python\n\n```python index.py {1-2,4-5}\ndef add(a, b):\n return a + b\n\ndef subtract(a, b):\n return a - b\n```\n\n## Java\n\n```java {3}\npublic class Main {\n public static void main(String[] args) {\n System.out.println(\"Hello, World!\");\n }\n}\n```\n\n## C#\n\n```csharp index.cs {1,3-4}\npublic class Program\n{\n public static void Main(string[] args)\n {\n Console.WriteLine(\"Hello, World!\");\n }\n}\n```\n\n## Testing Twoslash\n\n### Twoslash disabled without any additional configs or filenames\n\n```ts\n// This is a tooltip that will appear on the next line\nconst myVariable = 'hello world';\n// ^?\n\n// This is the second line\n// You can include [links](#anchor) in your hover content\nfunction myFunction() {\n // ^?\n return myVariable;\n}\n```\n\n### Twoslash enabled without any additional configs or filenames\n\n```ts twoslash\n// This is a tooltip that will appear on the next line\nconst myVariable = 'hello world';\n// ^?\n\n// This is the second line\n// You can include [links](#anchor) in your hover content\nfunction myFunction() {\n // ^?\n return myVariable;\n}\n```\n\n### Twoslash disabled with additional configs and filename\n\n```js something_with_external_packages.tsx icon=\"js\" lines\nimport { useEffect, useState } from 'react';\n\nexport function Component() {\n // ^?\n const [count, setCount] = useState(0);\n // ^? ^?\n\n useEffect(() => {\n setTimeout(() => setCount(count + 1), 1000);\n // ^?\n }, [count]);\n\n return
{count}
;\n}\n```\n\n### Twoslash enabled with additional configs\n\n```js something_with_external_packages.tsx icon=\"js\" lines twoslash\nimport { useEffect, useState } from 'react';\n\nexport function Component() {\n // ^?\n const [count, setCount] = useState(0);\n // ^? ^?\n\n useEffect(() => {\n setTimeout(() => setCount(count + 1), 1000);\n // ^?\n }, [count]);\n\n return
{count}
;\n}\n```\n\n## Link support\n\n```js Link Testing icon=\"js\" lines twoslash\nimport { useEffect, useState } from 'react';\n\n// @link Component\nexport function Component() {\n // ^?\n return
{count}
;\n}\n\n// @link OtherFunction: #hola-there\nexport function OtherFunction() {\n // ^?\n return
{count}
;\n}\n\n// @link ExternalLink: https://google.com\nexport function ExternalLink() {\n // ^?\n const str =\n \"Don't worry, only hover targets with ExternalLink will be affected, not random strings\";\n return
{count}
;\n}\n```\n\n```ts twoslash\ntype PermissionResult =\n | {\n behavior: 'allow';\n updatedInput: ToolInput;\n updatedPermissions?: PermissionUpdate[];\n }\n | {\n behavior: 'deny';\n message: string;\n interrupt?: boolean;\n };\n\ntype ToolInput = string[];\n\ntype PermissionUpdate = {\n name: string;\n permission: Array;\n};\n\n// ---cut-before---\n\ntype CanUseTool = (\n toolName: string,\n input: ToolInput,\n options: {\n signal: AbortSignal;\n suggestions?: PermissionUpdate[];\n // ^?\n }\n) => Promise;\n```\n\n### Component\n\nHello world from the `Component` section\n" }, { "path": "examples/pages-router/next.config.js", "content": "const path = require('path');\n\n/** @type {import('next').NextConfig} */\nconst nextConfig = {\n serverExternalPackages: ['@shikijs/twoslash'],\n outputFileTracingIncludes: {\n '/render': [\n path.relative(\n process.cwd(),\n path.resolve(require.resolve('typescript/package.json'), '..', 'lib', 'lib.*.d.ts')\n ),\n './node_modules/@types/node/**',\n ],\n },\n};\n\nmodule.exports = nextConfig;\n" }, { "path": "examples/pages-router/package.json", "content": "{\n \"name\": \"pages-router\",\n \"version\": \"0.1.0\",\n \"private\": true,\n \"scripts\": {\n \"dev\": \"next dev\",\n \"build\": \"next build\",\n \"start\": \"next start\",\n \"lint\": \"eslint .\"\n },\n \"dependencies\": {\n \"@mintlify/mdx\": \"workspace:^\",\n \"@radix-ui/react-popover\": \"^1.1.15\",\n \"next\": \"16.0.9\",\n \"react\": \"^19.2.1\",\n \"react-dom\": \"^19.2.1\"\n },\n \"devDependencies\": {\n \"@tailwindcss/typography\": \"^0.5.10\",\n \"@types/node\": \"^20\",\n \"@types/react\": \"^19.2.1\",\n \"@types/react-dom\": \"^19.2.1\",\n \"autoprefixer\": \"^10.0.1\",\n \"eslint\": \"^9\",\n \"eslint-config-next\": \"16.0.7\",\n \"postcss\": \"^8\",\n \"tailwindcss\": \"^3.3.0\",\n \"typescript\": \"^5\"\n },\n \"resolutions\": {\n \"@types/react\": \"19.2.7\",\n \"@types/react-dom\": \"19.2.3\"\n }\n}\n" }, { "path": "examples/pages-router/pages/_app.tsx", "content": "import { AppProps } from 'next/app';\n\nimport '@/styles/globals.css';\n\nexport default function App({ Component, pageProps }: AppProps) {\n return ;\n}\n" }, { "path": "examples/pages-router/pages/_document.tsx", "content": "import { Html, Head, Main, NextScript } from 'next/document';\n\nexport default function Document() {\n return (\n \n \n \n
\n \n \n \n );\n}\n" }, { "path": "examples/pages-router/pages/index.tsx", "content": "import { MDXClient } from '@mintlify/mdx/client';\nimport { serialize } from '@mintlify/mdx/server';\nimport type { SerializeResult } from '@mintlify/mdx/types';\nimport { promises as fs } from 'fs';\nimport type { GetStaticProps, InferGetStaticPropsType } from 'next';\n\nexport const getStaticProps = (async () => {\n const data = await fs.readFile(process.cwd() + '/examples/highlight-example.mdx', 'utf8');\n\n const mdxSource = await serialize({ source: data });\n if ('error' in mdxSource) {\n throw mdxSource.error;\n }\n\n return { props: { mdxSource } };\n}) satisfies GetStaticProps<{\n mdxSource: Omit;\n}>;\n\nexport default function Home({ mdxSource }: InferGetStaticPropsType) {\n return (\n
\n

{String(mdxSource.frontmatter.title)}

\n\n \n
\n );\n}\n" }, { "path": "examples/pages-router/postcss.config.js", "content": "module.exports = {\n plugins: {\n tailwindcss: {},\n autoprefixer: {},\n },\n};\n" }, { "path": "examples/pages-router/readme.md", "content": "## Getting Started\n\nThis is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) and it uses the [Pages Router](https://nextjs.org/docs/pages). It also uses [Tailwind CSS](https://tailwindcss.com/) for styling.\n\nYou can check out the code at [https://github.com/mintlify/mdx/blob/main/examples/pages-router/pages/index.tsx](https://github.com/mintlify/mdx/blob/main/examples/pages-router/pages/index.tsx) to understand how to parse your markdown using [@mintlify/mdx](https://www.npmjs.com/package/@mintlify/mdx).\n\n## Demo\n\nYou can check out the demo of [this page](https://github.com/mintlify/mdx/blob/main/examples/pages-router/pages/index.tsx) at [https://mdx-pages-router.vercel.app](https://mdx-pages-router.vercel.app).\n\n## How to use\n\n1. Call the `serialize` function inside `getStaticProps` and return the `mdxSource` object.\n\n ```tsx\n export const getStaticProps = (async () => {\n const mdxSource = await serialize({\n source: '## Markdown H2',\n });\n\n if ('error' in mdxSource) {\n // handle error case\n }\n\n return { props: { mdxSource } };\n }) satisfies GetStaticProps<{\n mdxSource: SerializeSuccess;\n }>;\n ```\n\n2. Pass the `mdxSource` object as props inside the `MDXComponent`.\n\n ```tsx\n export default function Page({ mdxSource }: InferGetStaticPropsType) {\n return ;\n }\n ```\n" }, { "path": "examples/pages-router/styles/globals.css", "content": "@tailwind base;\n@tailwind components;\n@tailwind utilities;\n\n@layer base {\n :root {\n --primary-light: 85 215 153;\n }\n}\n\n/* modified from https://github.com/shikijs/shiki/blob/main/packages/twoslash/style-rich.css */\n/* ===== Basic ===== */\n:root {\n --twoslash-border-color: #8888;\n --twoslash-underline-color: currentColor;\n --twoslash-highlighted-border: #c37d0d50;\n --twoslash-highlighted-bg: #c37d0d20;\n --twoslash-popup-bg: #f8f8f8;\n --twoslash-popup-color: inherit;\n --twoslash-popup-shadow: rgba(0, 0, 0, 0.08) 0px 1px 4px;\n --twoslash-docs-color: #888;\n --twoslash-docs-font: sans-serif;\n --twoslash-code-font: inherit;\n --twoslash-code-font-size: 1em;\n --twoslash-matched-color: inherit;\n --twoslash-unmatched-color: #888;\n --twoslash-cursor-color: #8888;\n --twoslash-error-color: #d45656;\n --twoslash-error-bg: #d4565620;\n --twoslash-warn-color: #c37d0d;\n --twoslash-warn-bg: #c37d0d20;\n --twoslash-tag-color: #3772cf;\n --twoslash-tag-bg: #3772cf20;\n --twoslash-tag-warn-color: var(--twoslash-warn-color);\n --twoslash-tag-warn-bg: var(--twoslash-warn-bg);\n --twoslash-tag-annotate-color: #1ba673;\n --twoslash-tag-annotate-bg: #1ba67320;\n --twoslash-text-size: 0.8rem;\n --twoslash-docs-tag-style: italic;\n}\n\n/* Respect people's wishes to not have animations */\n@media (prefers-reduced-motion: reduce) {\n .twoslash * {\n transition: none !important;\n }\n}\n\n/* ===== Hover Info ===== */\n.twoslash:hover .twoslash-hover {\n border-color: var(--twoslash-underline-color);\n}\n\n.twoslash .twoslash-hover {\n border-bottom: 1px dotted transparent;\n transition-timing-function: ease;\n transition: border-color 0.3s;\n position: relative;\n}\n\n\n/* ===== Popup Override ===== */\n.mint-twoslash-popover {\n background: var(--twoslash-popup-bg);\n color: var(--twoslash-popup-color);\n border: 1px solid var(--twoslash-border-color);\n border-radius: 4px;\n pointer-events: auto;\n text-align: left;\n box-shadow: var(--twoslash-popup-shadow);\n display: inline-flex;\n flex-direction: column;\n}\n\n.mint-twoslash-popover-pre {\n display: flex;\n font-size: var(--twoslash-text-size);\n font-family: var(--twoslash-code-font);\n}\n\n.mint-twoslash-popover:hover {\n user-select: auto;\n}\n\n.twoslash .twoslash-popup-arrow {\n display: none;\n}\n\n.twoslash-popup-code,\n.twoslash-popup-error,\n.twoslash-popup-docs {\n padding: 6px 8px !important;\n}\n\n.mint-twoslash-popover .twoslash-popup-docs {\n color: var(--twoslash-docs-color);\n font-family: var(--twoslash-docs-font);\n font-size: var(--twoslash-text-size);\n max-width: unset;\n}\n\n.mint-twoslash-popover .twoslash-popup-error {\n color: var(--twoslash-error-color);\n background-color: var(--twoslash-error-bg);\n font-family: var(--twoslash-docs-font);\n font-size: var(--twoslash-text-size);\n}\n\n.mint-twoslash-popover .twoslash-popup-docs-tags {\n display: flex;\n flex-direction: column;\n font-family: var(--twoslash-docs-font);\n}\n\n.mint-twoslash-popover .twoslash-popup-docs-tag-name {\n margin-right: 0.5em;\n font-style: var(--twoslash-docs-tag-style);\n}\n\n.mint-twoslash-popover .twoslash-popup-docs-tag-name {\n font-family: var(--twoslash-code-font);\n}\n\n/* ===== Query Line ===== */\n.mint-twoslash-popover .twoslash-query-line .twoslash-popup-container {\n position: relative;\n margin-bottom: 1.4em;\n transform: translateY(0.6em);\n}\n\n/* ===== Error Line ===== */\n.mint-twoslash-popover .twoslash-error-line {\n position: relative;\n background-color: var(--twoslash-error-bg);\n border-left: 3px solid var(--twoslash-error-color);\n color: var(--twoslash-error-color);\n padding: 6px 12px;\n margin: 0.2em 0;\n min-width: 100%;\n width: max-content;\n}\n\n.mint-twoslash-popover .twoslash-error-line.twoslash-error-level-warning {\n background-color: var(--twoslash-warn-bg);\n border-left: 3px solid var(--twoslash-warn-color);\n color: var(--twoslash-warn-color);\n}\n\n.mint-twoslash-popover .twoslash-error {\n background: url(\"data:image/svg+xml,%3Csvg%20xmlns%3D'http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg'%20viewBox%3D'0%200%206%203'%20enable-background%3D'new%200%200%206%203'%20height%3D'3'%20width%3D'6'%3E%3Cg%20fill%3D'%23c94824'%3E%3Cpolygon%20points%3D'5.5%2C0%202.5%2C3%201.1%2C3%204.1%2C0'%2F%3E%3Cpolygon%20points%3D'4%2C0%206%2C2%206%2C0.6%205.4%2C0'%2F%3E%3Cpolygon%20points%3D'0%2C2%201%2C3%202.4%2C3%200%2C0.6'%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E\") repeat-x bottom left;\n padding-bottom: 2px;\n}\n\n.mint-twoslash-popover .twoslash-error.twoslash-error-level-warning {\n background: url(\"data:image/svg+xml,%3Csvg%20xmlns%3D'http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg'%20viewBox%3D'0%200%206%203'%20enable-background%3D'new%200%200%206%203'%20height%3D'3'%20width%3D'6'%3E%3Cg%20fill%3D'%23c37d0d'%3E%3Cpolygon%20points%3D'5.5%2C0%202.5%2C3%201.1%2C3%204.1%2C0'%2F%3E%3Cpolygon%20points%3D'4%2C0%206%2C2%206%2C0.6%205.4%2C0'%2F%3E%3Cpolygon%20points%3D'0%2C2%201%2C3%202.4%2C3%200%2C0.6'%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E\") repeat-x bottom left;\n padding-bottom: 2px;\n}\n\n/* ===== Completeions ===== */\n.mint-twoslash-popover .twoslash-completion-cursor {\n position: relative;\n}\n\n.mint-twoslash-popover .twoslash-completion-cursor .twoslash-completion-list {\n user-select: none;\n position: absolute;\n top: 0;\n left: 0;\n transform: translate(0, 1.2em);\n margin: 3px 0 0 -1px;\n display: inline-block;\n z-index: 8;\n box-shadow: var(--twoslash-popup-shadow);\n background: var(--twoslash-popup-bg);\n border: 1px solid var(--twoslash-border-color);\n}\n\n.twoslash-completion-list {\n width: 240px;\n font-size: var(--twoslash-text-size);\n padding: 4px;\n display: flex;\n flex-direction: column;\n gap: 4px;\n}\n\n.twoslash-completion-list:hover {\n user-select: auto;\n}\n\n.twoslash-completion-list::before {\n background-color: var(--twoslash-cursor-color);\n width: 2px;\n position: absolute;\n top: -1.6em;\n height: 1.4em;\n left: -1px;\n content: ' ';\n}\n\n.twoslash-completion-list li {\n overflow: hidden;\n display: flex;\n align-items: center;\n gap: 0.25em;\n line-height: 1em;\n}\n\n.twoslash-completion-list li span.twoslash-completions-unmatched {\n color: var(--twoslash-unmatched-color);\n}\n\n.twoslash-completion-list .deprecated {\n text-decoration: line-through;\n opacity: 0.5;\n}\n\n.twoslash-completion-list li span.twoslash-completions-matched {\n color: var(--twoslash-matched-color);\n}\n\n/* Highlights */\n.twoslash-highlighted {\n background-color: var(--twoslash-highlighted-bg);\n border: 1px solid var(--twoslash-highlighted-border);\n padding: 1px 2px;\n margin: -1px -3px;\n border-radius: 4px;\n}\n\n/* Icons */\n.twoslash-completion-list .twoslash-completions-icon {\n color: var(--twoslash-unmatched-color);\n width: 1em;\n flex: none;\n}\n\n/* Custom Tags */\n.mint-twoslash-popover .twoslash-tag-line {\n position: relative;\n background-color: var(--twoslash-tag-bg);\n border-left: 3px solid var(--twoslash-tag-color);\n color: var(--twoslash-tag-color);\n padding: 6px 10px;\n margin: 0.2em 0;\n display: flex;\n align-items: center;\n gap: 0.3em;\n min-width: 100%;\n width: max-content;\n}\n\n.mint-twoslash-popover .twoslash-tag-line .twoslash-tag-icon {\n width: 1.1em;\n color: inherit;\n}\n\n.mint-twoslash-popover .twoslash-tag-line.twoslash-tag-error-line {\n background-color: var(--twoslash-error-bg);\n border-left: 3px solid var(--twoslash-error-color);\n color: var(--twoslash-error-color);\n}\n\n.mint-twoslash-popover .twoslash-tag-line.twoslash-tag-warn-line {\n background-color: var(--twoslash-tag-warn-bg);\n border-left: 3px solid var(--twoslash-tag-warn-color);\n color: var(--twoslash-tag-warn-color);\n}\n\n.mint-twoslash-popover .twoslash-tag-line.twoslash-tag-annotate-line {\n background-color: var(--twoslash-tag-annotate-bg);\n border-left: 3px solid var(--twoslash-tag-annotate-color);\n color: var(--twoslash-tag-annotate-color);\n}\n" }, { "path": "examples/pages-router/tailwind.config.ts", "content": "import type { Config } from 'tailwindcss';\n\nconst config: Config = {\n content: [\n './pages/**/*.{js,ts,jsx,tsx,mdx}',\n './components/**/*.{js,ts,jsx,tsx,mdx}',\n './app/**/*.{js,ts,jsx,tsx,mdx}',\n ],\n theme: {\n extend: {\n backgroundImage: {\n 'gradient-radial': 'radial-gradient(var(--tw-gradient-stops))',\n 'gradient-conic': 'conic-gradient(from 180deg at 50% 50%, var(--tw-gradient-stops))',\n },\n },\n },\n plugins: [require('@tailwindcss/typography')],\n};\nexport default config;\n" }, { "path": "examples/pages-router/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"target\": \"es5\",\n \"lib\": [\"dom\", \"dom.iterable\", \"esnext\"],\n \"allowJs\": true,\n \"skipLibCheck\": true,\n \"strict\": true,\n \"noEmit\": true,\n \"esModuleInterop\": true,\n \"module\": \"esnext\",\n \"moduleResolution\": \"bundler\",\n \"resolveJsonModule\": true,\n \"isolatedModules\": true,\n \"jsx\": \"preserve\",\n \"incremental\": true,\n \"paths\": {\n \"@/*\": [\"./*\"]\n }\n },\n \"include\": [\"next-env.d.ts\", \"**/*.ts\", \"**/*.tsx\"],\n \"exclude\": [\"node_modules\"]\n}\n" }, { "path": "package.json", "content": "{\n \"name\": \"mdx\",\n \"private\": true,\n \"scripts\": {\n \"build\": \"yarn workspaces foreach --topological-dev -Av run build\"\n },\n \"workspaces\": [\n \"packages/*\",\n \"examples/*\"\n ],\n \"packageManager\": \"yarn@4.3.1\"\n}\n" }, { "path": "packages/mdx/package.json", "content": "{\n \"name\": \"@mintlify/mdx\",\n \"version\": \"4.0.0\",\n \"description\": \"Markdown parser from Mintlify\",\n \"main\": \"./dist/index.js\",\n \"types\": \"./dist/index.d.ts\",\n \"sideEffects\": false,\n \"files\": [\n \"dist\"\n ],\n \"exports\": {\n \".\": {\n \"import\": \"./dist/index.js\",\n \"types\": \"./dist/index.d.ts\"\n },\n \"./rsc\": {\n \"import\": \"./dist/client/rsc.js\",\n \"types\": \"./dist/client/rsc.d.ts\"\n },\n \"./client\": {\n \"import\": \"./dist/client/default.js\",\n \"types\": \"./dist/client/default.d.ts\"\n },\n \"./server\": {\n \"import\": \"./dist/server/index.js\",\n \"types\": \"./dist/server/index.d.ts\"\n },\n \"./types\": {\n \"import\": \"./dist/types/index.js\",\n \"types\": \"./dist/types/index.d.ts\"\n },\n \"./plugins\": {\n \"import\": \"./dist/plugins/index.js\",\n \"types\": \"./dist/plugins/index.d.ts\"\n },\n \"./constants\": {\n \"import\": \"./dist/plugins/rehype/shiki-constants.js\",\n \"types\": \"./dist/plugins/rehype/shiki-constants.d.ts\"\n },\n \"./ui\": {\n \"import\": \"./dist/ui/index.js\",\n \"types\": \"./dist/ui/index.d.ts\"\n }\n },\n \"type\": \"module\",\n \"publishConfig\": {\n \"access\": \"public\",\n \"registry\": \"https://registry.npmjs.org/\"\n },\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/mintlify/mdx.git\"\n },\n \"scripts\": {\n \"prepare\": \"npm run build\",\n \"build\": \"tsc --project tsconfig.build.json\",\n \"clean:build\": \"rimraf dist\",\n \"clean:all\": \"rimraf node_modules .eslintcache && yarn clean:build\",\n \"watch\": \"tsc --watch\",\n \"type\": \"tsc --noEmit\",\n \"lint\": \"eslint . --cache\",\n \"format\": \"prettier . --write\",\n \"format:check\": \"prettier . --check\"\n },\n \"author\": \"Mintlify, Inc.\",\n \"license\": \"MIT\",\n \"devDependencies\": {\n \"@mintlify/eslint-config\": \"^1.0.4\",\n \"@mintlify/eslint-config-typescript\": \"^1.0.9\",\n \"@mintlify/prettier-config\": \"^1.0.1\",\n \"@mintlify/ts-config\": \"^2.0.2\",\n \"@trivago/prettier-plugin-sort-imports\": \"^4.3.0\",\n \"@tsconfig/recommended\": \"1.x\",\n \"@types/hast\": \"^3.0.4\",\n \"@types/react\": \"^19.2.1\",\n \"@types/react-dom\": \"^19.2.1\",\n \"@types/unist\": \"^3.0.3\",\n \"@typescript-eslint/eslint-plugin\": \"6.x\",\n \"@typescript-eslint/parser\": \"6.x\",\n \"eslint\": \"8.x\",\n \"eslint-config-prettier\": \"8.x\",\n \"eslint-plugin-unused-imports\": \"^3.x\",\n \"prettier\": \"^3.1.1\",\n \"prettier-plugin-tailwindcss\": \"^0.6.8\",\n \"react\": \"^19.2.1\",\n \"react-dom\": \"^19.2.1\",\n \"rimraf\": \"^5.0.1\",\n \"typescript\": \"^5.7.2\"\n },\n \"peerDependencies\": {\n \"@radix-ui/react-popover\": \"^19.2.1\",\n \"react\": \"^19.2.1\",\n \"react-dom\": \"^19.2.1\"\n },\n \"dependencies\": {\n \"@shikijs/transformers\": \"^3.11.0\",\n \"@shikijs/twoslash\": \"^3.12.2\",\n \"arktype\": \"^2.1.26\",\n \"hast-util-to-string\": \"^3.0.1\",\n \"mdast-util-from-markdown\": \"^2.0.2\",\n \"mdast-util-gfm\": \"^3.1.0\",\n \"mdast-util-mdx-jsx\": \"^3.2.0\",\n \"mdast-util-to-hast\": \"^13.2.0\",\n \"next-mdx-remote-client\": \"^1.0.3\",\n \"rehype-katex\": \"^7.0.1\",\n \"remark-gfm\": \"^4.0.0\",\n \"remark-math\": \"^6.0.0\",\n \"remark-smartypants\": \"^3.0.2\",\n \"shiki\": \"^3.11.0\",\n \"unified\": \"^11.0.0\",\n \"unist-util-visit\": \"^5.0.0\"\n }\n}\n" }, { "path": "packages/mdx/src/client/default.tsx", "content": "import { MDXClient as BaseMDXClient, MDXClientProps } from 'next-mdx-remote-client/csr';\n\nimport { Popup, PopupContent, PopupTrigger } from '../ui/index.js';\n\nexport function MDXClient(props: MDXClientProps) {\n const mergedComponents = {\n Popup,\n PopupContent,\n PopupTrigger,\n ...props.components,\n };\n\n return ;\n}\n" }, { "path": "packages/mdx/src/client/rsc.tsx", "content": "import { MDXRemote as BaseMDXRemote, MDXComponents } from 'next-mdx-remote-client/rsc';\nimport { SerializeOptions } from 'next-mdx-remote-client/serialize';\nimport rehypeKatex from 'rehype-katex';\nimport remarkGfm from 'remark-gfm';\nimport remarkMath from 'remark-math';\nimport remarkSmartypants from 'remark-smartypants';\n\nimport { rehypeSyntaxHighlighting, RehypeSyntaxHighlightingOptions } from '../plugins/index.js';\nimport { Popup, PopupContent, PopupTrigger } from '../ui/index.js';\n\nexport async function MDXRemote({\n source,\n mdxOptions,\n scope,\n components,\n parseFrontmatter,\n syntaxHighlightingOptions,\n}: {\n source: string;\n mdxOptions?: SerializeOptions['mdxOptions'];\n scope?: SerializeOptions['scope'];\n components?: MDXComponents;\n parseFrontmatter?: SerializeOptions['parseFrontmatter'];\n syntaxHighlightingOptions?: RehypeSyntaxHighlightingOptions;\n}) {\n const mergedComponents = {\n Popup,\n PopupContent,\n PopupTrigger,\n ...components,\n };\n\n return (\n \n );\n}\n" }, { "path": "packages/mdx/src/index.ts", "content": "" }, { "path": "packages/mdx/src/plugins/index.ts", "content": "export * from './rehype/index.js';\n" }, { "path": "packages/mdx/src/plugins/rehype/index.ts", "content": "export * from './rehypeSyntaxHighlighting.js';\n" }, { "path": "packages/mdx/src/plugins/rehype/rehypeSyntaxHighlighting.ts", "content": "import { transformerTwoslash } from '@shikijs/twoslash';\nimport { type } from 'arktype';\nimport type { Element, Root } from 'hast';\nimport { toString } from 'hast-util-to-string';\nimport type { MdxJsxFlowElementHast, MdxJsxTextElementHast } from 'mdast-util-mdx-jsx';\nimport { createHighlighter, type Highlighter } from 'shiki';\nimport type { Plugin } from 'unified';\nimport { visit } from 'unist-util-visit';\n\nimport {\n type ShikiLang,\n type ShikiTheme,\n shikiColorReplacements,\n DEFAULT_LANG_ALIASES,\n DEFAULT_LANG,\n DEFAULT_DARK_THEME,\n DEFAULT_LIGHT_THEME,\n DEFAULT_THEMES,\n DEFAULT_LANGS,\n SHIKI_TRANSFORMERS,\n UNIQUE_LANGS,\n} from './shiki-constants.js';\nimport { TextMateGrammar, TextMateGrammarType } from './shiki/custom-language.js';\nimport { getTwoslashOptions, parseLineComment } from './twoslash/config.js';\nimport { getLanguage } from './utils.js';\n\nexport type RehypeSyntaxHighlightingOptions = {\n theme?: ShikiTheme;\n themes?: Record<'light' | 'dark', ShikiTheme>;\n codeStyling?: 'dark' | 'system' | 'light' | Record | null;\n linkMap?: Map;\n customLanguages?: string[];\n};\n\nlet highlighterPromise: Promise | null = null;\n\nasync function getHighlighter(): Promise {\n if (!highlighterPromise) {\n highlighterPromise = createHighlighter({\n themes: DEFAULT_THEMES,\n langs: DEFAULT_LANGS,\n });\n }\n return highlighterPromise;\n}\n\nexport const rehypeSyntaxHighlighting: Plugin<[RehypeSyntaxHighlightingOptions?], Root, Root> = (\n options = {}\n) => {\n return async (tree) => {\n const nodesToProcess: Promise[] = [];\n const customLanguageNames: string[] = [];\n\n const themesToLoad: ShikiTheme[] = [];\n if (options.themes) {\n themesToLoad.push(options.themes.dark);\n themesToLoad.push(options.themes.light);\n } else if (options.theme) {\n themesToLoad.push(options.theme);\n }\n\n const highlighter = await getHighlighter();\n\n await Promise.all([\n ...themesToLoad\n .filter(\n (theme): theme is Exclude =>\n !DEFAULT_THEMES.includes(theme) && theme !== 'css-variables'\n )\n .map((theme) => highlighter.loadTheme(theme)),\n ...(options.customLanguages?.map(async (unparsedLang) => {\n const parsedLang = JSON.parse(unparsedLang);\n const lang = TextMateGrammar(parsedLang);\n if (lang instanceof type.errors) {\n console.error(lang.summary);\n return;\n }\n await highlighter.loadLanguage(lang);\n const possibleNames = [lang.name, lang.displayName, ...(lang.aliases ?? [])];\n customLanguageNames.push(...possibleNames.filter((l) => l != undefined));\n }) ?? []),\n ]);\n\n visit(tree, 'element', (node, index, parent) => {\n const child = node.children[0];\n if (\n !parent ||\n index === undefined ||\n node.type !== 'element' ||\n node.tagName !== 'pre' ||\n !child ||\n child.type !== 'element' ||\n child.tagName !== 'code'\n ) {\n return;\n }\n\n // set the metadata of `node` (which is a pre element) to that of\n // `child` (which is the code element that likely contains all the metadata)\n if (!Object.keys(node.properties).length) {\n node.properties = child.properties;\n }\n if (!node.data) {\n node.data = child.data;\n }\n\n let lang =\n getLanguage(node, DEFAULT_LANG_ALIASES) ??\n getLanguage(child, DEFAULT_LANG_ALIASES) ??\n DEFAULT_LANG;\n\n if (\n !DEFAULT_LANGS.includes(lang) &&\n !customLanguageNames.includes(lang) &&\n UNIQUE_LANGS.includes(lang)\n ) {\n nodesToProcess.push(\n highlighter.loadLanguage(lang).then(() => {\n traverseNode({ node, index, parent, highlighter, lang, options });\n })\n );\n } else {\n if (!UNIQUE_LANGS.includes(lang) && !customLanguageNames.includes(lang)) {\n lang = DEFAULT_LANG;\n }\n traverseNode({ node, index, parent, highlighter, lang, options });\n }\n });\n await Promise.all(nodesToProcess);\n };\n};\n\nfunction traverseNode({\n node,\n index,\n parent,\n highlighter,\n lang,\n options,\n}: {\n node: Element;\n index: number;\n parent: Element | Root | MdxJsxTextElementHast | MdxJsxFlowElementHast;\n highlighter: Highlighter;\n lang: ShikiLang;\n options: RehypeSyntaxHighlightingOptions;\n}) {\n try {\n let code = toString(node);\n\n const meta = node.data?.meta?.split(' ') ?? [];\n const twoslashIndex = meta.findIndex((str) => str.toLowerCase() === 'twoslash');\n const shouldUseTwoslash = twoslashIndex > -1;\n\n if (node.data && node.data.meta && shouldUseTwoslash) {\n meta.splice(twoslashIndex, 1);\n node.data.meta = meta.join(' ').trim() || undefined;\n }\n\n const linkMap = options.linkMap ?? new Map();\n if (shouldUseTwoslash) {\n const splitCode = code.split('\\n');\n\n for (const [i, line] of splitCode.entries()) {\n const parsedLineComment = parseLineComment(line);\n if (!parsedLineComment) continue;\n const { word, href } = parsedLineComment;\n linkMap.set(word, href);\n splitCode.splice(i, 1);\n }\n\n code = splitCode.join('\\n');\n }\n\n const twoslashOptions = getTwoslashOptions({ linkMap });\n\n const hast = highlighter.codeToHast(code, {\n lang: lang ?? DEFAULT_LANG,\n meta: shouldUseTwoslash ? { __raw: 'twoslash' } : undefined,\n themes: {\n light:\n options.themes?.light ??\n options.theme ??\n (options.codeStyling === 'dark' ? DEFAULT_DARK_THEME : DEFAULT_LIGHT_THEME),\n dark: options.themes?.dark ?? options.theme ?? DEFAULT_DARK_THEME,\n },\n colorReplacements: shikiColorReplacements,\n tabindex: false,\n tokenizeMaxLineLength: 1000,\n transformers: [...SHIKI_TRANSFORMERS, transformerTwoslash(twoslashOptions)],\n });\n\n const codeElement = hast.children[0] as Element;\n if (!codeElement) return;\n\n const preChild = codeElement.children[0] as Element;\n\n node.data = node.data ?? {};\n codeElement.data = node.data;\n codeElement.properties.language = lang;\n if (preChild) {\n preChild.data = node.data;\n preChild.properties.language = lang;\n }\n parent.children.splice(index, 1, codeElement);\n } catch (err) {\n if (err instanceof Error && /Unknown language/.test(err.message)) {\n return;\n }\n throw err;\n }\n}\n\nexport { TextMateGrammar, type TextMateGrammarType };\n" }, { "path": "packages/mdx/src/plugins/rehype/shiki/custom-language.ts", "content": "import { scope } from 'arktype';\n\n// Types come from the LanguageRegistration type in Shiki: node_modules/@shikijs/types/dist/index.d.ts\nconst types = scope({\n ScopeName: 'string',\n ScopePath: 'string',\n ScopePattern: 'string',\n IncludeString: 'string',\n RegExpString: 'string | RegExp',\n\n ILocation: {\n filename: 'string',\n line: 'number',\n char: 'number',\n },\n\n ILocatable: {\n '$vscodeTextmateLocation?': 'ILocation',\n },\n\n IRawCapturesMap: {\n '[string]': 'IRawRule',\n },\n\n IRawRepositoryMap: {\n '[string]': 'IRawRule',\n },\n\n IRawCaptures: 'IRawCapturesMap & ILocatable',\n\n _IRawRule: {\n 'include?': 'IncludeString',\n 'name?': 'ScopeName',\n 'contentName?': 'ScopeName',\n 'match?': 'RegExpString',\n 'captures?': 'IRawCaptures',\n 'begin?': 'RegExpString',\n 'beginCaptures?': 'IRawCaptures',\n 'end?': 'RegExpString',\n 'endCaptures?': 'IRawCaptures',\n 'while?': 'RegExpString',\n 'whileCaptures?': 'IRawCaptures',\n 'patterns?': 'IRawRule[]',\n 'repository?': 'IRawRepository',\n 'applyEndPatternLast?': 'boolean',\n '[string]': 'unknown',\n },\n\n IRawRule: '_IRawRule & ILocatable',\n\n IRawRepository: 'IRawRepositoryMap & ILocatable',\n\n _IRawGrammar: {\n repository: 'IRawRepository',\n scopeName: 'ScopeName',\n patterns: 'IRawRule[]',\n 'injections?': {\n '[string]': 'IRawRule',\n },\n 'injectionSelector?': 'string',\n 'fileTypes?': 'string[]',\n 'name?': 'string',\n 'firstLineMatch?': 'string',\n '[string]': 'unknown',\n },\n\n IRawGrammar: 'ILocatable & _IRawGrammar',\n\n LanguageRegistration: {\n name: 'string',\n scopeName: 'string',\n 'displayName?': 'string',\n 'aliases?': 'string[]',\n 'embeddedLangs?': 'string[]',\n 'embeddedLangsLazy?': 'string[]',\n 'balancedBracketSelectors?': 'string[]',\n 'unbalancedBracketSelectors?': 'string[]',\n 'foldingStopMarker?': 'string',\n 'foldingStartMarker?': 'string',\n 'injectTo?': 'string[]',\n '[string]': 'unknown',\n },\n\n TextMateGrammar: 'LanguageRegistration & IRawGrammar',\n}).export();\n\nexport const TextMateGrammar = types.TextMateGrammar;\nexport type TextMateGrammarType = typeof TextMateGrammar.infer;\n" }, { "path": "packages/mdx/src/plugins/rehype/shiki-constants.ts", "content": "import {\n transformerNotationHighlight,\n transformerNotationFocus,\n transformerMetaHighlight,\n transformerNotationDiff,\n} from '@shikijs/transformers';\nimport type { ShikiTransformer } from '@shikijs/types';\nimport { createCssVariablesTheme } from 'shiki/core';\nimport type { BundledLanguage, ThemeRegistration } from 'shiki/types';\n\nexport const LINE_HIGHLIGHT_CLASS_NAME = 'line-highlight';\nexport const LINE_FOCUS_CLASS_NAME = 'line-focus';\nexport const LINE_DIFF_ADD_CLASS_NAME = 'line-diff line-add';\nexport const LINE_DIFF_REMOVE_CLASS_NAME = 'line-diff line-remove';\n\nexport type ShikiLang = BundledLanguage | 'ansi' | 'text';\nexport type ShikiTheme = (typeof SHIKI_THEMES)[number];\n\nexport const SHIKI_CSS_THEME = createCssVariablesTheme({\n name: 'css-variables',\n variablePrefix: '--mint-',\n variableDefaults: {\n 'color-text': '#171717',\n 'color-background': 'transparent',\n 'token-constant': '#171717',\n 'token-string': '#297a3a',\n 'token-comment': '#666666',\n 'token-keyword': '#bd2864',\n 'token-parameter': '#a35200',\n 'token-function': '#0068d6',\n 'token-string-expression': '#297a3a',\n 'token-punctuation': '#171717',\n 'token-link': '#297a3a',\n\n 'ansi-black': '#000000',\n 'ansi-black-dim': '#00000080',\n 'ansi-red': '#bb0000',\n 'ansi-red-dim': '#bb000080',\n 'ansi-green': '#00bb00',\n 'ansi-green-dim': '#00bb0080',\n 'ansi-yellow': '#bbbb00',\n 'ansi-yellow-dim': '#bbbb0080',\n 'ansi-blue': '#0000bb',\n 'ansi-blue-dim': '#0000bb80',\n 'ansi-magenta': '#ff00ff',\n 'ansi-magenta-dim': '#ff00ff80',\n 'ansi-cyan': '#00bbbb',\n 'ansi-cyan-dim': '#00bbbb80',\n 'ansi-white': '#eeeeee',\n 'ansi-white-dim': '#eeeeee80',\n 'ansi-bright-black': '#555555',\n 'ansi-bright-black-dim': '#55555580',\n 'ansi-bright-red': '#ff5555',\n 'ansi-bright-red-dim': '#ff555580',\n 'ansi-bright-green': '#00ff00',\n 'ansi-bright-green-dim': '#00ff0080',\n 'ansi-bright-yellow': '#ffff55',\n 'ansi-bright-yellow-dim': '#ffff5580',\n 'ansi-bright-blue': '#5555ff',\n 'ansi-bright-blue-dim': '#5555ff80',\n 'ansi-bright-magenta': '#ff55ff',\n 'ansi-bright-magenta-dim': '#ff55ff80',\n 'ansi-bright-cyan': '#55ffff',\n 'ansi-bright-cyan-dim': '#55ffff80',\n 'ansi-bright-white': '#ffffff',\n 'ansi-bright-white-dim': '#ffffff80',\n },\n fontStyle: true,\n});\n\nexport const DEFAULT_LANG = 'text' as const;\nexport const DEFAULT_DARK_THEME: ShikiTheme = 'dark-plus' as const;\nexport const DEFAULT_LIGHT_THEME: ShikiTheme = 'github-light-default' as const;\nexport const DEFAULT_THEMES: [ShikiTheme, ShikiTheme, ThemeRegistration] = [\n DEFAULT_LIGHT_THEME,\n DEFAULT_DARK_THEME,\n SHIKI_CSS_THEME,\n] as const;\n\nexport const shikiColorReplacements: Partial>> =\n {\n 'dark-plus': {\n '#1e1e1e': '#0B0C0E',\n },\n };\n\nexport const DEFAULT_LANG_ALIASES: Record = {\n ansi: 'ansi',\n abap: 'abap',\n 'actionscript-3': 'actionscript-3',\n ada: 'ada',\n 'angular-html': 'angular-html',\n 'angular-ts': 'angular-ts',\n apache: 'apache',\n apex: 'apex',\n apl: 'apl',\n applescript: 'applescript',\n ara: 'ara',\n asciidoc: 'asciidoc',\n adoc: 'asciidoc',\n asm: 'asm',\n astro: 'astro',\n awk: 'awk',\n ballerina: 'ballerina',\n bat: 'bat',\n batch: 'bat',\n beancount: 'beancount',\n berry: 'berry',\n be: 'berry',\n bibtex: 'bibtex',\n bicep: 'bicep',\n blade: 'blade',\n bsl: 'bsl',\n '1c': 'bsl',\n c: 'c',\n h: 'c',\n cadence: 'cadence',\n cdc: 'cadence',\n cairo: 'cairo',\n clarity: 'clarity',\n clojure: 'clojure',\n clj: 'clojure',\n cmake: 'cmake',\n cobol: 'cobol',\n codeowners: 'codeowners',\n codeql: 'codeql',\n ql: 'codeql',\n coffee: 'coffee',\n coffeescript: 'coffee',\n 'common-lisp': 'common-lisp',\n lisp: 'common-lisp',\n coq: 'coq',\n cpp: 'cpp',\n cc: 'cpp',\n hh: 'cpp',\n 'c++': 'cpp',\n crystal: 'crystal',\n csharp: 'csharp',\n 'c#': 'csharp',\n cs: 'csharp',\n css: 'css',\n csv: 'csv',\n cue: 'cue',\n cypher: 'cypher',\n cql: 'cypher',\n d: 'd',\n dart: 'dart',\n dax: 'dax',\n desktop: 'desktop',\n diff: 'diff',\n docker: 'docker',\n dockerfile: 'docker',\n dotenv: 'dotenv',\n 'dream-maker': 'dream-maker',\n edge: 'edge',\n elixir: 'elixir',\n elm: 'elm',\n 'emacs-lisp': 'emacs-lisp',\n elisp: 'emacs-lisp',\n erb: 'erb',\n erlang: 'erlang',\n erl: 'erlang',\n fennel: 'fennel',\n fish: 'fish',\n fluent: 'fluent',\n ftl: 'fluent',\n 'fortran-fixed-form': 'fortran-fixed-form',\n f: 'fortran-fixed-form',\n for: 'fortran-fixed-form',\n f77: 'fortran-fixed-form',\n 'fortran-free-form': 'fortran-free-form',\n f90: 'fortran-free-form',\n f95: 'fortran-free-form',\n f03: 'fortran-free-form',\n f08: 'fortran-free-form',\n f18: 'fortran-free-form',\n fsharp: 'fsharp',\n 'f#': 'fsharp',\n fs: 'fsharp',\n gdresource: 'gdresource',\n gdscript: 'gdscript',\n gdshader: 'gdshader',\n genie: 'genie',\n gherkin: 'gherkin',\n 'git-commit': 'git-commit',\n 'git-rebase': 'git-rebase',\n gleam: 'gleam',\n 'glimmer-js': 'glimmer-js',\n gjs: 'glimmer-js',\n 'glimmer-ts': 'glimmer-ts',\n gts: 'glimmer-ts',\n glsl: 'glsl',\n gnuplot: 'gnuplot',\n go: 'go',\n graphql: 'graphql',\n gql: 'graphql',\n groovy: 'groovy',\n hack: 'hack',\n haml: 'haml',\n handlebars: 'handlebars',\n hbs: 'handlebars',\n haskell: 'haskell',\n hs: 'haskell',\n haxe: 'haxe',\n hcl: 'hcl',\n hjson: 'hjson',\n hlsl: 'hlsl',\n html: 'html',\n 'html-derivative': 'html-derivative',\n http: 'http',\n hxml: 'hxml',\n hy: 'hy',\n imba: 'imba',\n ini: 'ini',\n properties: 'ini',\n java: 'java',\n javascript: 'javascript',\n js: 'javascript',\n jinja: 'jinja',\n jison: 'jison',\n json: 'json',\n json5: 'json5',\n jsonc: 'jsonc',\n jsonl: 'jsonl',\n jsonnet: 'jsonnet',\n jssm: 'jssm',\n fsl: 'jssm',\n jsx: 'jsx',\n julia: 'julia',\n jl: 'julia',\n kotlin: 'kotlin',\n kt: 'kotlin',\n kts: 'kotlin',\n kusto: 'kusto',\n kql: 'kusto',\n latex: 'latex',\n lean: 'lean',\n lean4: 'lean',\n less: 'less',\n liquid: 'liquid',\n llvm: 'llvm',\n log: 'log',\n logo: 'logo',\n lua: 'lua',\n luau: 'luau',\n make: 'make',\n makefile: 'make',\n markdown: 'markdown',\n md: 'markdown',\n marko: 'marko',\n matlab: 'matlab',\n mdc: 'mdc',\n mdx: 'mdx',\n mermaid: 'mermaid',\n mmd: 'mermaid',\n mipsasm: 'mipsasm',\n mips: 'mipsasm',\n mojo: 'mojo',\n move: 'move',\n narrat: 'narrat',\n nar: 'narrat',\n nextflow: 'nextflow',\n nf: 'nextflow',\n nginx: 'nginx',\n nim: 'nim',\n nix: 'nix',\n nushell: 'nushell',\n nu: 'nushell',\n 'objective-c': 'objective-c',\n objc: 'objective-c',\n 'objective-cpp': 'objective-cpp',\n ocaml: 'ocaml',\n pascal: 'pascal',\n perl: 'perl',\n php: 'php',\n plsql: 'plsql',\n po: 'po',\n pot: 'po',\n potx: 'po',\n polar: 'polar',\n postcss: 'postcss',\n powerquery: 'powerquery',\n powershell: 'powershell',\n ps: 'powershell',\n ps1: 'powershell',\n prisma: 'prisma',\n prolog: 'prolog',\n proto: 'proto',\n protobuf: 'proto',\n pug: 'pug',\n jade: 'pug',\n puppet: 'puppet',\n purescript: 'purescript',\n python: 'python',\n py: 'python',\n qml: 'qml',\n qmldir: 'qmldir',\n qss: 'qss',\n r: 'r',\n racket: 'racket',\n raku: 'raku',\n perl6: 'raku',\n razor: 'razor',\n reg: 'reg',\n regexp: 'regexp',\n regex: 'regexp',\n rel: 'rel',\n riscv: 'riscv',\n rst: 'rst',\n ruby: 'ruby',\n rb: 'ruby',\n rust: 'rust',\n rs: 'rust',\n sas: 'sas',\n sass: 'sass',\n scala: 'scala',\n scheme: 'scheme',\n scss: 'scss',\n sdbl: 'sdbl',\n '1c-query': 'sdbl',\n shaderlab: 'shaderlab',\n shader: 'shaderlab',\n shellscript: 'shellscript',\n bash: 'shellscript',\n sh: 'shellscript',\n shell: 'shellscript',\n zsh: 'shellscript',\n shellsession: 'shellsession',\n console: 'shellsession',\n smalltalk: 'smalltalk',\n solidity: 'solidity',\n soy: 'soy',\n 'closure-templates': 'soy',\n sparql: 'sparql',\n splunk: 'splunk',\n spl: 'splunk',\n sql: 'sql',\n 'ssh-config': 'ssh-config',\n stata: 'stata',\n stylus: 'stylus',\n styl: 'stylus',\n svelte: 'svelte',\n swift: 'swift',\n 'system-verilog': 'system-verilog',\n systemd: 'systemd',\n talonscript: 'talonscript',\n talon: 'talonscript',\n tasl: 'tasl',\n tcl: 'tcl',\n templ: 'templ',\n terraform: 'terraform',\n tf: 'terraform',\n tfvars: 'terraform',\n tex: 'tex',\n toml: 'toml',\n 'ts-tags': 'ts-tags',\n lit: 'ts-tags',\n tsv: 'tsv',\n tsx: 'tsx',\n turtle: 'turtle',\n twig: 'twig',\n typescript: 'typescript',\n ts: 'typescript',\n typespec: 'typespec',\n tsp: 'typespec',\n typst: 'typst',\n typ: 'typst',\n txt: 'text',\n text: 'text',\n plaintext: 'text',\n plain: 'text',\n v: 'v',\n vala: 'vala',\n vb: 'vb',\n cmd: 'vb',\n verilog: 'verilog',\n vhdl: 'vhdl',\n viml: 'viml',\n vim: 'viml',\n vimscript: 'viml',\n vue: 'vue',\n 'vue-html': 'vue-html',\n vyper: 'vyper',\n vy: 'vyper',\n wasm: 'wasm',\n wenyan: 'wenyan',\n 文言: 'wenyan',\n wgsl: 'wgsl',\n wikitext: 'wikitext',\n mediawiki: 'wikitext',\n wiki: 'wikitext',\n wit: 'wit',\n wolfram: 'wolfram',\n wl: 'wolfram',\n xml: 'xml',\n xsl: 'xsl',\n yaml: 'yaml',\n yml: 'yaml',\n zenscript: 'zenscript',\n zig: 'zig',\n};\n\nexport const UNIQUE_LANGS = Array.from(new Set(Object.values(DEFAULT_LANG_ALIASES)));\n\nexport const SHIKI_THEMES = [\n 'andromeeda',\n 'aurora-x',\n 'ayu-dark',\n 'catppuccin-frappe',\n 'catppuccin-latte',\n 'catppuccin-macchiato',\n 'catppuccin-mocha',\n 'dark-plus',\n 'dracula',\n 'dracula-soft',\n 'everforest-dark',\n 'everforest-light',\n 'github-dark',\n 'github-dark-default',\n 'github-dark-dimmed',\n 'github-dark-high-contrast',\n 'github-light',\n 'github-light-default',\n 'github-light-high-contrast',\n 'gruvbox-dark-hard',\n 'gruvbox-dark-medium',\n 'gruvbox-dark-soft',\n 'gruvbox-light-hard',\n 'gruvbox-light-medium',\n 'gruvbox-light-soft',\n 'houston',\n 'kanagawa-dragon',\n 'kanagawa-lotus',\n 'kanagawa-wave',\n 'laserwave',\n 'light-plus',\n 'material-theme',\n 'material-theme-darker',\n 'material-theme-lighter',\n 'material-theme-ocean',\n 'material-theme-palenight',\n 'min-dark',\n 'min-light',\n 'monokai',\n 'night-owl',\n 'nord',\n 'one-dark-pro',\n 'one-light',\n 'plastic',\n 'poimandres',\n 'red',\n 'rose-pine',\n 'rose-pine-dawn',\n 'rose-pine-moon',\n 'slack-dark',\n 'slack-ochin',\n 'snazzy-light',\n 'solarized-dark',\n 'solarized-light',\n 'synthwave-84',\n 'tokyo-night',\n 'vesper',\n 'vitesse-black',\n 'vitesse-dark',\n 'vitesse-light',\n\n 'css-variables', // for users who want to use custom CSS to style their code blocks\n] as const;\n\nexport const DEFAULT_LANGS = [\n 'bash',\n 'blade',\n 'c',\n 'css',\n 'c#',\n 'c++',\n 'dart',\n 'diff',\n 'go',\n 'html',\n 'java',\n 'javascript',\n 'jsx',\n 'json',\n 'kotlin',\n 'log',\n 'lua',\n 'markdown',\n 'mdx',\n 'php',\n 'powershell',\n 'python',\n 'ruby',\n 'rust',\n 'solidity',\n 'swift',\n 'toml',\n 'typescript',\n 'tsx',\n 'yaml',\n];\n\nexport const matchAlgorithm = {\n matchAlgorithm: 'v3',\n} as const;\n\nexport const SHIKI_TRANSFORMERS: ShikiTransformer[] = [\n transformerMetaHighlight({\n className: LINE_HIGHLIGHT_CLASS_NAME,\n }),\n transformerNotationHighlight({\n ...matchAlgorithm,\n classActiveLine: LINE_HIGHLIGHT_CLASS_NAME,\n }),\n transformerNotationFocus({\n ...matchAlgorithm,\n classActiveLine: LINE_FOCUS_CLASS_NAME,\n }),\n transformerNotationDiff({\n ...matchAlgorithm,\n classLineAdd: LINE_DIFF_ADD_CLASS_NAME,\n classLineRemove: LINE_DIFF_REMOVE_CLASS_NAME,\n }),\n];\n" }, { "path": "packages/mdx/src/plugins/rehype/twoslash/config.ts", "content": "import { rendererRich, type TransformerTwoslashOptions } from '@shikijs/twoslash';\nimport type { Element, ElementContent } from 'hast';\nimport type { Code } from 'mdast';\nimport { fromMarkdown } from 'mdast-util-from-markdown';\nimport { gfmFromMarkdown } from 'mdast-util-gfm';\nimport { defaultHandlers, toHast } from 'mdast-util-to-hast';\nimport type { ShikiTransformerContextCommon } from 'shiki/types';\nimport ts from 'typescript';\n\nconst twoslashCompilerOptions: ts.CompilerOptions = {\n target: ts.ScriptTarget.ESNext,\n lib: ['ESNext', 'DOM', 'esnext', 'dom', 'es2020'],\n};\n\nfunction onTwoslashError(err: unknown, code: string, lang: string) {\n console.error(JSON.stringify({ err, code, lang }));\n}\n\nfunction onShikiError(err: unknown, code: string, lang: string) {\n console.error(JSON.stringify({ err, code, lang }));\n}\n\nexport function getTwoslashOptions(\n { linkMap }: { linkMap: Map } = { linkMap: new Map() }\n): TransformerTwoslashOptions {\n return {\n onTwoslashError,\n onShikiError,\n // copied fuma's approach for custom popup\n // https://github.com/fuma-nama/fumadocs/blob/dev/packages/twoslash/src/index.ts\n renderer: rendererRich({\n renderMarkdown,\n renderMarkdownInline,\n queryRendering: 'line',\n hast: {\n hoverToken: {\n tagName: 'Popup',\n children(input) {\n for (const rootElement of input) {\n if (!('children' in rootElement)) continue;\n for (const [i, element] of rootElement.children.entries()) {\n if (element.type !== 'text') continue;\n const href = linkMap.get(element.value);\n if (!href) continue;\n const linkProperties = {\n href,\n ...(checkIsExternalLink(href) && {\n target: '_blank',\n rel: 'noopener noreferrer',\n }),\n };\n if (rootElement.type === 'element' && rootElement.tagName === 'PopupTrigger') {\n rootElement.properties = { ...rootElement.properties, ...linkProperties };\n } else {\n const newElement: ElementContent = {\n type: 'element',\n tagName: 'a',\n properties: linkProperties,\n children: [{ type: 'text', value: element.value }],\n };\n input.splice(i, 1, newElement);\n }\n }\n }\n return input;\n },\n },\n hoverPopup: {\n tagName: 'PopupContent',\n },\n hoverCompose: ({ popup, token }) => [\n popup,\n {\n type: 'element',\n tagName: 'PopupTrigger',\n properties: {},\n children: [token],\n },\n ],\n popupDocs: {\n class: 'prose-sm prose-gray dark:prose-dark twoslash-popup-docs',\n },\n popupTypes: {\n tagName: 'span',\n class: 'mint-twoslash-popover-pre',\n children: (v) => {\n if (v.length === 1 && v[0]?.type === 'element' && v[0]?.tagName === 'pre') return v;\n\n return [\n {\n type: 'element',\n tagName: 'code',\n properties: {\n class: 'twoslash-popup-code shiki',\n },\n children: v,\n },\n ];\n },\n },\n popupDocsTags: {\n class: 'prose-sm prose-gray dark:prose-dark twoslash-popup-docs twoslash-popup-docs-tags',\n },\n nodesHighlight: {\n class: 'highlighted-word twoslash-highlighted',\n },\n },\n }),\n langs: ['ts', 'typescript', 'js', 'javascript', 'tsx', 'jsx'],\n explicitTrigger: true,\n twoslashOptions: {\n compilerOptions: twoslashCompilerOptions,\n },\n };\n}\n\n/** https://github.com/fuma-nama/fumadocs/blob/2862a10c2d78b52c0a3f479ad21b255cc0031fc9/packages/twoslash/src/index.ts#L121-L150 */\nfunction renderMarkdown(this: ShikiTransformerContextCommon, md: string): ElementContent[] {\n const mdast = fromMarkdown(\n md.replace(/{@link (?[^}]*)}/g, '$1'), // replace jsdoc links\n { mdastExtensions: [gfmFromMarkdown()] }\n );\n\n return (\n toHast(mdast, {\n handlers: {\n code: (state, node: Code) => {\n if (node.lang) {\n return this.codeToHast(node.value, {\n ...this.options,\n transformers: [],\n meta: {\n __raw: node.meta ?? undefined,\n },\n lang: node.lang,\n }).children[0] as Element;\n }\n return defaultHandlers.code(state, node);\n },\n },\n }) as Element\n ).children;\n}\n\n/** https://github.com/fuma-nama/fumadocs/blob/2862a10c2d78b52c0a3f479ad21b255cc0031fc9/packages/twoslash/src/index.ts#L152-L168 */\nfunction renderMarkdownInline(\n this: ShikiTransformerContextCommon,\n md: string,\n context?: string\n): ElementContent[] {\n const text = context === 'tag:param' ? md.replace(/^(?[\\w$-]+)/, '`$1` ') : md;\n\n const children = renderMarkdown.call(this, text);\n if (children.length === 1 && children[0]?.type === 'element' && children[0].tagName === 'p')\n return children[0].children;\n return children;\n}\n\nexport function parseLineComment(line: string): { word: string; href: string } | undefined {\n line = line.trim();\n if (!line.startsWith('//')) return;\n\n line = line.replace(/^[\\/\\s]+/, '').trim();\n if (!line.startsWith('@link ') && !line.startsWith('@link:')) return;\n\n line = line.replace('@link:', '@link ');\n const parts = line.split('@link ')[1];\n if (!parts) return;\n\n const words = parts.split(' ').filter(Boolean);\n if (words.length === 1 && words[0]) {\n let word = words[0];\n if (word.endsWith(':')) word = word.slice(0, -1);\n const lowercaseWord = word.toLowerCase();\n const href = word.startsWith('#') ? lowercaseWord : `#${encodeURIComponent(lowercaseWord)}`;\n return { word, href };\n } else if (words.length === 2 && words[0] && words[1]) {\n let word = words[0];\n if (word.endsWith(':')) word = word.slice(0, -1);\n const href = words[1];\n if (!href.startsWith('#') && !href.startsWith('https://')) return;\n return { word, href };\n }\n\n return;\n}\n\ntype Url = `https://${string}`;\nfunction checkIsExternalLink(href: string | undefined): href is Url {\n let isExternalLink = false;\n try {\n if (href && URL.canParse(href)) isExternalLink = true;\n } catch {}\n return isExternalLink;\n}\n" }, { "path": "packages/mdx/src/plugins/rehype/utils.ts", "content": "import type { Element } from 'hast';\n\nimport { type ShikiLang } from './shiki-constants.js';\n\nexport function classNameOrEmptyArray(element: Element): string[] {\n const className = element.properties.className;\n if (Array.isArray(className) && className.every((el) => typeof el === 'string')) return className;\n return [];\n}\n\nexport function getLanguage(\n node: Element,\n aliases: Record\n): ShikiLang | undefined {\n const className = classNameOrEmptyArray(node);\n\n for (const classListItem of className) {\n if (classListItem.startsWith('language-')) {\n const lang = classListItem.slice(9).toLowerCase();\n if (lang) return aliases[lang] ?? (lang as ShikiLang);\n }\n }\n\n return undefined;\n}\n" }, { "path": "packages/mdx/src/server/index.ts", "content": "import { serialize as baseSerialize } from 'next-mdx-remote-client/serialize';\nimport rehypeKatex from 'rehype-katex';\nimport remarkGfm from 'remark-gfm';\nimport remarkMath from 'remark-math';\nimport remarkSmartypants from 'remark-smartypants';\n\nimport { rehypeSyntaxHighlighting, RehypeSyntaxHighlightingOptions } from '../plugins/index.js';\nimport type { SerializeOptions } from '../types/index.js';\n\nexport const serialize = async ({\n source,\n mdxOptions,\n scope,\n parseFrontmatter = true,\n syntaxHighlightingOptions,\n}: {\n source: string;\n mdxOptions?: SerializeOptions['mdxOptions'];\n scope?: SerializeOptions['scope'];\n parseFrontmatter?: SerializeOptions['parseFrontmatter'];\n syntaxHighlightingOptions?: RehypeSyntaxHighlightingOptions;\n}) => {\n try {\n return await baseSerialize({\n source,\n options: {\n mdxOptions: {\n ...mdxOptions,\n remarkPlugins: [\n remarkGfm,\n remarkSmartypants,\n remarkMath,\n ...(mdxOptions?.remarkPlugins || []),\n ],\n rehypePlugins: [\n rehypeKatex,\n [rehypeSyntaxHighlighting, syntaxHighlightingOptions],\n ...(mdxOptions?.rehypePlugins || []),\n ],\n format: mdxOptions?.format || 'mdx',\n },\n scope,\n parseFrontmatter,\n },\n });\n } catch (error) {\n console.error(`Error occurred while serializing MDX: ${error}`);\n\n throw error;\n }\n};\n" }, { "path": "packages/mdx/src/types/index.ts", "content": "import type { SerializeOptions, SerializeResult } from 'next-mdx-remote-client/serialize';\n\ntype SerializeSuccess = SerializeResult & { compiledSource: string };\n\nexport type { SerializeOptions, SerializeResult, SerializeSuccess };\n" }, { "path": "packages/mdx/src/ui/index.ts", "content": "export * from './popup.js';\n" }, { "path": "packages/mdx/src/ui/popup.tsx", "content": "'use client';\n\n// copied from fuma's approach for custom popup\n// https://github.com/fuma-nama/fumadocs/blob/dev/packages/twoslash/src/ui/popup.tsx\nimport { Popover, PopoverContent, PopoverPortal, PopoverTrigger } from '@radix-ui/react-popover';\nimport {\n type ComponentPropsWithoutRef,\n type ComponentRef,\n createContext,\n forwardRef,\n type ReactNode,\n useContext,\n useMemo,\n useRef,\n useState,\n} from 'react';\n\ninterface PopupContextObject {\n open: boolean;\n setOpen: (open: boolean) => void;\n\n handleOpen: (e: React.PointerEvent) => void;\n handleClose: (e: React.PointerEvent) => void;\n}\n\nconst PopupContext = createContext(undefined);\n\nfunction Popup({ delay = 300, children }: { delay?: number; children: ReactNode }) {\n const [open, setOpen] = useState(false);\n const openTimeoutRef = useRef(undefined);\n const closeTimeoutRef = useRef(undefined);\n\n return (\n \n ({\n open,\n setOpen,\n handleOpen(e) {\n if (e.pointerType === 'touch') return;\n if (closeTimeoutRef.current) clearTimeout(closeTimeoutRef.current);\n\n openTimeoutRef.current = window.setTimeout(() => {\n setOpen(true);\n }, delay);\n },\n handleClose(e) {\n if (e.pointerType === 'touch') return;\n if (openTimeoutRef.current) clearTimeout(openTimeoutRef.current);\n\n closeTimeoutRef.current = window.setTimeout(() => {\n setOpen(false);\n }, delay);\n },\n }),\n [delay, open]\n )}\n >\n {children}\n \n \n );\n}\n\nconst PopupTrigger = forwardRef<\n ComponentRef,\n ComponentPropsWithoutRef & { href?: string; target?: string; rel?: string }\n>(({ children, href, target, rel, ...props }, ref) => {\n const ctx = useContext(PopupContext);\n if (!ctx) throw new Error('Missing Popup Context');\n\n let element;\n if (href) {\n element = (\n \n {children}\n \n );\n } else {\n element = {children};\n }\n\n return (\n \n {element}\n \n );\n});\n\nPopupTrigger.displayName = 'PopupTrigger';\n\nconst PopupContent = forwardRef<\n ComponentRef,\n ComponentPropsWithoutRef\n>(({ className, side = 'bottom', align = 'center', sideOffset = 4, ...props }, ref) => {\n const ctx = useContext(PopupContext);\n if (!ctx) throw new Error('Missing Popup Context');\n\n return (\n \n {\n e.preventDefault();\n }}\n onCloseAutoFocus={(e) => {\n e.preventDefault();\n }}\n {...props}\n />\n \n );\n});\n\nPopupContent.displayName = 'PopupContent';\n\nexport { Popup, PopupTrigger, PopupContent };\n" }, { "path": "packages/mdx/tsconfig.build.json", "content": "{\n \"extends\": \"./tsconfig.json\",\n \"include\": [\"src/**/*.ts\", \"src/**/*.tsx\"]\n}\n" }, { "path": "packages/mdx/tsconfig.json", "content": "{\n \"extends\": \"@mintlify/ts-config\",\n \"compilerOptions\": {\n \"lib\": [\"dom\", \"dom.iterable\", \"esnext\"],\n \"jsx\": \"react-jsx\",\n \"target\": \"ES2021\",\n \"outDir\": \"dist\",\n \"declaration\": true,\n \"module\": \"Node16\"\n },\n \"include\": [\"**/*.ts\", \"**/*.tsx\"],\n \"exclude\": [\"node_modules\", \"dist\"]\n}\n" }, { "path": "readme.md", "content": "
\n \n \n \n
\n

\n

\n \n Mint\n \n

\n

\n

\n \n Open source docs builder that's beautiful, fast, and easy to work with.\n \n

\n

\n\n![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen?logo=github) [![Tweet](https://img.shields.io/twitter/url?url=https%3A%2F%2Fmintlify.com%2F)](https://twitter.com/intent/tweet?url=&text=Check%20out%20%40mintlify)\n\n

\n
\n\n# Mintlify's markdown parser\n\n**@mintlify/mdx** is a thin layer on top of [next-mdx-remote-client](https://github.com/ipikuka/next-mdx-remote-client) that provides a better developer experience for Next.js users by adding support for syntax highlighting.\n\n## Installation\n\n```bash\n# using npm\nnpm i @mintlify/mdx\n\n# using yarn\nyarn add @mintlify/mdx\n\n# using pnpm\npnpm add @mintlify/mdx\n```\n\n## Examples\n\n### Next.js pages router\n\n[You can check the example app here](https://github.com/mintlify/mdx/tree/main/examples/pages-router).\n\n1. Call the `serialize` function inside `getStaticProps` and return the `mdxSource` object.\n\n ```tsx\n export const getStaticProps = (async () => {\n const mdxSource = await serialize({\n source: '## Markdown H2',\n });\n\n if ('error' in mdxSource) {\n // handle error case\n }\n\n return { props: { mdxSource } };\n }) satisfies GetStaticProps<{\n mdxSource: SerializeSuccess;\n }>;\n ```\n\n2. Pass the `mdxSource` object as props inside the `MDXComponent`.\n\n ```tsx\n export default function Page({ mdxSource }: InferGetStaticPropsType) {\n return ;\n }\n ```\n\n### Next.js app router\n\n[You can check the example app here](https://github.com/mintlify/mdx/tree/main/examples/app-router).\n\n1. Use the `MDXRemote` component directly inside your async React Server Component.\n\n ```tsx\n import { MDXRemote } from '@mintlify/mdx';\n\n export default async function Home() {\n const source: `---\n title: Title\n ---\n\n ## Markdown H2\n `;\n\n return (\n
\n \n
\n );\n }\n ```\n\n## APIs\n\nSimilar to [next-mdx-remote-client](https://github.com/ipikuka/next-mdx-remote-client), this package exports the following APIs:\n\n- `serialize` - a function that compiles MDX source to SerializeResult.\n- `MDXClient` - a component that renders SerializeSuccess on the client.\n- `MDXRemote` - a component that both serializes and renders the source - should be used inside async React Server Component.\n\n### serialize\n\n```tsx\nimport { serialize } from '@mintlify/mdx';\n\nconst mdxSource = await serialize({\n source: '## Markdown H2',\n mdxOptions: {\n remarkPlugins: [\n // Remark plugins\n ],\n rehypePlugins: [\n // Rehype plugins\n ],\n },\n});\n```\n\n### MDXClient\n\n```tsx\n'use client';\n\nimport { MDXClient } from '@mintlify/mdx';\n\n;\n```\n\n### MDXRemote\n\n```tsx\nimport { MDXRemote } from '@mintlify/mdx';\n\n;\n```\n\n
\n

\n \n Built with ❤︎ by\n \n Mintlify\n \n \n

\n
\n" } ]