Better MDX

[!WARNING] This project is developed primarily through vibe coding with AI assistance. Review the implementation carefully before using it in critical workflows.

Better MDX is a VS Code extension that provides syntax highlighting, TypeScript-aware editing, and built-in KaTeX support for MDX.

Features

• Syntax highlighting for Markdown, ESM, JSX, expressions, and fenced code blocks.
• TypeScript diagnostics, completions, path completions, and auto-imports in MDX.
• Built-in remark-math parsing with dynamic KaTeX semantic highlighting.
• KaTeX 0.18 command, environment, and snippet completions.
• IntelliSense recovery while top-level imports and exports are incomplete.

Settings

{
  "betterMdx.remarkMath.enabled": true,
  "betterMdx.remarkMath.singleDollar": true,
}

• remarkMath.enabled controls all math parsing, highlighting, and completions.
• remarkMath.singleDollar controls inline $...$ math; $$...$$ remains available when disabled.

Both settings support user, workspace, and workspace-folder scopes. Changes take effect immediately.

TypeScript

Better MDX uses a supported TypeScript 5/6 workspace SDK when available and otherwise falls back to the version bundled with VS Code. Use Better MDX: Select TypeScript Version to change the active SDK.

Compiler options such as strict, paths, baseUrl, types, and jsxImportSource are read from the nearest tsconfig.json or jsconfig.json. An open MDX file inherits that configuration even when tsconfig.include only lists TypeScript files, so aliases such as @/* work without adding **/*.mdx.

Extension conflicts

Disable unifiedjs.vscode-mdx while using Better MDX to avoid duplicate grammars, diagnostics, and completion providers. Better MDX displays a one-time warning when it detects the extension.

Limitations

• remark-math is currently the only supported MDX extension.

Development

Requirements: Node.js 24+, pnpm 11+, and VS Code 1.125+.

pnpm install
pnpm run typecheck
pnpm test
pnpm run test:extension
pnpm run package

Grammar and KaTeX catalog updates are available through pnpm run generate:grammar and pnpm run generate:katex. Normal builds do not access the network.

Third-party source and license information is recorded in THIRD_PARTY_NOTICES.md.