SVG `<circle>` element

a
b

a
b

a
b

├── .editorconfig ├── .github └── workflows │ ├── bb.yml │ └── main.yml ├── .gitignore ├── .npmrc ├── .prettierignore ├── changelog.md ├── index.js ├── lib └── index.js ├── license ├── package.json ├── readme.md ├── script └── load-jsx.js ├── test.jsx └── tsconfig.json /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | charset = utf-8 5 | end_of_line = lf 6 | indent_size = 2 7 | indent_style = space 8 | insert_final_newline = true 9 | trim_trailing_whitespace = true 10 | -------------------------------------------------------------------------------- /.github/workflows/bb.yml: -------------------------------------------------------------------------------- 1 | jobs: 2 | main: 3 | runs-on: ubuntu-latest 4 | steps: 5 | - uses: unifiedjs/beep-boop-beta@main 6 | with: 7 | repo-token: ${{secrets.GITHUB_TOKEN}} 8 | name: bb 9 | on: 10 | issues: 11 | types: [closed, edited, labeled, opened, reopened, unlabeled] 12 | pull_request_target: 13 | types: [closed, edited, labeled, opened, reopened, unlabeled] 14 | -------------------------------------------------------------------------------- /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | jobs: 2 | main: 3 | name: ${{matrix.node}} 4 | runs-on: ubuntu-latest 5 | steps: 6 | - uses: actions/checkout@v4 7 | - uses: actions/setup-node@v4 8 | with: 9 | node-version: ${{matrix.node}} 10 | - run: npm install 11 | - run: npm test 12 | - uses: codecov/codecov-action@v5 13 | strategy: 14 | matrix: 15 | node: 16 | - lts/hydrogen 17 | - node 18 | name: main 19 | on: 20 | - pull_request 21 | - push 22 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.d.ts 2 | *.log 3 | *.map 4 | *.tsbuildinfo 5 | .DS_Store 6 | coverage/ 7 | node_modules/ 8 | react-markdown.min.js 9 | yarn.lock 10 | -------------------------------------------------------------------------------- /.npmrc: -------------------------------------------------------------------------------- 1 | ignore-scripts=true 2 | package-lock=false 3 | -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | coverage/ 2 | *.md 3 | -------------------------------------------------------------------------------- /changelog.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Changelog 4 | 5 | All notable changes will be documented in this file. 6 | 7 | ## 10.0.0 - 2025-02-20 8 | 9 | * [`aaaa40b`](https://github.com/remarkjs/react-markdown/commit/aaaa40b) 10 | Remove support for `className` prop 11 | **migrate**: see “Remove `className`” below 12 | 13 | ### Remove `className` 14 | 15 | The `className` prop was removed. 16 | If you want to add classes to some element that wraps the markdown 17 | you can explicitly write that element and add the class to it. 18 | You can then choose yourself which tag name to use and whether to add other 19 | props. 20 | 21 | Before: 22 | 23 | ```js 24 | {markdown} 25 | ``` 26 | 27 | After: 28 | 29 | ```js 30 |

31 | {markdown} 32 |

118 |

Show example of plugin

119 | 120 | ```js 121 | import {visit} from 'unist-util-visit' 122 | 123 | function rehypePluginAddingIndex() { 124 | /** 125 | * @param {import('hast').Root} tree 126 | * @returns {undefined} 127 | */ 128 | return function (tree) { 129 | visit(tree, function (node, index) { 130 | if (node.type === 'element' && typeof index === 'number') { 131 | node.properties.index = index 132 | } 133 | }) 134 | } 135 | } 136 | ``` 137 | 138 |

139 | 140 | ### Remove `rawSourcePos` 141 | 142 | The `rawSourcePos` option was removed, so `sourcePos` is never passed to 143 | components. 144 | All components are passed `node`, so you can get `node.position` from them. 145 | 146 | ### Remove `sourcePos` 147 | 148 | The `sourcePos` option was removed, so `data-sourcepos` is never passed to 149 | elements. 150 | Write a plugin to pass `index`: 151 | 152 |

153 |

Show example of plugin

154 | 155 | ```js 156 | import {stringifyPosition} from 'unist-util-stringify-position' 157 | import {visit} from 'unist-util-visit' 158 | 159 | function rehypePluginAddingIndex() { 160 | /** 161 | * @param {import('hast').Root} tree 162 | * @returns {undefined} 163 | */ 164 | return function (tree) { 165 | visit(tree, function (node) { 166 | if (node.type === 'element') { 167 | node.properties.dataSourcepos = stringifyPosition(node.position) 168 | } 169 | }) 170 | } 171 | } 172 | ``` 173 | 174 |

385 |

Show example of needed change

386 | 387 | Before (**broken**): 388 | 389 | ```js 390 | 394 | }} 395 | >{`***`} 396 | ``` 397 | 398 | Now (**fixed**): 399 | 400 | ```js 401 | 405 | }} 406 | >{`***`} 407 | ``` 408 | 409 |

410 | 411 |

412 |

Show conversion table

413 | 414 | | Type (`renderers`) | Tag names (`components`) | 415 | | ----------------------------------- | --------------------------------------- | 416 | | `blockquote` | `blockquote` | 417 | | `break` | `br` | 418 | | `code`, `inlineCode` | `code`, `pre`**\*** | 419 | | `definition` | **†** | 420 | | `delete` | `del`**‡** | 421 | | `emphasis` | `em` | 422 | | `heading` | `h1`, `h2`, `h3`, `h4`, `h5`, `h6`**§** | 423 | | `html`, `parsedHtml`, `virtualHtml` | **‖** | 424 | | `image`, `imageReference` | `img`**†** | 425 | | `link`, `linkReference` | `a`**†** | 426 | | `list` | `ol`, `ul`**¶** | 427 | | `listItem` | `li` | 428 | | `paragraph` | `p` | 429 | | `root` | **\*\*** | 430 | | `strong` | `strong` | 431 | | `table` | `table`**‡** | 432 | | `tableHead` | `thead`**‡** | 433 | | `tableBody` | `tbody`**‡** | 434 | | `tableRow` | `tr`**‡** | 435 | | `tableCell` | `td`, `th`**‡** | 436 | | `text` | | 437 | | `thematicBreak` | `hr` | 438 | 439 | * **\*** It’s possible to differentiate between code based on the `inline` 440 | prop. 441 | Block code is also wrapped in a `pre` 442 | * **†** Resource (`[text](url)`) and reference (`[text][id]`) style links and 443 | images (and their definitions) are now resolved and treated the same 444 | * **‡** Available when using 445 | [`remark-gfm`](https://github.com/remarkjs/remark-gfm) 446 | * **§** It’s possible to differentiate between heading based on the `level` 447 | prop 448 | * **‖** When using `rehype-raw` (see below), components for those elements 449 | can also be used (for example, `abbr` for 450 | `HTML`) 451 | * **¶** It’s possible to differentiate between lists based on the `ordered` 452 | prop 453 | * **\*\*** Wrap `ReactMarkdown` in a component instead 454 | 455 |

476 |

Show example of feature

477 | 478 | ```js 479 | import rehypeHighlight from 'rehype-highlight' 480 | 481 | {`~~~js 482 | console.log(1) 483 | ~~~`} 484 | ``` 485 | 486 |

506 |

Show example of needed change

507 | 508 | Before (**broken**): 509 | 510 | ```js 511 | import MarkdownWithHtml from 'react-markdown/with-html' 512 | 513 | {`# Hello, world!`} 514 | ``` 515 | 516 | Now (**fixed**): 517 | 518 | ```js 519 | import Markdown from 'react-markdown' 520 | import rehypeRaw from 'rehype-raw' 521 | import rehypeSanitize from 'rehype-sanitize' 522 | 523 | {`# Hello, world!`} 524 | ``` 525 | 526 |

527 | 528 | ### Change `source` to `children` 529 | 530 | Instead of passing a `source` pass `children` instead: 531 | 532 |

533 |

Show example of needed change

534 | 535 | Before (**broken**): 536 | 537 | ```js 538 | 539 | ``` 540 | 541 | Now (**fixed**): 542 | 543 | ```js 544 | {`some 545 | markdown`} 546 | ``` 547 | 548 | Or (**also fixed**): 549 | 550 | ```js 551 | 553 | ``` 554 | 555 |

556 | 557 | ### Replace `allowNode`, `allowedTypes`, and `disallowedTypes` 558 | 559 | Similar to the `renderers` to `components` change, the filtering options 560 | also changed from being based on markdown names towards being based on HTML 561 | names: `allowNode` to `allowElement`, `allowedTypes` to `allowedElements`, and 562 | `disallowedTypes` to `disallowedElements`. 563 | 564 |

565 |

Show example of needed change

566 | 567 | Before (**broken**): 568 | 569 | ```js 570 | {`![alt text](./image.url)`} 574 | ``` 575 | 576 | Now (**fixed**): 577 | 578 | ```js 579 | {`![alt text](./image.url)`} 583 | ``` 584 | 585 | *** 586 | 587 | Before (**broken**): 588 | 589 | ```js 590 | node.type !== 'heading' || node.depth !== 1} 593 | >{`# main heading`} 594 | ``` 595 | 596 | Now (**fixed**): 597 | 598 | ```js 599 | element.tagName !== 'h1'} 602 | >{`# main heading`} 603 | ``` 604 | 605 |

606 | 607 | ### Change `includeNodeIndex` to `includeElementIndex` 608 | 609 | Similar to the `renderers` to `components` change, this option to pass more info 610 | to components also changed from being based on markdown to being based on HTML. 611 | 612 |

613 |

Show example of needed change

614 | 615 | Before (**broken**): 616 | 617 | ```js 618 | 622 | }} 623 | >{`Some text`} 624 | ``` 625 | 626 | Now (**fixed**): 627 | 628 | ```js 629 | 633 | }} 634 | >{`Some text`} 635 | ``` 636 | 637 |

` for `## hi`) 22 | * [x] [plugins][section-plugins] 23 | (many plugins you can pick and choose from) 24 | * [x] [compliant][section-syntax] 25 | (100% to CommonMark, 100% to GFM with a plugin) 26 | 27 | ## Contents 28 | 29 | * [What is this?](#what-is-this) 30 | * [When should I use this?](#when-should-i-use-this) 31 | * [Install](#install) 32 | * [Use](#use) 33 | * [API](#api) 34 | * [`Markdown`](#markdown) 35 | * [`MarkdownAsync`](#markdownasync) 36 | * [`MarkdownHooks`](#markdownhooks) 37 | * [`defaultUrlTransform(url)`](#defaulturltransformurl) 38 | * [`AllowElement`](#allowelement) 39 | * [`Components`](#components) 40 | * [`ExtraProps`](#extraprops) 41 | * [`HooksOptions`](#hooksoptions) 42 | * [`Options`](#options) 43 | * [`UrlTransform`](#urltransform) 44 | * [Examples](#examples) 45 | * [Use a plugin](#use-a-plugin) 46 | * [Use a plugin with options](#use-a-plugin-with-options) 47 | * [Use custom components (syntax highlight)](#use-custom-components-syntax-highlight) 48 | * [Use remark and rehype plugins (math)](#use-remark-and-rehype-plugins-math) 49 | * [Plugins](#plugins) 50 | * [Syntax](#syntax) 51 | * [Compatibility](#compatibility) 52 | * [Architecture](#architecture) 53 | * [Appendix A: HTML in markdown](#appendix-a-html-in-markdown) 54 | * [Appendix B: Components](#appendix-b-components) 55 | * [Appendix C: line endings in markdown (and JSX)](#appendix-c-line-endings-in-markdown-and-jsx) 56 | * [Security](#security) 57 | * [Related](#related) 58 | * [Contribute](#contribute) 59 | * [License](#license) 60 | 61 | ## What is this? 62 | 63 | This package is a [React][] component that can be given a string of markdown 64 | that it’ll safely render to React elements. 65 | You can pass plugins to change how markdown is transformed and pass components 66 | that will be used instead of normal HTML elements. 67 | 68 | * to learn markdown, see this [cheatsheet and tutorial][commonmark-help] 69 | * to try out `react-markdown`, see [our demo][github-io-react-markdown] 70 | 71 | ## When should I use this? 72 | 73 | There are other ways to use markdown in React out there so why use this one? 74 | The three main reasons are that they often rely on `dangerouslySetInnerHTML`, 75 | have bugs with how they handle markdown, or don’t let you swap elements for 76 | components. 77 | `react-markdown` builds a virtual DOM, so React only replaces what changed, 78 | from a syntax tree. 79 | That’s supported because we use [unified][github-unified], 80 | specifically [remark][github-remark] for markdown and [rehype][github-rehype] 81 | for HTML, 82 | which are popular tools to transform content with plugins. 83 | 84 | This package focusses on making it easy for beginners to safely use markdown in 85 | React. 86 | When you’re familiar with unified, you can use a modern hooks based alternative 87 | [`react-remark`][github-react-remark] or [`rehype-react`][github-rehype-react] 88 | manually. 89 | If you instead want to use JavaScript and JSX inside markdown files, use 90 | [MDX][github-mdx]. 91 | 92 | ## Install 93 | 94 | This package is [ESM only][esm]. 95 | In Node.js (version 16+), install with [npm][npm-install]: 96 | 97 | ```sh 98 | npm install react-markdown 99 | ``` 100 | 101 | In Deno with [`esm.sh`][esmsh]: 102 | 103 | ```js 104 | import Markdown from 'https://esm.sh/react-markdown@10' 105 | ``` 106 | 107 | In browsers with [`esm.sh`][esmsh]: 108 | 109 | ```html 110 | 113 | ``` 114 | 115 | ## Use 116 | 117 | A basic hello world: 118 | 119 | ```js 120 | import React from 'react' 121 | import {createRoot} from 'react-dom/client' 122 | import Markdown from 'react-markdown' 123 | 124 | const markdown = '# Hi, Pluto!' 125 | 126 | createRoot(document.body).render({markdown}) 127 | ``` 128 | 129 |
130 |
Show equivalent JSX
131 | 132 | ```js 133 |
134 | Hi, Pluto! 135 |
136 | ``` 137 | 138 |
139 | 140 | Here is an example that shows how to use a plugin 141 | ([`remark-gfm`][github-remark-gfm], 142 | which adds support for footnotes, strikethrough, tables, tasklists and 143 | URLs directly): 144 | 145 | ```js 146 | import React from 'react' 147 | import {createRoot} from 'react-dom/client' 148 | import Markdown from 'react-markdown' 149 | import remarkGfm from 'remark-gfm' 150 | 151 | const markdown = `Just a link: www.nasa.gov.` 152 | 153 | createRoot(document.body).render( 154 | {markdown} 155 | ) 156 | ``` 157 | 158 |
159 |
Show equivalent JSX
160 | 161 | ```js 162 |
163 | Just a link: www.nasa.gov. 164 |
165 | ``` 166 | 167 |
168 | 169 | ## API 170 | 171 | This package exports the identifiers 172 | [`MarkdownAsync`][api-markdown-async], 173 | [`MarkdownHooks`][api-markdown-hooks], 174 | and 175 | [`defaultUrlTransform`][api-default-url-transform]. 176 | The default export is [`Markdown`][api-markdown]. 177 | 178 | It also exports the additional [TypeScript][] types 179 | [`AllowElement`][api-allow-element], 180 | [`Components`][api-components], 181 | [`ExtraProps`][api-extra-props], 182 | [`HooksOptions`][api-hooks-options], 183 | [`Options`][api-options], 184 | and 185 | [`UrlTransform`][api-url-transform]. 186 | 187 | ### `Markdown` 188 | 189 | Component to render markdown. 190 | 191 | This is a synchronous component. 192 | When using async plugins, 193 | see [`MarkdownAsync`][api-markdown-async] or 194 | [`MarkdownHooks`][api-markdown-hooks]. 195 | 196 | ###### Parameters 197 | 198 | * `options` ([`Options`][api-options]) 199 | — props 200 | 201 | ###### Returns 202 | 203 | React element (`ReactElement`). 204 | 205 | ### `MarkdownAsync` 206 | 207 | Component to render markdown with support for async plugins 208 | through async/await. 209 | 210 | Components returning promises are supported on the server. 211 | For async support on the client, 212 | see [`MarkdownHooks`][api-markdown-hooks]. 213 | 214 | ###### Parameters 215 | 216 | * `options` ([`Options`][api-options]) 217 | — props 218 | 219 | ###### Returns 220 | 221 | Promise to a React element (`Promise`). 222 | 223 | ### `MarkdownHooks` 224 | 225 | Component to render markdown with support for async plugins through hooks. 226 | 227 | This uses `useEffect` and `useState` hooks. 228 | Hooks run on the client and do not immediately render something. 229 | For async support on the server, 230 | see [`MarkdownAsync`][api-markdown-async]. 231 | 232 | ###### Parameters 233 | 234 | * `options` ([`Options`][api-options]) 235 | — props 236 | 237 | ###### Returns 238 | 239 | React node (`ReactNode`). 240 | 241 | ### `defaultUrlTransform(url)` 242 | 243 | Make a URL safe. 244 | 245 | This follows how GitHub works. 246 | It allows the protocols `http`, `https`, `irc`, `ircs`, `mailto`, and `xmpp`, 247 | and URLs relative to the current protocol (such as `/something`). 248 | 249 | ###### Parameters 250 | 251 | * `url` (`string`) 252 | — URL 253 | 254 | ###### Returns 255 | 256 | Safe URL (`string`). 257 | 258 | ### `AllowElement` 259 | 260 | Filter elements (TypeScript type). 261 | 262 | ###### Parameters 263 | 264 | * `node` ([`Element` from `hast`][github-hast-element]) 265 | — element to check 266 | * `index` (`number | undefined`) 267 | — index of `element` in `parent` 268 | * `parent` ([`Node` from `hast`][github-hast-nodes]) 269 | — parent of `element` 270 | 271 | ###### Returns 272 | 273 | Whether to allow `element` (`boolean`, optional). 274 | 275 | ### `Components` 276 | 277 | Map tag names to components (TypeScript type). 278 | 279 | ###### Type 280 | 281 | ```ts 282 | import type {ExtraProps} from 'react-markdown' 283 | import type {ComponentProps, ElementType} from 'react' 284 | 285 | type Components = { 286 | [Key in Extract]?: ElementType & ExtraProps> 287 | } 288 | ``` 289 | 290 | ### `ExtraProps` 291 | 292 | Extra fields we pass to components (TypeScript type). 293 | 294 | ###### Fields 295 | 296 | * `node` ([`Element` from `hast`][github-hast-element], optional) 297 | — original node 298 | 299 | ### `HooksOptions` 300 | 301 | Configuration for [`MarkdownHooks`][api-markdown-hooks] (TypeScript type); 302 | extends the regular [`Options`][api-options] with a `fallback` prop. 303 | 304 | ###### Extends 305 | 306 | [`Options`][api-options]. 307 | 308 | ###### Fields 309 | 310 | * `fallback` (`ReactNode`, optional) 311 | — content to render while the processor processing the markdown 312 | 313 | ### `Options` 314 | 315 | Configuration (TypeScript type). 316 | 317 | ###### Fields 318 | 319 | * `allowElement` ([`AllowElement`][api-allow-element], optional) 320 | — filter elements; 321 | `allowedElements` / `disallowedElements` is used first 322 | * `allowedElements` (`Array`, default: all tag names) 323 | — tag names to allow; 324 | cannot combine w/ `disallowedElements` 325 | * `children` (`string`, optional) 326 | — markdown 327 | * `components` ([`Components`][api-components], optional) 328 | — map tag names to components 329 | * `disallowedElements` (`Array`, default: `[]`) 330 | — tag names to disallow; 331 | cannot combine w/ `allowedElements` 332 | * `rehypePlugins` (`Array`, optional) 333 | — list of [rehype plugins][github-rehype-plugins] to use 334 | * `remarkPlugins` (`Array`, optional) 335 | — list of [remark plugins][github-remark-plugins] to use 336 | * `remarkRehypeOptions` 337 | ([`Options` from `remark-rehype`][github-remark-rehype-options], 338 | optional) 339 | — options to pass through to `remark-rehype` 340 | * `skipHtml` (`boolean`, default: `false`) 341 | — ignore HTML in markdown completely 342 | * `unwrapDisallowed` (`boolean`, default: `false`) 343 | — extract (unwrap) what’s in disallowed elements; 344 | normally when say `strong` is not allowed, it and it’s children are dropped, 345 | with `unwrapDisallowed` the element itself is replaced by its children 346 | * `urlTransform` ([`UrlTransform`][api-url-transform], default: 347 | [`defaultUrlTransform`][api-default-url-transform]) 348 | — change URLs 349 | 350 | ### `UrlTransform` 351 | 352 | Transform URLs (TypeScript type). 353 | 354 | ###### Parameters 355 | 356 | * `url` (`string`) 357 | — URL 358 | * `key` (`string`, example: `'href'`) 359 | — property name 360 | * `node` ([`Element` from `hast`][github-hast-element]) 361 | — element to check 362 | 363 | ###### Returns 364 | 365 | Transformed URL (`string`, optional). 366 | 367 | ## Examples 368 | 369 | ### Use a plugin 370 | 371 | This example shows how to use a remark plugin. 372 | In this case, [`remark-gfm`][github-remark-gfm], 373 | which adds support for strikethrough, tables, tasklists and URLs directly: 374 | 375 | ```js 376 | import React from 'react' 377 | import {createRoot} from 'react-dom/client' 378 | import Markdown from 'react-markdown' 379 | import remarkGfm from 'remark-gfm' 380 | 381 | const markdown = `A paragraph with emphasis and strong importance. 382 | 383 | > A block quote with ~strikethrough~ and a URL: https://reactjs.org. 384 | 385 | * Lists 386 | * [ ] todo 387 | * [x] done 388 | 389 | A table: 390 | 391 | | a | b | 392 | | - | - | 393 | ` 394 | 395 | createRoot(document.body).render( 396 | {markdown} 397 | ) 398 | ``` 399 | 400 |
401 |
Show equivalent JSX
402 | 403 | ```js 404 | <> 405 |
406 | A paragraph with emphasis and strong importance. 407 |
408 |
409 |
410 | A block quote with strikethrough and a URL:{' '} 411 | https://reactjs.org. 412 |
413 |
414 |
415 |
Lists
416 |
417 | todo 418 |
419 |
420 | done 421 |
422 |
423 |
A table:
424 | 425 | 426 | 427 | 428 | 429 | 430 | 431 |
a b
432 | 433 | ``` 434 | 435 |
436 | 437 | ### Use a plugin with options 438 | 439 | This example shows how to use a plugin and give it options. 440 | To do that, use an array with the plugin at the first place, and the options 441 | second. 442 | [`remark-gfm`][github-remark-gfm] has an option to allow only double tildes for 443 | strikethrough: 444 | 445 | ```js 446 | import React from 'react' 447 | import {createRoot} from 'react-dom/client' 448 | import Markdown from 'react-markdown' 449 | import remarkGfm from 'remark-gfm' 450 | 451 | const markdown = 'This ~is not~ strikethrough, but this is!' 452 | 453 | createRoot(document.body).render( 454 | 455 | {markdown} 456 | 457 | ) 458 | ``` 459 | 460 |
461 |
Show equivalent JSX
462 | 463 | ```js 464 |
465 | This ~is not~ strikethrough, but this is! 466 |
467 | ``` 468 | 469 |
470 | 471 | ### Use custom components (syntax highlight) 472 | 473 | This example shows how you can overwrite the normal handling of an element by 474 | passing a component. 475 | In this case, we apply syntax highlighting with the seriously super amazing 476 | [`react-syntax-highlighter`][github-react-syntax-highlighter] by 477 | [@conorhastings][github-conorhastings]: 478 | 479 | 480 | 481 | ```js 482 | import React from 'react' 483 | import {createRoot} from 'react-dom/client' 484 | import Markdown from 'react-markdown' 485 | import {Prism as SyntaxHighlighter} from 'react-syntax-highlighter' 486 | import {dark} from 'react-syntax-highlighter/dist/esm/styles/prism' 487 | 488 | // Did you know you can use tildes instead of backticks for code in markdown? ✨ 489 | const markdown = `Here is some JavaScript code: 490 | 491 | ~js 492 | console.log('It works!') 493 | ~ 494 | ` 495 | 496 | createRoot(document.body).render( 497 | 511 | ) : ( 512 | `513 | {children} 514 |` 515 | ) 516 | } 517 | }} 518 | /> 519 | ) 520 | ``` 521 | 522 |
523 |
Show equivalent JSX
524 | 525 | ```js 526 | <> 527 |
Here is some JavaScript code:
528 |
529 | 530 |
531 | 532 | ``` 533 | 534 |
535 | 536 | ### Use remark and rehype plugins (math) 537 | 538 | This example shows how a syntax extension 539 | (through [`remark-math`][github-remark-math]) 540 | is used to support math in markdown, and a transform plugin 541 | ([`rehype-katex`][github-rehype-katex]) to render that math. 542 | 543 | ```js 544 | import React from 'react' 545 | import {createRoot} from 'react-dom/client' 546 | import Markdown from 'react-markdown' 547 | import rehypeKatex from 'rehype-katex' 548 | import remarkMath from 'remark-math' 549 | import 'katex/dist/katex.min.css' // `rehype-katex` does not import the CSS for you 550 | 551 | const markdown = `The lift coefficient ($C_L$) is a dimensionless coefficient.` 552 | 553 | createRoot(document.body).render( 554 | 555 | {markdown} 556 | 557 | ) 558 | ``` 559 | 560 |
561 |
Show equivalent JSX
562 | 563 | ```js 564 |
565 | The lift coefficient ( 566 | 567 | 568 | ${/* … /}$ 569 | 570 | 573 | 574 | ) is a dimensionless coefficient. 575 |
576 | ``` 577 | 578 |
579 | 580 | ## Plugins 581 | 582 | We use [unified][github-unified], 583 | specifically [remark][github-remark] for markdown and 584 | [rehype][github-rehype] for HTML, 585 | which are tools to transform content with plugins. 586 | Here are three good ways to find plugins: 587 | 588 | [`awesome-remark`][github-awesome-remark] and 589 | [`awesome-rehype`][github-awesome-rehype] 590 | — selection of the most awesome projects 591 | * [List of remark plugins][github-remark-plugins] and 592 | [list of rehype plugins][github-rehype-plugins] 593 | — list of all plugins 594 | * [`remark-plugin`][github-topic-remark-plugin] and 595 | [`rehype-plugin`][github-topic-rehype-plugin] topics 596 | — any tagged repo on GitHub 597 | 598 | ## Syntax 599 | 600 | `react-markdown` follows CommonMark, which standardizes the differences between 601 | markdown implementations, by default. 602 | Some syntax extensions are supported through plugins. 603 | 604 | We use [`micromark`][github-micromark] under the hood for our parsing. 605 | See its documentation for more information on markdown, CommonMark, and 606 | extensions. 607 | 608 | ## Compatibility 609 | 610 | Projects maintained by the unified collective are compatible with maintained 611 | versions of Node.js. 612 | 613 | When we cut a new major release, we drop support for unmaintained versions of 614 | Node. 615 | This means we try to keep the current release line, `react-markdown@10`, 616 | compatible with Node.js 16. 617 | 618 | They work in all modern browsers (essentially: everything not IE 11). 619 | You can use a bundler (such as esbuild, webpack, or Rollup) to use this package 620 | in your project, and use its options (or plugins) to add support for legacy 621 | browsers. 622 | 623 | ## Architecture 624 | 625 |
react-markdown 626 | +----------------------------------------------------------------------------------------------------------------+ 627 | | | 628 | | +----------+ +----------------+ +---------------+ +----------------+ +------------+ | 629 | | | | | | | | | | | | | 630 | markdown-+->+ remark +-mdast->+ remark plugins +-mdast->+ remark-rehype +-hast->+ rehype plugins +-hast->+ components +-+->react elements 631 | | | | | | | | | | | | | 632 | | +----------+ +----------------+ +---------------+ +----------------+ +------------+ | 633 | | | 634 | +----------------------------------------------------------------------------------------------------------------+ 635 |
636 | 637 | To understand what this project does, it’s important to first understand what 638 | unified does: please read through the [`unifiedjs/unified`][github-unified] 639 | readme 640 | (the part until you hit the API section is required reading). 641 | 642 | `react-markdown` is a unified pipeline — wrapped so that most folks don’t need 643 | to directly interact with unified. 644 | The processor goes through these steps: 645 | 646 | * parse markdown to mdast (markdown syntax tree) 647 | * transform through remark (markdown ecosystem) 648 | * transform mdast to hast (HTML syntax tree) 649 | * transform through rehype (HTML ecosystem) 650 | * render hast to React with components 651 | 652 | ## Appendix A: HTML in markdown 653 | 654 | `react-markdown` typically escapes HTML (or ignores it, with `skipHtml`) 655 | because it is dangerous and defeats the purpose of this library. 656 | 657 | However, if you are in a trusted environment (you trust the markdown), and 658 | can spare the bundle size (±60kb minzipped), then you can use 659 | [`rehype-raw`][github-rehype-raw]: 660 | 661 | ```js 662 | import React from 'react' 663 | import {createRoot} from 'react-dom/client' 664 | import Markdown from 'react-markdown' 665 | import rehypeRaw from 'rehype-raw' 666 | 667 | const markdown = `
668 | 669 | Some emphasis and strong! 670 | 671 |
` 672 | 673 | createRoot(document.body).render( 674 | {markdown} 675 | ) 676 | ``` 677 | 678 |
679 |
Show equivalent JSX
680 | 681 | ```js 682 |
683 |
684 | Some emphasis and strong! 685 |
686 |
687 | ``` 688 | 689 |
690 | 691 | Note: HTML in markdown is still bound by how [HTML works in 692 | CommonMark][commonmark-html]. 693 | Make sure to use blank lines around block-level HTML that again contains 694 | markdown! 695 | 696 | ## Appendix B: Components 697 | 698 | You can also change the things that come from markdown: 699 | 700 | ```js 701 | 709 | } 710 | }} 711 | /> 712 | ``` 713 | 714 | The keys in components are HTML equivalents for the things you write with 715 | markdown (such as `h1` for `# heading`). 716 | Normally, in markdown, those are: `a`, `blockquote`, `br`, `code`, `em`, `h1`, 717 | `h2`, `h3`, `h4`, `h5`, `h6`, `hr`, `img`, `li`, `ol`, `p`, `pre`, `strong`, and 718 | `ul`. 719 | With [`remark-gfm`][github-remark-gfm], 720 | you can also use `del`, `input`, `table`, `tbody`, `td`, `th`, `thead`, and `tr`. 721 | Other remark or rehype plugins that add support for new constructs will also 722 | work with `react-markdown`. 723 | 724 | The props that are passed are what you probably would expect: an `a` (link) will 725 | get `href` (and `title`) props, and `img` (image) an `src`, `alt` and `title`, 726 | etc. 727 | 728 | Every component will receive a `node`. 729 | This is the original [`Element` from `hast`][github-hast-element] element being 730 | turned into a React element. 731 | 732 | ## Appendix C: line endings in markdown (and JSX) 733 | 734 | You might have trouble with how line endings work in markdown and JSX. 735 | We recommend the following, which solves all line ending problems: 736 | 737 | ```js 738 | // If you write actual markdown in your code, put your markdown in a variable; 739 | // do not indent markdown: 740 | const markdown = ` 741 | # This is perfect! 742 | ` 743 | 744 | // Pass the value as an expression as an only child: 745 | const result = {markdown} 746 | ``` 747 | 748 | 👆 That works. 749 | Read on for what doesn’t and why that is. 750 | 751 | You might try to write markdown directly in your JSX and find that it does 752 | not work: 753 | 754 | ```js 755 | 756 | # Hi 757 | 758 | This is not a paragraph. 759 | 760 | ``` 761 | 762 | The is because in JSX the whitespace (including line endings) is collapsed to 763 | a single space. 764 | So the above example is equivalent to: 765 | 766 | ```js 767 | # Hi This is not a paragraph. 768 | ``` 769 | 770 | Instead, to pass markdown to `Markdown`, you can use an expression: 771 | with a template literal: 772 | 773 | ```js 774 | {` 775 | # Hi 776 | 777 | This is a paragraph. 778 | `} 779 | ``` 780 | 781 | Template literals have another potential problem, because they keep whitespace 782 | (including indentation) inside them. 783 | That means that the following does not turn into a heading: 784 | 785 | ```js 786 | {` 787 | # This is not a heading, it’s an indented code block 788 | `} 789 | ``` 790 | 791 | ## Security 792 | 793 | Use of `react-markdown` is secure by default. 794 | Overwriting `urlTransform` to something insecure will open you up to XSS 795 | vectors. 796 | Furthermore, the `remarkPlugins`, `rehypePlugins`, and `components` you use may 797 | be insecure. 798 | 799 | To make sure the content is completely safe, even after what plugins do, 800 | use [`rehype-sanitize`][github-rehype-sanitize]. 801 | It lets you define your own schema of what is and isn’t allowed. 802 | 803 | ## Related 804 | 805 | * [`MDX`][github-mdx] 806 | — JSX in markdown 807 | * [`remark-gfm`][github-remark-gfm] 808 | — add support for GitHub flavored markdown support 809 | * [`react-remark`][github-react-remark] 810 | — hook based alternative 811 | * [`rehype-react`][github-rehype-react] 812 | — turn HTML into React elements 813 | 814 | ## Contribute 815 | 816 | See [`contributing.md`][health-contributing] in [`remarkjs/.github`][health] 817 | for ways to get started. 818 | See [`support.md`][health-support] for ways to get help. 819 | 820 | This project has a [code of conduct][health-coc]. 821 | By interacting with this repository, organization, or community you agree to 822 | abide by its terms. 823 | 824 | ## License 825 | 826 | [MIT][file-license] © [Espen Hovlandsdal][author] 827 | 828 | [api-allow-element]: #allowelement 829 | 830 | [api-components]: #components 831 | 832 | [api-default-url-transform]: #defaulturltransformurl 833 | 834 | [api-extra-props]: #extraprops 835 | 836 | [api-hooks-options]: #hooksoptions 837 | 838 | [api-markdown]: #markdown 839 | 840 | [api-markdown-async]: #markdownasync 841 | 842 | [api-markdown-hooks]: #markdownhooks 843 | 844 | [api-options]: #options 845 | 846 | [api-url-transform]: #urltransform 847 | 848 | [author]: https://espen.codes/ 849 | 850 | [badge-build-image]: https://github.com/remarkjs/react-markdown/workflows/main/badge.svg 851 | 852 | [badge-build-url]: https://github.com/remarkjs/react-markdown/actions 853 | 854 | [badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/react-markdown.svg 855 | 856 | [badge-coverage-url]: https://codecov.io/github/remarkjs/react-markdown 857 | 858 | [badge-downloads-image]: https://img.shields.io/npm/dm/react-markdown.svg 859 | 860 | [badge-downloads-url]: https://www.npmjs.com/package/react-markdown 861 | 862 | [badge-size-image]: https://img.shields.io/bundlejs/size/react-markdown 863 | 864 | [badge-size-url]: https://bundlejs.com/?q=react-markdown 865 | 866 | [commonmark-help]: https://commonmark.org/help/ 867 | 868 | [commonmark-html]: https://spec.commonmark.org/0.31.2/#html-blocks 869 | 870 | [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c 871 | 872 | [esmsh]: https://esm.sh 873 | 874 | [file-license]: license 875 | 876 | [github-awesome-rehype]: https://github.com/rehypejs/awesome-rehype 877 | 878 | [github-awesome-remark]: https://github.com/remarkjs/awesome-remark 879 | 880 | [github-conorhastings]: https://github.com/conorhastings 881 | 882 | [github-hast-element]: https://github.com/syntax-tree/hast#element 883 | 884 | [github-hast-nodes]: https://github.com/syntax-tree/hast#nodes 885 | 886 | [github-io-react-markdown]: https://remarkjs.github.io/react-markdown/ 887 | 888 | [github-mdx]: https://github.com/mdx-js/mdx/ 889 | 890 | [github-micromark]: https://github.com/micromark/micromark 891 | 892 | [github-react-remark]: https://github.com/remarkjs/react-remark 893 | 894 | [github-react-syntax-highlighter]: https://github.com/react-syntax-highlighter/react-syntax-highlighter 895 | 896 | [github-rehype]: https://github.com/rehypejs/rehype 897 | 898 | [github-rehype-katex]: https://github.com/remarkjs/remark-math/tree/main/packages/rehype-katex 899 | 900 | [github-rehype-plugins]: https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins 901 | 902 | [github-rehype-raw]: https://github.com/rehypejs/rehype-raw 903 | 904 | [github-rehype-react]: https://github.com/rehypejs/rehype-react 905 | 906 | [github-rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize 907 | 908 | [github-remark]: https://github.com/remarkjs/remark 909 | 910 | [github-remark-gfm]: https://github.com/remarkjs/remark-gfm 911 | 912 | [github-remark-math]: https://github.com/remarkjs/remark-math 913 | 914 | [github-remark-plugins]: https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins 915 | 916 | [github-remark-rehype-options]: https://github.com/remarkjs/remark-rehype#options 917 | 918 | [github-topic-rehype-plugin]: https://github.com/topics/rehype-plugin 919 | 920 | [github-topic-remark-plugin]: https://github.com/topics/remark-plugin 921 | 922 | [github-unified]: https://github.com/unifiedjs/unified 923 | 924 | [health]: https://github.com/remarkjs/.github 925 | 926 | [health-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md 927 | 928 | [health-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md 929 | 930 | [health-support]: https://github.com/remarkjs/.github/blob/main/support.md 931 | 932 | [npm-install]: https://docs.npmjs.com/cli/install 933 | 934 | [react]: http://reactjs.org 935 | 936 | [section-components]: #appendix-b-components 937 | 938 | [section-plugins]: #plugins 939 | 940 | [section-security]: #security 941 | 942 | [section-syntax]: #syntax 943 | 944 | [typescript]: https://www.typescriptlang.org 945 | -------------------------------------------------------------------------------- /script/load-jsx.js: -------------------------------------------------------------------------------- 1 | import fs from 'node:fs/promises' 2 | import {fileURLToPath} from 'node:url' 3 | import {transform} from 'esbuild' 4 | 5 | const {getFormat, load, transformSource} = createLoader() 6 | 7 | export {getFormat, load, transformSource} 8 | 9 | /** 10 | * A tiny JSX loader. 11 | */ 12 | export function createLoader() { 13 | return {load, getFormat, transformSource} 14 | 15 | // Node version 17. 16 | /** 17 | * @param {string} href 18 | * @param {unknown} context 19 | * @param {Function} defaultLoad 20 | */ 21 | async function load(href, context, defaultLoad) { 22 | const url = new URL(href) 23 | 24 | if (!url.pathname.endsWith('.jsx')) { 25 | return defaultLoad(href, context, defaultLoad) 26 | } 27 | 28 | const {code, warnings} = await transform(String(await fs.readFile(url)), { 29 | format: 'esm', 30 | loader: 'jsx', 31 | sourcefile: fileURLToPath(url), 32 | sourcemap: 'both', 33 | target: 'esnext' 34 | }) 35 | 36 | if (warnings) { 37 | for (const warning of warnings) { 38 | console.log(warning.location) 39 | console.log(warning.text) 40 | } 41 | } 42 | 43 | return {format: 'module', shortCircuit: true, source: code} 44 | } 45 | 46 | // Pre version 17. 47 | /** 48 | * @param {string} href 49 | * @param {unknown} context 50 | * @param {Function} defaultGetFormat 51 | */ 52 | function getFormat(href, context, defaultGetFormat) { 53 | const url = new URL(href) 54 | 55 | return url.pathname.endsWith('.jsx') 56 | ? {format: 'module'} 57 | : defaultGetFormat(href, context, defaultGetFormat) 58 | } 59 | 60 | /** 61 | * @param {Buffer} value 62 | * @param {{url: string, [x: string]: unknown}} context 63 | * @param {Function} defaultTransformSource 64 | / 65 | async function transformSource(value, context, defaultTransformSource) { 66 | const url = new URL(context.url) 67 | 68 | if (!url.pathname.endsWith('.jsx')) { 69 | return defaultTransformSource(value, context, defaultTransformSource) 70 | } 71 | 72 | const {code, warnings} = await transform(String(value), { 73 | format: context.format === 'module' ? 'esm' : 'cjs', 74 | loader: 'jsx', 75 | sourcefile: fileURLToPath(url), 76 | sourcemap: 'both', 77 | target: 'esnext' 78 | }) 79 | 80 | if (warnings) { 81 | for (const warning of warnings) { 82 | console.log(warning.location) 83 | console.log(warning.text) 84 | } 85 | } 86 | 87 | return {source: code} 88 | } 89 | } 90 | -------------------------------------------------------------------------------- /test.jsx: -------------------------------------------------------------------------------- 1 | / @jsxRuntime automatic @jsxImportSource react */ 2 | /** 3 | * @import {Root} from 'hast' 4 | * @import {ComponentProps, ReactNode} from 'react' 5 | * @import {ExtraProps} from 'react-markdown' 6 | * @import {Plugin} from 'unified' 7 | */ 8 | 9 | /** 10 | * @typedef DeferredPlugin 11 | * Deferred plugin. 12 | * @property {Plugin<[]>} plugin 13 | * Plugin. 14 | * @property {(error: Error) => undefined} reject 15 | * Reject the plugin. 16 | * @property {() => undefined} resolve 17 | * Resolve the plugin. 18 | */ 19 | 20 | import assert from 'node:assert/strict' 21 | import test from 'node:test' 22 | import 'global-jsdom/register' 23 | import {render, waitFor} from '@testing-library/react' 24 | import concatStream from 'concat-stream' 25 | import {Component} from 'react' 26 | import {renderToPipeableStream, renderToStaticMarkup} from 'react-dom/server' 27 | import Markdown, {MarkdownAsync, MarkdownHooks} from 'react-markdown' 28 | import rehypeRaw from 'rehype-raw' 29 | import rehypeStarryNight from 'rehype-starry-night' 30 | import remarkGfm from 'remark-gfm' 31 | import remarkToc from 'remark-toc' 32 | import {visit} from 'unist-util-visit' 33 | 34 | const decoder = new TextDecoder() 35 | 36 | test('react-markdown (core)', async function (t) { 37 | await t.test('should expose the public api', async function () { 38 | assert.deepEqual(Object.keys(await import('react-markdown')).sort(), [ 39 | 'MarkdownAsync', 40 | 'MarkdownHooks', 41 | 'default', 42 | 'defaultUrlTransform' 43 | ]) 44 | }) 45 | }) 46 | 47 | test('Markdown', async function (t) { 48 | await t.test('should work', function () { 49 | assert.equal(renderToStaticMarkup(), '
a
') 50 | }) 51 | 52 | await t.test('should throw w/ `source`', function () { 53 | assert.throws(function () { 54 | // @ts-expect-error: check how the runtime handles untyped `source`. 55 | renderToStaticMarkup() 56 | }, /Unexpected `source` prop, use `children` instead/) 57 | }) 58 | 59 | await t.test('should throw w/ non-string children (number)', function () { 60 | assert.throws(function () { 61 | // @ts-expect-error: check how the runtime handles invalid `children`. 62 | renderToStaticMarkup() 63 | }, /Unexpected value `1` for `children` prop, expected `string`/) 64 | }) 65 | 66 | await t.test('should throw w/ non-string children (boolean)', function () { 67 | assert.throws(function () { 68 | // @ts-expect-error: check how the runtime handles invalid `children`. 69 | renderToStaticMarkup() 70 | }, /Unexpected value `true` for `children` prop, expected `string`/) 71 | }) 72 | 73 | await t.test('should support `null` as children', function () { 74 | assert.equal(renderToStaticMarkup(), '') 75 | }) 76 | 77 | await t.test('should support `undefined` as children', function () { 78 | assert.equal(renderToStaticMarkup(), '') 79 | }) 80 | 81 | await t.test('should warn w/ `allowDangerousHtml`', function () { 82 | assert.throws(function () { 83 | // @ts-expect-error: check how the runtime handles deprecated `allowDangerousHtml`. 84 | renderToStaticMarkup() 85 | }, /Unexpected `allowDangerousHtml` prop, remove it/) 86 | }) 87 | 88 | await t.test('should support a block quote', function () { 89 | assert.equal( 90 | renderToStaticMarkup(), 91 | '
\n
a
\n
' 92 | ) 93 | }) 94 | 95 | await t.test('should support a break', function () { 96 | assert.equal( 97 | renderToStaticMarkup(), 98 | '
a
\nb
' 99 | ) 100 | }) 101 | 102 | await t.test('should support a code (block, flow; indented)', function () { 103 | assert.equal( 104 | renderToStaticMarkup(), 105 | '
`a\n`
' 106 | ) 107 | }) 108 | 109 | await t.test('should support a code (block, flow; fenced)', function () { 110 | assert.equal( 111 | renderToStaticMarkup(), 112 | '
`a\n`
' 113 | ) 114 | }) 115 | 116 | await t.test('should support a delete (GFM)', function () { 117 | assert.equal( 118 | renderToStaticMarkup( 119 | 120 | ), 121 | '
a
' 122 | ) 123 | }) 124 | 125 | await t.test('should support an emphasis', function () { 126 | assert.equal( 127 | renderToStaticMarkup(), 128 | '
a
' 129 | ) 130 | }) 131 | 132 | await t.test('should support a footnote (GFM)', function () { 133 | assert.equal( 134 | renderToStaticMarkup( 135 | 136 | ), 137 | '
a¹
\n
Footnotes
\n
\n
\n
y ↩
\n
\n
\n
' 138 | ) 139 | }) 140 | 141 | await t.test('should support a heading', function () { 142 | assert.equal( 143 | renderToStaticMarkup(), 144 | '
a
' 145 | ) 146 | }) 147 | 148 | await t.test('should support an html (default)', function () { 149 | assert.equal( 150 | renderToStaticMarkup(), 151 | '
<i>a</i>
' 152 | ) 153 | }) 154 | 155 | await t.test('should support an html (w/ `rehype-raw`)', function () { 156 | assert.equal( 157 | renderToStaticMarkup( 158 | 159 | ), 160 | '
a
' 161 | ) 162 | }) 163 | 164 | await t.test('should support an image', function () { 165 | assert.equal( 166 | renderToStaticMarkup(), 167 | // Note: React weirdly adds `rel="preload"`. 168 | '
' 169 | ) 170 | }) 171 | 172 | await t.test('should support an image w/ a title', function () { 173 | assert.equal( 174 | renderToStaticMarkup(), 175 | // Note: React weirdly adds `rel="preload"`. 176 | '
' 177 | ) 178 | }) 179 | 180 | await t.test('should support an image reference / definition', function () { 181 | assert.equal( 182 | renderToStaticMarkup(), 183 | // Note: React weirdly adds `rel="preload"`. 184 | '
' 185 | ) 186 | }) 187 | 188 | await t.test('should support code (text, inline)', function () { 189 | assert.equal( 190 | renderToStaticMarkup(), 191 | '
`a`
' 192 | ) 193 | }) 194 | 195 | await t.test('should support a link', function () { 196 | assert.equal( 197 | renderToStaticMarkup(), 198 | '
a
' 199 | ) 200 | }) 201 | 202 | await t.test('should support a link w/ a title', function () { 203 | assert.equal( 204 | renderToStaticMarkup(), 205 | '
a
' 206 | ) 207 | }) 208 | 209 | await t.test('should support a link reference / definition', function () { 210 | assert.equal( 211 | renderToStaticMarkup(), 212 | '
a
' 213 | ) 214 | }) 215 | 216 | await t.test('should support prototype poluting identifiers', function () { 217 | assert.equal( 218 | renderToStaticMarkup( 219 | 224 | ), 225 | '

' 226 | ) 227 | }) 228 | 229 | await t.test('should support duplicate definitions', function () { 230 | assert.equal( 231 | renderToStaticMarkup(), 232 | '
a
' 233 | ) 234 | }) 235 | 236 | await t.test('should support a list (unordered) / list item', function () { 237 | assert.equal( 238 | renderToStaticMarkup(), 239 | '
\n
a
\n
' 240 | ) 241 | }) 242 | 243 | await t.test('should support a list (ordered) / list item', function () { 244 | assert.equal( 245 | renderToStaticMarkup(), 246 | '
\n
a
\n
' 247 | ) 248 | }) 249 | 250 | await t.test('should support a paragraph', function () { 251 | assert.equal(renderToStaticMarkup(), '
a
') 252 | }) 253 | 254 | await t.test('should support a strong', function () { 255 | assert.equal( 256 | renderToStaticMarkup(), 257 | '
a
' 258 | ) 259 | }) 260 | 261 | await t.test('should support a table (GFM)', function () { 262 | assert.equal( 263 | renderToStaticMarkup( 264 | 268 | ), 269 | '
a
b
' 270 | ) 271 | }) 272 | 273 | await t.test('should support a table (GFM; w/ align)', function () { 274 | assert.equal( 275 | renderToStaticMarkup( 276 | 280 | ), 281 | '
a b c d
' 282 | ) 283 | }) 284 | 285 | await t.test('should support a thematic break', function () { 286 | assert.equal(renderToStaticMarkup(), '
') 287 | }) 288 | 289 | await t.test('should support ab absolute path', function () { 290 | assert.equal( 291 | renderToStaticMarkup(), 292 | '
' 293 | ) 294 | }) 295 | 296 | await t.test('should support an absolute URL', function () { 297 | assert.equal( 298 | renderToStaticMarkup(), 299 | '
' 300 | ) 301 | }) 302 | 303 | await t.test('should support a URL w/ uppercase protocol', function () { 304 | assert.equal( 305 | renderToStaticMarkup(), 306 | '
' 307 | ) 308 | }) 309 | 310 | await t.test('should make a `javascript:` URL safe', function () { 311 | assert.equal( 312 | renderToStaticMarkup(), 313 | '
' 314 | ) 315 | }) 316 | 317 | await t.test('should make a `vbscript:` URL safe', function () { 318 | assert.equal( 319 | renderToStaticMarkup(), 320 | '
' 321 | ) 322 | }) 323 | 324 | await t.test('should make a `VBSCRIPT:` URL safe', function () { 325 | assert.equal( 326 | renderToStaticMarkup(), 327 | '
' 328 | ) 329 | }) 330 | 331 | await t.test('should make a `file:` URL safe', function () { 332 | assert.equal( 333 | renderToStaticMarkup(), 334 | '
' 335 | ) 336 | }) 337 | 338 | await t.test('should allow an empty URL', function () { 339 | assert.equal( 340 | renderToStaticMarkup(), 341 | '
' 342 | ) 343 | }) 344 | 345 | await t.test('should support search (`?`) in a URL', function () { 346 | assert.equal( 347 | renderToStaticMarkup(), 348 | '
' 349 | ) 350 | }) 351 | 352 | await t.test('should support hash (`&`) in a URL', function () { 353 | assert.equal( 354 | renderToStaticMarkup(), 355 | '
' 356 | ) 357 | }) 358 | 359 | await t.test('should support hash (`#`) in a URL', function () { 360 | assert.equal( 361 | renderToStaticMarkup(), 362 | '
' 363 | ) 364 | }) 365 | 366 | await t.test('should support `urlTransform` (`href` on `a`)', function () { 367 | assert.equal( 368 | renderToStaticMarkup( 369 | 378 | ), 379 | '
a
' 380 | ) 381 | }) 382 | 383 | await t.test('should support `urlTransform` w/ empty URLs', function () { 384 | assert.equal( 385 | renderToStaticMarkup( 386 | 395 | ), 396 | '
' 397 | ) 398 | }) 399 | 400 | await t.test('should support `urlTransform` (`src` on `img`)', function () { 401 | assert.equal( 402 | renderToStaticMarkup( 403 | 412 | ), 413 | '
' 414 | ) 415 | }) 416 | 417 | await t.test('should support `skipHtml`', function () { 418 | const actual = renderToStaticMarkup( 419 | 420 | ) 421 | assert.equal(actual, '
abc
') 422 | }) 423 | 424 | await t.test( 425 | 'should support `allowedElements` (drop unlisted nodes)', 426 | function () { 427 | assert.equal( 428 | renderToStaticMarkup( 429 | 433 | ), 434 | '
\n
\n
b
\n
' 435 | ) 436 | } 437 | ) 438 | 439 | await t.test('should support `allowedElements` as a function', function () { 440 | assert.equal( 441 | renderToStaticMarkup( 442 | 448 | ), 449 | '
b
' 450 | ) 451 | }) 452 | await t.test('should support `disallowedElements`', function () { 453 | assert.equal( 454 | renderToStaticMarkup( 455 | 456 | ), 457 | '
\n
\n
b
\n
' 458 | ) 459 | }) 460 | 461 | await t.test( 462 | 'should fail for both `allowedElements` and `disallowedElements`', 463 | function () { 464 | assert.throws(function () { 465 | renderToStaticMarkup( 466 | 471 | ) 472 | }, /Unexpected combined `allowedElements` and `disallowedElements`, expected one or the other/) 473 | } 474 | ) 475 | 476 | await t.test( 477 | 'should support `unwrapDisallowed` w/ `allowedElements`', 478 | function () { 479 | assert.equal( 480 | renderToStaticMarkup( 481 | 486 | ), 487 | '
a
' 488 | ) 489 | } 490 | ) 491 | 492 | await t.test( 493 | 'should support `unwrapDisallowed` w/ `disallowedElements`', 494 | function () { 495 | assert.equal( 496 | renderToStaticMarkup( 497 | 502 | ), 503 | '
a
' 504 | ) 505 | } 506 | ) 507 | 508 | await t.test('should support `remarkRehypeOptions`', function () { 509 | assert.equal( 510 | renderToStaticMarkup( 511 | 516 | ), 517 | '
¹
\n
Footnotes
\n
\n
\n
a ↩
\n
\n
\n
' 518 | ) 519 | }) 520 | 521 | await t.test('should support `components`', function () { 522 | assert.equal( 523 | renderToStaticMarkup(), 524 | '
a
' 525 | ) 526 | }) 527 | 528 | await t.test('should support `components` as functions', function () { 529 | assert.equal( 530 | renderToStaticMarkup( 531 | 538 | } 539 | }} 540 | /> 541 | ), 542 | '
a
' 543 | ) 544 | }) 545 | 546 | await t.test('should fail on an invalid component', function () { 547 | assert.throws(function () { 548 | renderToStaticMarkup( 549 | 556 | ) 557 | }, /Element type is invalid/) 558 | }) 559 | 560 | await t.test('should support `components` (headings)', function () { 561 | let calls = 0 562 | 563 | assert.equal( 564 | renderToStaticMarkup( 565 | 569 | ), 570 | '
a
\n
b
' 571 | ) 572 | 573 | assert.equal(calls, 2) 574 | 575 | /** 576 | * @param {ComponentProps<'h1'> & ExtraProps} props 577 | */ 578 | function heading(props) { 579 | const {node, ...rest} = props 580 | assert(node) 581 | assert(node.tagName === 'h1' || node.tagName === 'h2') 582 | calls++ 583 | return 584 | } 585 | }) 586 | 587 | await t.test('should support `components` (code)', function () { 588 | let calls = 0 589 | assert.equal( 590 | renderToStaticMarkup( 591 | 600 | } 601 | }} 602 | /> 603 | ), 604 | '
`a\n`
\n
`b\n`
\n
`c`
' 605 | ) 606 | 607 | assert.equal(calls, 3) 608 | }) 609 | 610 | await t.test('should support `components` (li)', function () { 611 | let calls = 0 612 | 613 | assert.equal( 614 | renderToStaticMarkup( 615 | 624 | } 625 | }} 626 | remarkPlugins={[remarkGfm]} 627 | /> 628 | ), 629 | '
\n
a
\n
\n
\n
b
\n
' 630 | ) 631 | 632 | assert.equal(calls, 2) 633 | }) 634 | 635 | await t.test('should support `components` (ol)', function () { 636 | let calls = 0 637 | 638 | assert.equal( 639 | renderToStaticMarkup( 640 | 649 | } 650 | }} 651 | /> 652 | ), 653 | '
\n
a
\n
' 654 | ) 655 | 656 | assert.equal(calls, 1) 657 | }) 658 | 659 | await t.test('should support `components` (ul)', function () { 660 | let calls = 0 661 | 662 | assert.equal( 663 | renderToStaticMarkup( 664 | 673 | } 674 | }} 675 | /> 676 | ), 677 | '
\n
a
\n
' 678 | ) 679 | 680 | assert.equal(calls, 1) 681 | }) 682 | 683 | await t.test('should support `components` (tr)', function () { 684 | let calls = 0 685 | 686 | assert.equal( 687 | renderToStaticMarkup( 688 | 697 | } 698 | }} 699 | remarkPlugins={[remarkGfm]} 700 | /> 701 | ), 702 | '
a
b
' 703 | ) 704 | 705 | assert.equal(calls, 2) 706 | }) 707 | 708 | await t.test('should support `components` (td, th)', function () { 709 | let tdCalls = 0 710 | let thCalls = 0 711 | 712 | assert.equal( 713 | renderToStaticMarkup( 714 | 723 | }, 724 | th(props) { 725 | const {node, ...rest} = props 726 | assert(node) 727 | assert(node.tagName === 'th') 728 | thCalls++ 729 | return 730 | } 731 | }} 732 | remarkPlugins={[remarkGfm]} 733 | /> 734 | ), 735 | '
a
b
' 736 | ) 737 | 738 | assert.equal(tdCalls, 1) 739 | assert.equal(thCalls, 1) 740 | }) 741 | 742 | await t.test('should pass `node` to components', function () { 743 | let calls = 0 744 | assert.equal( 745 | renderToStaticMarkup( 746 | 772 | } 773 | }} 774 | /> 775 | ), 776 | '
a
' 777 | ) 778 | 779 | assert.equal(calls, 1) 780 | }) 781 | 782 | await t.test('should support plugins (`remark-gfm`)', function () { 783 | assert.equal( 784 | renderToStaticMarkup( 785 | 786 | ), 787 | '
a b c
' 788 | ) 789 | }) 790 | 791 | await t.test('should support plugins (`remark-toc`)', function () { 792 | assert.equal( 793 | renderToStaticMarkup( 794 | 798 | ), 799 | `
a
800 |
Contents
801 |
802 |
b 803 |
804 |
c
805 |
806 |
807 |
d
808 |
809 |
b
810 |
c
811 |
d
` 812 | ) 813 | }) 814 | 815 | await t.test('should support aria properties', function () { 816 | assert.equal( 817 | renderToStaticMarkup(), 818 | '
c
' 819 | ) 820 | 821 | function plugin() { 822 | /** 823 | * @param {Root} tree 824 | * @returns {undefined} 825 | */ 826 | return function (tree) { 827 | tree.children.unshift({ 828 | type: 'element', 829 | tagName: 'input', 830 | properties: {id: 'a', ariaDescribedBy: 'b', required: true}, 831 | children: [] 832 | }) 833 | } 834 | } 835 | }) 836 | 837 | await t.test('should support data properties', function () { 838 | assert.equal( 839 | renderToStaticMarkup(), 840 | '
b
' 841 | ) 842 | 843 | function plugin() { 844 | /** 845 | * @param {Root} tree 846 | * @returns {undefined} 847 | */ 848 | return function (tree) { 849 | tree.children.unshift({ 850 | type: 'element', 851 | tagName: 'i', 852 | properties: {dataWhatever: 'a', dataIgnoreThis: undefined}, 853 | children: [] 854 | }) 855 | } 856 | } 857 | }) 858 | 859 | await t.test('should support comma separated properties', function () { 860 | assert.equal( 861 | renderToStaticMarkup(), 862 | '
c
' 863 | ) 864 | 865 | function plugin() { 866 | /** 867 | * @param {Root} tree 868 | * @returns {undefined} 869 | */ 870 | return function (tree) { 871 | tree.children.unshift({ 872 | type: 'element', 873 | tagName: 'i', 874 | properties: {accept: ['a', 'b']}, 875 | children: [] 876 | }) 877 | } 878 | } 879 | }) 880 | 881 | await t.test('should support `style` properties', function () { 882 | assert.equal( 883 | renderToStaticMarkup(), 884 | '
a
' 885 | ) 886 | 887 | function plugin() { 888 | /** 889 | * @param {Root} tree 890 | * @returns {undefined} 891 | */ 892 | return function (tree) { 893 | tree.children.unshift({ 894 | type: 'element', 895 | tagName: 'i', 896 | properties: {style: 'color: red; font-weight: bold'}, 897 | children: [] 898 | }) 899 | } 900 | } 901 | }) 902 | 903 | await t.test( 904 | 'should support `style` properties w/ vendor prefixes', 905 | function () { 906 | assert.equal( 907 | renderToStaticMarkup( 908 | 909 | ), 910 | '
a
' 911 | ) 912 | 913 | function plugin() { 914 | /** 915 | * @param {Root} tree 916 | * @returns {undefined} 917 | */ 918 | return function (tree) { 919 | tree.children.unshift({ 920 | type: 'element', 921 | tagName: 'i', 922 | properties: {style: '-ms-b: 1; -webkit-c: 2'}, 923 | children: [] 924 | }) 925 | } 926 | } 927 | } 928 | ) 929 | 930 | await t.test('should support broken `style` properties', function () { 931 | assert.equal( 932 | renderToStaticMarkup(), 933 | '
a
' 934 | ) 935 | 936 | function plugin() { 937 | /** 938 | * @param {Root} tree 939 | * @returns {undefined} 940 | */ 941 | return function (tree) { 942 | tree.children.unshift({ 943 | type: 'element', 944 | tagName: 'i', 945 | properties: {style: 'broken'}, 946 | children: [] 947 | }) 948 | } 949 | } 950 | }) 951 | 952 | await t.test('should support SVG elements', function () { 953 | assert.equal( 954 | renderToStaticMarkup(), 955 | '
a
' 956 | ) 957 | 958 | function plugin() { 959 | /** 960 | * @param {Root} tree 961 | * @returns {undefined} 962 | */ 963 | return function (tree) { 964 | tree.children.unshift({ 965 | type: 'element', 966 | tagName: 'svg', 967 | properties: { 968 | viewBox: '0 0 500 500', 969 | xmlns: 'http://www.w3.org/2000/svg' 970 | }, 971 | children: [ 972 | { 973 | type: 'element', 974 | tagName: 'title', 975 | properties: {}, 976 | children: [{type: 'text', value: 'SVG `` element'}] 977 | }, 978 | { 979 | type: 'element', 980 | tagName: 'circle', 981 | properties: {cx: 120, cy: 120, r: 100}, 982 | children: [] 983 | }, 984 | // `strokeMiterLimit` in hast, `strokeMiterlimit` in React. 985 | { 986 | type: 'element', 987 | tagName: 'path', 988 | properties: {strokeMiterLimit: -1}, 989 | children: [] 990 | } 991 | ] 992 | }) 993 | } 994 | } 995 | }) 996 | 997 | await t.test('should support comments (ignore them)', function () { 998 | const input = 'a' 999 | const actual = renderToStaticMarkup( 1000 | 1001 | ) 1002 | const expected = '
a
' 1003 | assert.equal(actual, expected) 1004 | 1005 | function plugin() { 1006 | /** 1007 | * @param {Root} tree 1008 | * @returns {undefined} 1009 | */ 1010 | return function (tree) { 1011 | tree.children.unshift({type: 'comment', value: 'things!'}) 1012 | } 1013 | } 1014 | }) 1015 | 1016 | await t.test('should support table cells w/ style', function () { 1017 | assert.equal( 1018 | renderToStaticMarkup( 1019 | 1024 | ), 1025 | '
a
' 1026 | ) 1027 | 1028 | function plugin() { 1029 | /** 1030 | * @param {Root} tree 1031 | * @returns {undefined} 1032 | */ 1033 | return function (tree) { 1034 | visit(tree, 'element', function (node) { 1035 | if (node.tagName === 'th') { 1036 | node.properties = {...node.properties, style: 'color: red'} 1037 | } 1038 | }) 1039 | } 1040 | } 1041 | }) 1042 | 1043 | await t.test('should not fail on a plugin replacing `root`', function () { 1044 | assert.equal( 1045 | renderToStaticMarkup(), 1046 | '' 1047 | ) 1048 | 1049 | function plugin() { 1050 | /** 1051 | * @returns {Root} 1052 | */ 1053 | return function () { 1054 | // @ts-expect-error: check how non-roots are handled. 1055 | return {type: 'comment', value: 'things!'} 1056 | } 1057 | } 1058 | }) 1059 | }) 1060 | 1061 | test('MarkdownAsync', async function (t) { 1062 | await t.test('should support `MarkdownAsync` (1)', async function () { 1063 | assert.throws(function () { 1064 | renderToStaticMarkup() 1065 | }, /A component suspended while responding to synchronous input/) 1066 | }) 1067 | 1068 | await t.test('should support `MarkdownAsync` (2)', async function () { 1069 | return new Promise(function (resolve, reject) { 1070 | renderToPipeableStream() 1071 | .pipe( 1072 | concatStream({encoding: 'u8'}, function (data) { 1073 | assert.equal(decoder.decode(data), '
a
') 1074 | resolve() 1075 | }) 1076 | ) 1077 | .on('error', reject) 1078 | }) 1079 | }) 1080 | 1081 | await t.test( 1082 | 'should support async plugins w/ `MarkdownAsync` (`rehype-starry-night`)', 1083 | async function () { 1084 | return new Promise(function (resolve) { 1085 | renderToPipeableStream( 1086 | 1090 | ).pipe( 1091 | concatStream({encoding: 'u8'}, function (data) { 1092 | assert.equal( 1093 | decoder.decode(data), 1094 | '
`console.log(3.14)\n`
' 1095 | ) 1096 | resolve() 1097 | }) 1098 | ) 1099 | }) 1100 | } 1101 | ) 1102 | }) 1103 | 1104 | // Note: hooks are not supported on the “server”. 1105 | test('MarkdownHooks', async function (t) { 1106 | await t.test('should support `MarkdownHooks`', async function () { 1107 | const plugin = deferPlugin() 1108 | const result = render( 1109 | 1110 | ) 1111 | 1112 | assert.equal(result.container.innerHTML, '') 1113 | 1114 | plugin.resolve() 1115 | 1116 | await waitFor(function () { 1117 | assert.notEqual(result.container.innerHTML, '') 1118 | }) 1119 | 1120 | assert.equal(result.container.innerHTML, '
a
') 1121 | }) 1122 | 1123 | await t.test( 1124 | 'should support async plugins w/ `MarkdownHooks` (`rehype-starry-night`)', 1125 | async function () { 1126 | const plugin = deferPlugin() 1127 | const result = render( 1128 | 1132 | ) 1133 | 1134 | assert.equal(result.container.innerHTML, '') 1135 | 1136 | plugin.resolve() 1137 | 1138 | await waitFor(function () { 1139 | assert.notEqual(result.container.innerHTML, '') 1140 | }) 1141 | 1142 | assert.equal( 1143 | result.container.innerHTML, 1144 | '
`console.log(3.14)\n`
' 1145 | ) 1146 | } 1147 | ) 1148 | 1149 | await t.test('should support `fallback`', async function () { 1150 | const plugin = deferPlugin() 1151 | const result = render( 1152 | 1157 | ) 1158 | 1159 | assert.equal(result.container.innerHTML, 'Loading') 1160 | 1161 | plugin.resolve() 1162 | 1163 | await waitFor(function () { 1164 | assert.notEqual(result.container.innerHTML, 'Loading') 1165 | }) 1166 | 1167 | assert.equal(result.container.innerHTML, '
a
') 1168 | }) 1169 | 1170 | await t.test('should support plugins that error', async function () { 1171 | const plugin = deferPlugin() 1172 | const result = render( 1173 | 1174 | 1175 | 1176 | ) 1177 | 1178 | assert.equal(result.container.innerHTML, '') 1179 | 1180 | console.info('\nNote: the below error (`Error: rejected`) is expected.\n') 1181 | 1182 | plugin.reject(new Error('rejected')) 1183 | 1184 | await waitFor(function () { 1185 | assert.notEqual(result.container.innerHTML, '') 1186 | }) 1187 | 1188 | console.info('Note: the above error (`Error: rejected`) was expected.') 1189 | 1190 | assert.equal(result.container.innerHTML, 'Error: rejected') 1191 | }) 1192 | 1193 | await t.test('should support rerenders', async function () { 1194 | const pluginA = deferPlugin() 1195 | const pluginB = deferPlugin() 1196 | 1197 | const result = render( 1198 | 1199 | ) 1200 | 1201 | assert.equal(result.container.innerHTML, '') 1202 | 1203 | result.rerender( 1204 | 1205 | ) 1206 | 1207 | assert.equal(result.container.innerHTML, '') 1208 | 1209 | pluginA.resolve() 1210 | pluginB.resolve() 1211 | 1212 | await waitFor(function () { 1213 | assert.notEqual(result.container.innerHTML, '') 1214 | }) 1215 | 1216 | assert.equal(result.container.innerHTML, '
b
') 1217 | }) 1218 | }) 1219 | 1220 | /** 1221 | * Create an async unified plugin that waits until a promise is resolved or 1222 | * rejected from the outside. 1223 | * 1224 | * @returns {DeferredPlugin} 1225 | * Deferred plugin object. 1226 | */ 1227 | function deferPlugin() { 1228 | /** @type {(error: Error) => void} */ 1229 | let hoistedReject 1230 | /** @type {() => void} */ 1231 | let hoistedResolve 1232 | /** @type {Promise} */ 1233 | const promise = new Promise(function (resolve, reject) { 1234 | hoistedResolve = resolve 1235 | hoistedReject = reject 1236 | }) 1237 | 1238 | return { 1239 | plugin() { 1240 | return function () { 1241 | return promise 1242 | } 1243 | }, 1244 | reject(error) { 1245 | hoistedReject(error) 1246 | }, 1247 | resolve() { 1248 | hoistedResolve() 1249 | } 1250 | } 1251 | } 1252 | 1253 | /** 1254 | * Basic error boundary. 1255 | */ 1256 | class ErrorBoundary extends Component { 1257 | /** 1258 | * @param {Error} error 1259 | * Error. 1260 | * @returns {undefined} 1261 | * Nothing. 1262 | */ 1263 | componentDidCatch(error) { 1264 | this.setState({error}) 1265 | } 1266 | 1267 | render() { 1268 | const props = /** @type {{children: ReactNode}} */ (this.props) 1269 | 1270 | return this.state.error ? String(this.state.error) : props.children 1271 | } 1272 | 1273 | state = { 1274 | /** 1275 | * @type {Error | undefined} 1276 | * Error. 1277 | */ 1278 | error: undefined 1279 | } 1280 | } 1281 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "checkJs": true, 4 | "customConditions": ["development"], 5 | "declarationMap": true, 6 | "declaration": true, 7 | "emitDeclarationOnly": true, 8 | "exactOptionalPropertyTypes": true, 9 | "jsx": "preserve", 10 | "lib": ["dom", "es2022"], 11 | "module": "node16", 12 | "strict": true, 13 | "target": "es2022" 14 | }, 15 | "exclude": ["coverage/", "node_modules/"], 16 | "include": ["**/*.js", "**/*.jsx"] 17 | } 18 | --------------------------------------------------------------------------------