mdast-util-mdx-jsx vs. shiki

mdast-util-mdx-jsx is a specialized plugin for the `mdast` ecosystem, focusing on enabling JSX syntax within Markdown documents processed by `mdx`. Its core philosophy is to extend the Abstract Syntax Tree (AST) representation of Markdown to accommodate the complex structure introduced by JSX, allowing for more dynamic and component-driven content creation directly within Markdown.

shiki, on the other hand, is a sophisticated syntax highlighter designed to bring beautiful code highlighting to web applications. Its primary audience consists of developers building documentation sites, blogs, or any platform where code snippets need to be presented clearly and aesthetically. shiki's philosophy centers on providing a robust, themeable, and performant solution for rendering code across various frameworks.

A key architectural difference lies in their fundamental purpose: mdast-util-mdx-jsx operates at the AST level, manipulating the parsed structure of Markdown to integrate JSX nodes. It's concerned with representing the content accurately before rendering. shiki, conversely, is a rendering engine; it takes plain code and transforms it into an HTML or DOM structure with applied styling based on a syntax grammar.

Another technical distinction is their extension and integration model. mdast-util-mdx-jsx is a direct extension of the `mdast` processor, designed to be plugged into the `remark` or `mdx` build pipelines. shiki, while also extensible through themes and languages, primarily functions as a standalone highlighter that can be integrated into various frontend frameworks or build tools, often by consuming its output rather than being a direct pipeline stage.

From a developer experience perspective, mdast-util-mdx-jsx is for developers already entrenched in the `mdast`/`remark`/`mdx` ecosystem. Its integration is seamless within that context, but it requires understanding AST manipulation. shiki offers a more general developer experience; its API is straightforward for basic usage, and it provides excellent TypeScript support out of the box. Integrating shiki into a project is typically less about ASTs and more about calling a function with code and options.

Performance and bundle size reveal a significant divergence. mdast-util-mdx-jsx is remarkably lightweight, with a gzipped bundle size of a mere 5.1 kB. This makes it ideal for integration into existing build processes where minimizing overhead is crucial. shiki, while optimized, is considerably larger at 64.7 kB gzipped, reflecting its broader functionality and bundled assets like syntax grammars and themes.

Practically, you would choose mdast-util-mdx-jsx when your goal is to author content that mixes Markdown with React/Vue/etc. components directly within your `.mdx` files, and you need this structure to be correctly parsed and transformed by `mdast`. Consider shiki when you need to display code blocks attractively within your application, regardless of whether that application is built with MDX or any other technology; its strength is in code presentation.

The maintenance and community activity offer contrasting signals. mdast-util-mdx-jsx, despite its last update date, shows zero open issues, suggesting a stable and well-maintained state for its current version. shiki, while very actively developed with recent updates, has a backlog of 108 open issues, indicating a more dynamic but potentially less immediately resolved issue landscape.

For niche use cases, mdast-util-mdx-jsx excels in scenarios requiring programmatic generation or manipulation of MDX content that includes JSX, perhaps for dynamic documentation generation or complex content authoring tools. shiki is versatile for any project needing robust code highlighting, including handling less common programming languages if appropriate TextMate grammars are available or can be added, and supporting a wide array of popular themes.