MDX Renderer [@m2d/react-markdown]

✨ A modern, SSR-compatible Markdown renderer for React with full MDAST/HAST access — built for customization, performance, and document generation - docx/pdf.

🔥 Why @m2d/react-markdown?

@m2d/react-markdown goes beyond traditional React Markdown libraries by focusing on:

• ✅ Server-side rendering (SSR) without hooks
• ✅ Full JSX children support (not just strings)
• ✅ Access to raw MDAST & HAST trees
• ✅ Drop-in plugin support via Unified (remark, rehype, etc.)
• ✅ Custom component overrides per tag
• ✅ Integration with tools like mdast2docx

Compared to react-markdown, this library offers:

📦 Installation

pnpm add @m2d/react-markdown

or

npm install @m2d/react-markdown

or

yarn add @m2d/react-markdown

🚀 Server vs Client

By default, this package is SSR-safe and has no client-specific hooks.

✅ Server (default):

import { Md } from "@m2d/react-markdown";

🔁 Client (for dynamic reactivity/memoization):

import { Md } from "@m2d/react-markdown/client";

This version supports client-side behavior with memoization and dynamic JSX rendering.

⚡ Example: Rendering + Exporting DOCX

import { Md } from "@m2d/react-markdown/client";
import { toDocx } from "mdast2docx";
import { useRef } from "react";

const astRef = useRef([]);

export default function Page() {
  return (
    <>
      <Md astRef={astRef}>{`# Hello\n\nThis is **Markdown**.`}</Md>
      <button
        onClick={() => {
          const doc = toDocx(astRef.current[0].mdast);
          // Save or download doc
        }}>
        Export to DOCX
      </button>
    </>
  );
}

Note for Server Component use you can replace useRef with custom ref object const astRef = {current: undefined} as AstRef

🧠 JSX-Aware Parsing

Unlike most markdown renderers, @m2d/react-markdown supports arbitrary JSX as children:

<Md>
  <article>{"# Markdown Heading\n\nSome **rich** content."}</article>
</Md>

astRef.current is an array — one per Markdown string — each with { mdast, hast }.

🎨 Component Overrides

import { Md, Unwrap, Omit } from "@m2d/react-markdown";

<Md
  components={{
    em: Unwrap,
    blockquote: Omit,
    code: props => <CodeBlock {...props} />,
  }}>
  {`*em is unwrapped*\n\n> blockquote is removed`}
</Md>;

Use the built-in helpers:

• Unwrap – renders only children
• Omit – removes element and content entirely
• CodeBlock - it is your custom component

🔌 Plugin Support (Unified)

Use any remark or rehype plugin:

<Md remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeSlug, rehypeAutolinkHeadings]}>
  {markdown}
</Md>

📂 Accessing MDAST + HAST

type astRef = {
  current: { mdast: Root; hast: HastRoot }[];
};

Useful for:

• 📄 DOCX export (mdast2docx)
• 🧪 AST testing or analysis
• 🛠️ Custom tree manipulation

🧭 Roadmap

• 🔄 Merge JSX + <Md> segments into unified AST
• 🧪 Structural test utilities
• 🧑‍🏫 Next.js + DOCX example

🌍 Related Projects

• mdast2docx – Convert MDAST → .docx
• unified – Syntax tree ecosystem
• react-markdown – Popular alternative (less customizable)

📘 License

Licensed under the MPL-2.0.

💡 Want to support this project? Sponsor or check out our courses!

Built with ❤️ by Mayank Kumar Chaudhari