Skip to content

Commit 825dea7

Browse files
mayank1513mayank1513
committed
Apply changesets and update CHANGELOG [skip ci]
1 parent 2ee05c6 commit 825dea7

File tree

1 file changed

+80
-42
lines changed

1 file changed

+80
-42
lines changed

‎lib/README.md‎

Lines changed: 80 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,19 @@
1-
# MDX Renderer [@m2d/react-markdown] <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 40px"/>
1+
# MDX Renderer [`@m2d/react-markdown`] <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 40px"/>
22

3-
[![test](https://github.com/md2docx/react-markdown/actions/workflows/test.yml/badge.svg)](https://github.com/md2docx/react-markdown/actions/workflows/test.yml) [![Maintainability](https://api.codeclimate.com/v1/badges/aa896ec14c570f3bb274/maintainability)](https://codeclimate.com/github/md2docx/react-markdown/maintainability) [![codecov](https://codecov.io/gh/md2docx/react-markdown/graph/badge.svg)](https://codecov.io/gh/md2docx/react-markdown) [![Version](https://img.shields.io/npm/v/@m2d/react-markdown.svg?colorB=green)](https://www.npmjs.com/package/@m2d/react-markdown) [![Downloads](https://img.jsdelivr.com/img.shields.io/npm/d18m/@m2d/react-markdown.svg)](https://www.npmjs.com/package/@m2d/react-markdown) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@m2d/react-markdown) [![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/from-referrer/)
3+
[![test](https://github.com/md2docx/react-markdown/actions/workflows/test.yml/badge.svg)](https://github.com/md2docx/react-markdown/actions/workflows/test.yml)
4+
[![Maintainability](https://api.codeclimate.com/v1/badges/aa896ec14c570f3bb274/maintainability)](https://codeclimate.com/github/md2docx/react-markdown/maintainability)
5+
[![codecov](https://codecov.io/gh/md2docx/react-markdown/graph/badge.svg)](https://codecov.io/gh/md2docx/react-markdown)
6+
[![Version](https://img.shields.io/npm/v/@m2d/react-markdown.svg?colorB=green)](https://www.npmjs.com/package/@m2d/react-markdown)
7+
[![Downloads](https://img.jsdelivr.com/img.shields.io/npm/d18m/@m2d/react-markdown.svg)](https://www.npmjs.com/package/@m2d/react-markdown)
8+
![npm bundle size](https://img.shields.io/bundlephobia/minzip/@m2d/react-markdown)
49

5-
> ✨ A modern, JSX-compatible, SSR-ready Markdown renderer for React — with full access to MDAST & HAST trees for tools like `mdast2docx`.
10+
> ✨ A modern, SSR-compatible Markdown renderer for React with full MDAST/HAST access — built for **customization**, **performance**, and **document generation** - **docx/pdf**.
611
712
---
813

9-
## 🔥 Why mdx-render?
14+
## 🔥 Why `@m2d/react-markdown`?
1015

11-
`mdx-render` goes beyond traditional React Markdown libraries by focusing on:
16+
`@m2d/react-markdown` goes beyond traditional React Markdown libraries by focusing on:
1217

1318
- ✅ **Server-side rendering (SSR)** without hooks
1419
- ✅ **Full JSX children support** (not just strings)
@@ -17,9 +22,21 @@
1722
- ✅ **Custom component overrides** per tag
1823
- ✅ **Integration with tools like [`mdast2docx`](https://github.com/md2docx/mdast2docx)**
1924

25+
Compared to `react-markdown`, this library offers:
26+
27+
| Feature | `@m2d/react-markdown` ✅ | `react-markdown` ❌ |
28+
| ----------------------------------- | ------------------------ | ------------------- |
29+
| Full JSX support (not just strings) | ✅ | ❌ |
30+
| SSR-safe (no hooks) | ✅ | ⚠️ (limited) |
31+
| MDAST + HAST access via `astRef` | ✅ | ❌ |
32+
| Component-level overrides | ✅ | ✅ |
33+
| Unified plugin support | ✅ | ✅ |
34+
| Tiny bundle (minzipped) | **~35 kB** | ~45 kB |
35+
| Built-in DOCX-friendly AST output | ✅ | ❌ |
36+
2037
---
2138

22-
## 🚀 Installation
39+
## 📦 Installation
2340

2441
```bash
2542
pnpm add @m2d/react-markdown
@@ -39,10 +56,30 @@ yarn add @m2d/react-markdown
3956

4057
---
4158

42-
## ⚡ Quick Example
59+
## 🚀 Server vs Client
60+
61+
By default, this package is SSR-safe and has **no client-specific hooks**.
62+
63+
### ✅ Server (default):
64+
65+
```tsx
66+
import { Md } from "@m2d/react-markdown";
67+
```
68+
69+
### 🔁 Client (for dynamic reactivity/memoization):
4370

4471
```tsx
45-
import { Md } from "mdx-render";
72+
import { Md } from "@m2d/react-markdown/client";
73+
```
74+
75+
This version supports client-side behavior with memoization and dynamic JSX rendering.
76+
77+
---
78+
79+
## ⚡ Example: Rendering + Exporting DOCX
80+
81+
```tsx
82+
import { Md } from "@m2d/react-markdown/client";
4683
import { toDocx } from "mdast2docx";
4784
import { useRef } from "react";
4885

@@ -55,7 +92,7 @@ export default function Page() {
5592
<button
5693
onClick={() => {
5794
const doc = toDocx(astRef.current[0].mdast);
58-
// Export DOCX, or save
95+
// Save or download doc
5996
}}>
6097
Export to DOCX
6198
</button>
@@ -64,48 +101,50 @@ export default function Page() {
64101
}
65102
```
66103

104+
> Note for Server Component use you can replace useRef with custom ref object `const astRef = {current: undefined} as AstRef`
105+
67106
---
68107

69108
## 🧠 JSX-Aware Parsing
70109

71-
Unlike other libraries, this renderer supports **JSX as children**, which means you can nest Markdown inside arbitrary components:
110+
Unlike most markdown renderers, `@m2d/react-markdown` supports **arbitrary JSX as children**:
72111

73112
```tsx
74113
<Md>
75-
<section>{`# Title\n\nContent.`}</section>
114+
<article>{"# Markdown Heading\n\nSome **rich** content."}</article>
76115
</Md>
77116
```
78117

79-
> Note: `astRef.current` is an array — one entry per Markdown segment.
80-
> Each entry contains `{ mdast, hast }` for fine-grained control.
118+
> `astRef.current` is an array — one per Markdown string — each with `{ mdast, hast }`.
81119
82120
---
83121

84-
## ✨ Component Overrides
85-
86-
Override default HTML rendering with your own components:
122+
## 🎨 Component Overrides
87123

88124
```tsx
125+
import { Md, Unwrap, Omit } from "@m2d/react-markdown";
126+
89127
<Md
90128
components={{
91-
code: (props) => <CodeWithHighlights {...props} />
92-
em: Unwrap, // Renders <em> content without tags
93-
blockquote: Omit, // Removes <blockquote> completely
129+
em: Unwrap,
130+
blockquote: Omit,
131+
code: props => <CodeBlock {...props} />,
94132
}}>
95-
{`*This will be unwrapped*\n\n> This will be removed!`}
96-
</Md>
133+
{`*em is unwrapped*\n\n> blockquote is removed`}
134+
</Md>;
97135
```
98136

99137
Use the built-in helpers:
100138

101-
- `Unwrap` – renders children, ignores tag & props.
102-
- `Omit` – removes the element and its content entirely.
139+
- `Unwrap` – renders only children
140+
- `Omit` – removes element and content entirely
141+
- `CodeBlock` - it is your custom component
103142

104143
---
105144

106-
## 🧩 Plugin Support
145+
## 🔌 Plugin Support (Unified)
107146

108-
Use any `remark` or `rehype` plugins with full flexibility:
147+
Use any `remark` or `rehype` plugin:
109148

110149
```tsx
111150
<Md remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeSlug, rehypeAutolinkHeadings]}>
@@ -115,45 +154,44 @@ Use any `remark` or `rehype` plugins with full flexibility:
115154

116155
---
117156

118-
## 📦 astRef: MDAST + HAST Access
157+
## 📂 Accessing MDAST + HAST
119158

120159
```ts
121160
type astRef = {
122161
current: { mdast: Root; hast: HastRoot }[];
123162
};
124163
```
125164

126-
Each markdown block is processed independently to allow full JSX flexibility.
127-
You can access all parsed trees via `astRef.current`, ideal for:
165+
Useful for:
128166

129-
- DOCX/PDF generation (`mdast2docx`)
130-
- Markdown linting or analytics
131-
- AST-aware transformations
167+
- 📄 DOCX export (`mdast2docx`)
168+
- 🧪 AST testing or analysis
169+
- 🛠️ Custom tree manipulation
132170

133171
---
134172

135173
## 🧭 Roadmap
136174

137-
- [ ] 🔄 Merge surrounding JSX + `<Md>` blocks into unified MDAST/HAST
138-
- [x] 🧪 Add test utilities for structural validation
139-
- [x] 📚 Provide Next.js examples with DOCX export
175+
- [ ] 🔄 Merge JSX + `<Md>` segments into unified AST
176+
- [x] 🧪 Structural test utilities
177+
- [x] 🧑‍🏫 Next.js + DOCX example
140178

141179
---
142180

143-
## 📘 Related Projects
181+
## 🌍 Related Projects
144182

145-
- [mdast2docx](https://github.com/md2docx/mdast2docx) – Convert MDAST to Word (.docx)
146-
- [unifiedjs](https://unifiedjs.com/) – Syntax tree processing toolkit
147-
- [react-markdown](https://github.com/remarkjs/react-markdown) – A simpler but less flexible Markdown renderer
183+
- [`mdast2docx`](https://github.com/md2docx/mdast2docx) – Convert MDAST → `.docx`
184+
- [`unified`](https://unifiedjs.com/) – Syntax tree ecosystem
185+
- [`react-markdown`](https://github.com/remarkjs/react-markdown) – Popular alternative (less customizable)
148186

149187
---
150188

151-
## License
189+
## 📘 License
152190

153-
This library is licensed under the MPL-2.0 open-source license.
191+
Licensed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/).
154192

155-
> <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Please enroll in [our courses](https://mayank-chaudhari.vercel.app/courses) or [sponsor](https://github.com/sponsors/mayank1513) our work.
193+
> 💡 Want to support this project? [Sponsor](https://github.com/sponsors/mayank1513) or check out our [courses](https://mayank-chaudhari.vercel.app/courses)!
156194
157195
---
158196

159-
<p align="center" style="text-align:center">with 💖 by <a href="https://mayank-chaudhari.vercel.app" target="_blank">Mayank Kumar Chaudhari</a></p>
197+
<p align="center" style="text-align:center">Built with ❤️ by <a href="https://mayank-chaudhari.vercel.app" target="_blank">Mayank Kumar Chaudhari</a></p>

0 commit comments

Comments
 (0)