mdxjs-rs

mdxjs-rs (published as the mdxjs crate) is a Rust implementation of the MDX compiler that turns MDX — Markdown extended with embedded JSX and JavaScript expressions — into runnable JavaScript. Written by the maintainer of the MDX and micromark ecosystems, it mirrors the behavior of the reference JavaScript @mdx-js/mdx compiler while delivering the speed and memory safety of Rust.

Built on top of the markdown crate for CommonMark and GFM parsing and on swc_core for JavaScript/JSX AST handling and code generation, mdxjs-rs is designed to be embedded in build tools, bundlers, and static site generators that need to compile MDX content quickly. It supports configurable JSX runtimes, development mode, and the same plugin-shaped transformation pipeline as the JavaScript original.

What You Get

• A single compile entry point that turns MDX strings into JavaScript
• CommonMark and GitHub Flavored Markdown parsing via the markdown crate
• JSX and JavaScript expression handling through the SWC toolchain
• Configurable JSX runtime, pragma, and development-mode output
• Behavior aligned with the reference @mdx-js/mdx JavaScript compiler

Common Use Cases

• Embedding MDX compilation inside Rust-based build tools and bundlers
• Adding fast MDX support to static site generators and content pipelines
• Compiling MDX to JavaScript without a Node.js dependency in the toolchain

Under The Hood

Architecture - src/lib.rs exposes the compile API and drives a multi-stage pipeline: the markdown crate parses MDX to an mdast tree, mdast_util_to_hast.rs and hast.rs convert it to a HTML-like tree, hast_util_to_swc.rs and swc_util_build_jsx.rs lower it into an SWC ECMAScript AST, and the mdx_plugin_recma_document.rs and mdx_plugin_recma_jsx_rewrite.rs passes wrap and rewrite the JSX before swc.rs emits JavaScript. configuration.rs exposes the options.

Tech Stack - Rust, depending on the markdown crate for parsing, swc_core for ECMAScript AST/parser/codegen/visitor infrastructure, rustc-hash for fast maps, and optional serde for serializable configuration.

Code Quality - The pipeline is decomposed into small, purpose-named modules that each mirror a stage of the reference MDX architecture (mdast/hast/recma), and the crate uses pretty_assertions for readable test diffs. The port closely tracks the upstream JavaScript implementation’s semantics.

API Design - The surface is intentionally small: call compile (or compile with an Options/configuration struct) and receive JavaScript. Options map directly onto familiar MDX settings such as JSX runtime and development mode, so users of the JavaScript compiler can adopt it with little friction.