https://github.com/md2docx/react-markdown
SSR-ready React Markdown renderer with MDAST reuse, JSX support, and unified plugin pipeline.
https://github.com/md2docx/react-markdown
docx jsx markdown mdast react rehype remark renderer ssr unified
Last synced: about 1 month ago
JSON representation
SSR-ready React Markdown renderer with MDAST reuse, JSX support, and unified plugin pipeline.
- Host: GitHub
- URL: https://github.com/md2docx/react-markdown
- Owner: md2docx
- License: mpl-2.0
- Created: 2025-06-20T03:10:48.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2026-04-26T16:47:52.000Z (about 2 months ago)
- Last Synced: 2026-04-26T18:23:48.109Z (about 2 months ago)
- Topics: docx, jsx, markdown, mdast, react, rehype, remark, renderer, ssr, unified
- Language: TypeScript
- Homepage:
- Size: 737 KB
- Stars: 11
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: contributing.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# MDX Renderer [`@m2d/react-markdown`] 
[](https://github.com/md2docx/react-markdown/actions/workflows/test.yml)
[](https://codeclimate.com/github/md2docx/react-markdown/maintainability)
[](https://codecov.io/gh/md2docx/react-markdown)
[](https://www.npmjs.com/package/@m2d/react-markdown)
[](https://www.npmjs.com/package/@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`](https://github.com/md2docx/mdast2docx)**
Compared to `react-markdown`, this library offers:
| Feature | `@m2d/react-markdown` ✅ | `react-markdown` ❌ |
| -------------------------------------- | ------------------------ | ------------------- |
| Full JSX support (not just strings) | ✅ | ❌ |
| SSR-safe (no hooks) | ✅ | ✅ |
| Client Side component with memoization | ✅ | ❌ |
| MDAST + HAST access via `astRef` | ✅ | ❌ |
| Component-level overrides | ✅ | ✅ |
| Unified plugin support | ✅ | ✅ |
| Tiny bundle (minzipped) | **~35 kB** | ~45 kB |
| Built-in DOCX-friendly AST output | ✅ | ❌ |
---
## 📦 Installation
```bash
pnpm add @m2d/react-markdown
```
**_or_**
```bash
npm install @m2d/react-markdown
```
**_or_**
```bash
yarn add @m2d/react-markdown
```
---
## 🚀 Server vs Client
By default, this package is SSR-safe and has **no client-specific hooks**.
### ✅ Server (default):
```tsx
import { Md } from "@m2d/react-markdown";
```
### 🔁 Client (for dynamic reactivity/memoization):
```tsx
import { Md } from "@m2d/react-markdown/client";
```
This version supports client-side behavior with memoization and dynamic JSX rendering.
---
## ⚡ Example: Rendering + Exporting DOCX
```tsx
import { Md } from "@m2d/react-markdown/client";
import { toDocx } from "mdast2docx";
import { useRef } from "react";
const astRef = useRef([]);
export default function Page() {
return (
<>
{`# Hello\n\nThis is **Markdown**.`}
{
const doc = toDocx(astRef.current[0].mdast);
// Save or download doc
}}>
Export to DOCX
>
);
}
```
> 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**:
```tsx
import { Mdx } from "@m2d/react-markdown/server";
// ...
{"# Markdown Heading\n\nSome **rich** content."}
;
```
> `astRef.current` is an array — one per Markdown string — each with `{ mdast, hast }`.
> The default `` export accepts only string children for better optimization.
---
## 🎨 Component Overrides
```tsx
import { Md } from "@m2d/react-markdown";
import { Unwrap, Omit } from "@m2d/react-markdown/server";
,
}}>
{`*em is unwrapped*\n\n> blockquote is removed`}
;
```
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:
```tsx
{markdown}
```
---
## 📂 Accessing MDAST + HAST
```ts
type astRef = {
current: { mdast: Root; hast: HastRoot }[];
};
```
Useful for:
- 📄 DOCX export (`mdast2docx`)
- 🧪 AST testing or analysis
- 🛠️ Custom tree manipulation
---
## 📊 Performance
> **TL;DR:** `@m2d/react-markdown` performs competitively with `react-markdown`, especially on medium and large documents.
>
> 👉 [See full benchmarks →](./benchmark.md)
Benchmarks include:
- Multiple markdown fixture types (short, long, complex, deeply nested)
- Plugin configurations like `remark-gfm`, `remark-math`, `rehype-raw`
- Visual comparisons using interactive Mermaid `xychart-beta` charts
- Ops/sec, ±%, and future memory profiling
---
## 💬 Upcoming Changes – Seeking Feedback
We're proposing a **major change** to the internal `astRef` structure to better support MDX-style custom components and rendering flexibility:
👉 [Join the discussion →](https://github.com/md2docx/react-markdown/discussions/3)
Key goals:
- Allow `` to embed child components like JSX/MDX
- Simplify recursive rendering model
- Improve performance and reduce abstraction overhead
## 🧭 Roadmap
- [ ] 🔄 Merge JSX + `` segments into unified AST
- [x] 🧪 Structural test utilities
- [x] 🧑🏫 Next.js + DOCX example
---
## 🌍 Related Projects
- [`mdast2docx`](https://github.com/md2docx/mdast2docx) – Convert MDAST → `.docx`
- [`unified`](https://unifiedjs.com/) – Syntax tree ecosystem
- [`react-markdown`](https://github.com/remarkjs/react-markdown) – Popular alternative (less customizable)
---
## 🙏 Acknowledgements
We are deeply grateful to the open-source community whose work made this project possible.
- 🌱 **[react-markdown](https://github.com/remarkjs/react-markdown)** – For pioneering a React-based Markdown renderer. This library builds on its ideas while extending flexibility and SSR-readiness.
- 🛠 **[unified](https://github.com/unifiedjs/unified)** – The brilliant engine powering our markdown-to-AST transformations.
- ✨ **[remark](https://github.com/remarkjs/remark)** and **[rehype](https://github.com/rehypejs/rehype)** – For their modular ecosystems that make parsing and rendering delightful.
- 🧾 **[mdast2docx](https://github.com/md2docx/mdast2docx)** – Our sister project that inspired the MDAST-first architecture of this library.
> 💖 To the maintainers, contributors, and communities behind these projects — thank you for your generosity, vision, and dedication to making the web better for everyone.
---
## 📘 License
Licensed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/).
> 💡 Want to support this project? [Sponsor](https://github.com/sponsors/mayank1513) or check out our [courses](https://mayank-chaudhari.vercel.app/courses)!
---
Built with ❤️ by Mayank Kumar Chaudhari