Skip to content

Commit 069492b

Browse files
mayank1513mayank1513
committed
Apply changesets and update CHANGELOG [skip ci]
1 parent bb6a47a commit 069492b

File tree

1 file changed

+97
-70
lines changed

1 file changed

+97
-70
lines changed

‎lib/README.md‎

Lines changed: 97 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,25 @@
1-
# 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

33
[![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/)
44

5-
React Markdown is a comprehensive library designed to unlock the full potential of React 18 server components. It provides customizable loading animation components and a fullscreen loader container, seamlessly integrating with React and Next.js.
5+
> ✨ A modern, JSX-compatible, SSR-ready Markdown renderer for React — with full access to MDAST & HAST trees for tools like `mdast2docx`.
66
7-
✅ Fully Treeshakable (import from `@m2d/react-markdown/client/loader-container`)
7+
---
88

9-
✅ Fully TypeScript Supported
9+
## 🔥 Why mdx-render?
1010

11-
✅ Leverages the power of React 18 Server components
11+
`mdx-render` goes beyond traditional React Markdown libraries by focusing on:
1212

13-
✅ Compatible with all React 18 build systems/tools/frameworks
13+
- ✅ **Server-side rendering (SSR)** without hooks
14+
- ✅ **Full JSX children support** (not just strings)
15+
- ✅ **Access to raw MDAST & HAST trees**
16+
- ✅ **Drop-in plugin support** via Unified (`remark`, `rehype`, etc.)
17+
- ✅ **Custom component overrides** per tag
18+
- ✅ **Integration with tools like [`mdast2docx`](https://github.com/md2docx/mdast2docx)**
1419

15-
✅ Documented with [Typedoc](https://md2docx.github.io/react-markdown) ([Docs](https://md2docx.github.io/react-markdown))
20+
---
1621

17-
✅ Examples for Next.js, and Vite
18-
19-
> <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Star [this repository](https://github.com/md2docx/react-markdown) and share it with your friends.
20-
21-
## Getting Started
22-
23-
### Installation
22+
## 🚀 Installation
2423

2524
```bash
2625
pnpm add @m2d/react-markdown
@@ -38,95 +37,123 @@ npm install @m2d/react-markdown
3837
yarn add @m2d/react-markdown
3938
```
4039

41-
## Want Lite Version? [![npm bundle size](https://img.shields.io/bundlephobia/minzip/@m2d/react-markdown-lite)](https://www.npmjs.com/package/@m2d/react-markdown-lite) [![Version](https://img.shields.io/npm/v/@m2d/react-markdown-lite.svg?colorB=green)](https://www.npmjs.com/package/@m2d/react-markdown-lite) [![Downloads](https://img.jsdelivr.com/img.shields.io/npm/d18m/@m2d/react-markdown-lite.svg)](https://www.npmjs.com/package/@m2d/react-markdown-lite)
40+
---
4241

43-
```bash
44-
pnpm add @m2d/react-markdown-lite
42+
## ⚡ Quick Example
43+
44+
```tsx
45+
import { Md } from "mdx-render";
46+
import { toDocx } from "mdast2docx";
47+
import { useRef } from "react";
48+
49+
const astRef = useRef([]);
50+
51+
export default function Page() {
52+
return (
53+
<>
54+
<Md astRef={astRef}>{`# Hello\n\nThis is **Markdown**.`}</Md>
55+
<button
56+
onClick={() => {
57+
const doc = toDocx(astRef.current[0].mdast);
58+
// Export DOCX, or save
59+
}}>
60+
Export to DOCX
61+
</button>
62+
</>
63+
);
64+
}
4565
```
4666

47-
**or**
67+
---
4868

49-
```bash
50-
npm install @m2d/react-markdown-lite
51-
```
69+
## 🧠 JSX-Aware Parsing
5270

53-
**or**
71+
Unlike other libraries, this renderer supports **JSX as children**, which means you can nest Markdown inside arbitrary components:
5472

55-
```bash
56-
yarn add @m2d/react-markdown-lite
73+
```tsx
74+
<Md>
75+
<section>{`# Title\n\nContent.`}</section>
76+
</Md>
5777
```
5878

59-
> You need `r18gs` as a peer-dependency
79+
> Note: `astRef.current` is an array — one entry per Markdown segment.
80+
> Each entry contains `{ mdast, hast }` for fine-grained control.
6081
61-
### Import Styles
82+
---
6283

63-
You can import styles globally or within specific components.
84+
## ✨ Component Overrides
6485

65-
```css
66-
/* globals.css */
67-
@import "@m2d/react-markdown/dist";
68-
```
86+
Override default HTML rendering with your own components:
6987

7088
```tsx
71-
// layout.tsx
72-
import "@m2d/react-markdown/dist/index.css";
89+
<Md
90+
components={{
91+
code: (props) => <CodeWithHighlights {...props} />
92+
em: Unwrap, // Renders <em> content without tags
93+
blockquote: Omit, // Removes <blockquote> completely
94+
}}>
95+
{`*This will be unwrapped*\n\n> This will be removed!`}
96+
</Md>
7397
```
7498

75-
For selective imports:
99+
Use the built-in helpers:
76100

77-
```css
78-
/* globals.css */
79-
@import "@m2d/react-markdown/dist/client"; /** required if you are using LoaderContainer */
80-
@import "@m2d/react-markdown/dist/server/bars/bars1";
81-
```
101+
- `Unwrap` – renders children, ignores tag & props.
102+
- `Omit` – removes the element and its content entirely.
103+
104+
---
82105

83-
### Usage
106+
## 🧩 Plugin Support
84107

85-
Using loaders is straightforward.
108+
Use any `remark` or `rehype` plugins with full flexibility:
86109

87110
```tsx
88-
import { Bars1 } from "@m2d/react-markdown/dist/server/bars/bars1";
111+
<Md remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeSlug, rehypeAutolinkHeadings]}>
112+
{markdown}
113+
</Md>
114+
```
89115

90-
export default function MyComponent() {
91-
return someCondition ? <Bars1 /> : <>Something else...</>;
92-
}
116+
---
117+
118+
## 📦 astRef: MDAST + HAST Access
119+
120+
```ts
121+
type astRef = {
122+
current: { mdast: Root; hast: HastRoot }[];
123+
};
93124
```
94125

95-
For detailed API and options, refer to [the API documentation](https://md2docx.github.io/react-markdown).
126+
Each markdown block is processed independently to allow full JSX flexibility.
127+
You can access all parsed trees via `astRef.current`, ideal for:
96128

97-
**Using LoaderContainer**
129+
- DOCX/PDF generation (`mdast2docx`)
130+
- Markdown linting or analytics
131+
- AST-aware transformations
98132

99-
`LoaderContainer` is a fullscreen component. You can add this component directly in your layout and then use `useLoader` hook to toggle its visibility.
133+
---
100134

101-
```tsx
102-
// layout.tsx
103-
<LoaderContainer />
104-
...
105-
```
135+
## 🧭 Roadmap
106136

107-
```tsx
108-
// some other page or component
109-
import { useLoader } from "@m2d/react-markdown/dist/hooks";
110-
111-
export default MyComponent() {
112-
const { setLoading } = useLoader();
113-
useCallback(()=>{
114-
setLoading(true);
115-
...do some work
116-
setLoading(false);
117-
}, [])
118-
...
119-
}
120-
```
137+
- [ ] 🔄 Merge surrounding JSX + `<Md>` blocks into unified MDAST/HAST
138+
- [ ] 🧪 Add test utilities for structural validation
139+
- [x] 📚 Provide Next.js examples with DOCX export
121140

122-
## License
141+
---
123142

124-
This library is licensed under the MPL-2.0 open-source license.
143+
## 📘 Related Projects
144+
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
125148

149+
---
126150

151+
## License
152+
153+
This library is licensed under the MPL-2.0 open-source license.
127154

128155
> <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.
129156
130-
<hr />
157+
---
131158

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

0 commit comments

Comments
 (0)