markdown-to-jsx 9.1.2 → 9.3.0

package/README.md

@@ -25,39 +25,30 @@ Some special features of the library:
   - [Entry Points](#entry-points)
     - [Main](#main)
     - [React](#react)
+    - [React Native](#react-native)
+    - [SolidJS](#solidjs)
+    - [Vue.js](#vuejs)
     - [HTML](#html)
     - [Markdown](#markdown)
   - [Library Options](#library-options)
-    - [options.forceBlock](#optionsforceblock)
-    - [options.forceInline](#optionsforceinline)
-    - [options.wrapper](#optionswrapper)
-      - [Other useful recipes](#other-useful-recipes)
-    - [options.wrapperProps](#optionswrapperprops)
+    - [All Options](#all-options)
+    - [options.createElement](#optionscreateelement)
     - [options.forceWrapper](#optionsforcewrapper)
-    - [options.overrides - Void particular banned tags](#optionsoverrides---void-particular-banned-tags)
-    - [options.overrides - Override Any HTML Tag's Representation](#optionsoverrides---override-any-html-tags-representation)
-    - [options.overrides - Rendering Arbitrary React Components](#optionsoverrides---rendering-arbitrary-react-components)
-    - [options.createElement - Custom React.createElement behavior](#optionscreateelement---custom-reactcreateelement-behavior)
-    - [options.enforceAtxHeadings](#optionsenforceatxheadings)
+    - [options.overrides](#optionsoverrides)
     - [options.renderRule](#optionsrenderrule)
     - [options.sanitizer](#optionssanitizer)
     - [options.slugify](#optionsslugify)
-    - [options.disableAutoLink](#optionsdisableautolink)
-    - [options.preserveFrontmatter](#optionspreservefrontmatter)
-    - [options.disableParsingRawHTML](#optionsdisableparsingrawhtml)
-    - [options.tagfilter](#optionstagfilter)
+    - [options.wrapper](#optionswrapper)
+      - [Other useful recipes](#other-useful-recipes)
+    - [options.wrapperProps](#optionswrapperprops)
   - [Syntax highlighting](#syntax-highlighting)
   - [Handling shortcodes](#handling-shortcodes)
-  - [Getting the smallest possible bundle size](#getting-the-smallest-possible-bundle-size)
   - [Usage with Preact](#usage-with-preact)
   - [AST Anatomy](#ast-anatomy)
     - [Node Types](#node-types)
     - [Example AST Structure](#example-ast-structure)
     - [Type Checking](#type-checking)
   - [Gotchas](#gotchas)
-    - [Passing props to stringified React components](#passing-props-to-stringified-react-components)
-    - [Significant indentation inside arbitrary HTML](#significant-indentation-inside-arbitrary-html)
-    - [Code blocks](#code-blocks)
 - [Changelog](#changelog)
 - [Donate](#donate)
 
@@ -72,37 +63,25 @@ Some special features of the library:
 - **`ast` option removed**: The `ast: true` option on `compiler()` has been removed. Use the new `parser()` function instead to access the AST directly.
 
 ```typescript
-// Before (v8)
-import { compiler } from 'markdown-to-jsx'
-const ast = compiler('# Hello world', { ast: true })
-
-// After (v9)
-import { parser } from 'markdown-to-jsx'
-const ast = parser('# Hello world')
+/** v8 */ compiler('# Hello world', { ast: true })
+/** v9 */ parser('# Hello world')
 ```
 
 - **`namedCodesToUnicode` option removed**: The `namedCodesToUnicode` option has been removed. All named HTML entities are now supported by default via the full entity list, so custom entity mappings are no longer needed.
 
 ```typescript
-// Before (v8)
-import { compiler } from 'markdown-to-jsx'
-compiler('≤ symbol', { namedCodesToUnicode: { le: '\u2264' } })
-
-// After (v9)
-import { compiler } from 'markdown-to-jsx'
-compiler('≤ symbol') // All entities supported automatically
+/** v8 */ compiler('≤ symbol', { namedCodesToUnicode: { le: '\u2264' } })
+/** v9 */ compiler('≤ symbol')
 ```
 
 - **`tagfilter` enabled by default**: Dangerous HTML tags (`script`, `iframe`, `style`, `title`, `textarea`, `xmp`, `noembed`, `noframes`, `plaintext`) are now escaped by default in both HTML string output and React JSX output. Previously these tags were rendered as JSX elements in React output.
 
 ```typescript
-// Before (v8) - tags rendered as JSX elements
-compiler('<script>alert("xss")</script>') // Rendered as <script> element
+/** v8 */ tags rendered as JSX elements
+/** v9 */ tags escaped by default
+compiler('<script>alert("xss")</script>') // <span>&lt;script&gt;</span>
 
-// After (v9) - tags escaped by default
-compiler('<script>alert("xss")</script>') // Renders as <span>&lt;script&gt;</span>
-
-// To restore old behavior:
+/** Restore old behavior */
 compiler('<script>alert("xss")</script>', { tagfilter: false })
 ```
 
@@ -128,33 +107,22 @@ import { compiler, astToMarkdown, parser } from 'markdown-to-jsx/markdown'
 1. **Replace `compiler(..., { ast: true })` with `parser()`**:
 
 ```typescript
-// Before
-import { compiler } from 'markdown-to-jsx'
-const ast = compiler(markdown, { ast: true })
-
-// After
-import { parser } from 'markdown-to-jsx'
-const ast = parser(markdown)
+/** v8 */ compiler(markdown, { ast: true })
+/** v9 */ parser(markdown)
 ```
 
 2. **Migrate React imports to `/react` entry point** (optional but recommended):
 
 ```typescript
-// Before
-import Markdown, { compiler } from 'markdown-to-jsx'
-
-// After (recommended)
-import Markdown, { compiler } from 'markdown-to-jsx/react'
+/** Legacy */ import from 'markdown-to-jsx'
+/** Recommended */ import from 'markdown-to-jsx/react'
 ```
 
 3. **Remove `namedCodesToUnicode` option**: All named HTML entities are now supported automatically, so you can remove any custom entity mappings.
 
 ```typescript
-// Before
-compiler('&le; symbol', { namedCodesToUnicode: { le: '\u2264' } })
-
-// After
-compiler('&le; symbol') // Works automatically
+/** v8 */ compiler('&le; symbol', { namedCodesToUnicode: { le: '\u2264' } })
+/** v9 */ compiler('&le; symbol')
 ```
 
 **Note:** The main entry point (`markdown-to-jsx`) continues to work for backward compatibility, but React code there is deprecated and will be removed in a future major release. Consider migrating to `markdown-to-jsx/react` for React-specific usage.
@@ -169,21 +137,15 @@ compiler('&le; symbol') // Works automatically
 - Type `ParserResult` renamed to `ASTNode` - If you were using `MarkdownToJSX.ParserResult` in your code, update to `MarkdownToJSX.ASTNode`
 
 ```typescript
-// Before
-const nodes: MarkdownToJSX.ParserResult[] = parse(markdown)
-
-// After
-const nodes: MarkdownToJSX.ASTNode[] = parse(markdown)
+/** v7 */ MarkdownToJSX.ParserResult[]
+/** v8+ */ MarkdownToJSX.ASTNode[]
 ```
 
 - Multiple `RuleType` enums consolidated into `RuleType.textFormatted` - If you were checking for `RuleType.textBolded`, `RuleType.textEmphasized`, `RuleType.textMarked`, or `RuleType.textStrikethroughed`, update to check for `RuleType.textFormatted` and inspect the node's boolean flags:
 
 ```typescript
-// Before
-if (node.type === RuleType.textBolded) { ... }
-
-// After
-if (node.type === RuleType.textFormatted && node.bold) { ... }
+/** v7 */ RuleType.textBolded
+/** v8+ */ RuleType.textFormatted && node.bold
 ```
 
 </details>
@@ -239,290 +201,224 @@ For React-specific usage, import from the `/react` entry point:
 ```tsx
 import Markdown, { compiler, parser, astToJSX } from 'markdown-to-jsx/react'
 
-// Use compiler for markdown → JSX
 const jsxElement = compiler('# Hello world')
 
-const markdown = `# Hello world`
-
 function App() {
-  return <Markdown children={markdown} />
+  return <Markdown children="# Hello world" />
 }
 
-// Or use parser + astToJSX for total control
+/** Or use parser + astToJSX */
 const ast = parser('# Hello world')
 const jsxElement2 = astToJSX(ast)
 ```
 
-#### HTML
+#### React Native
 
-For HTML string output (server-side rendering), import from the `/html` entry point:
+For React Native usage, import from the `/native` entry point:
 
 ```tsx
-import { compiler, html, parser } from 'markdown-to-jsx/html'
-
-// Convenience function that combines parsing and HTML rendering
-const htmlString = compiler('# Hello world')
-// Returns: '<h1>Hello world</h1>'
-
-// Or use parser + html separately for more control
-const ast = parser('# Hello world')
-const htmlString2 = html(ast)
-```
-
-#### Markdown
-
-For markdown-to-markdown compilation (normalization and formatting), import from the `/markdown` entry point:
-
-```typescript
-import { compiler, astToMarkdown, parser } from 'markdown-to-jsx/markdown'
-
-// Convenience function that parses and recompiles markdown
-const normalizedMarkdown = compiler('# Hello  world\n\nExtra spaces!')
-// Returns: '# Hello world\n\nExtra spaces!\n'
-
-// Or work with AST directly
-const ast = parser('# Hello  world')
-const normalizedMarkdown2 = astToMarkdown(ast)
-// Returns: '# Hello world\n'
-```
-
-### Library Options
-
-#### options.forceBlock
-
-By default, the compiler will try to make an intelligent guess about the content passed and wrap it in a `<div>`, `<p>`, or `<span>` as needed to satisfy the "inline"-ness of the markdown. For instance, this string would be considered "inline":
+import Markdown, { compiler, parser, astToNative } from 'markdown-to-jsx/native'
+import { View, Text, StyleSheet, Linking } from 'react-native'
+
+const nativeElement = compiler('# Hello world', {
+  styles: {
+    heading1: { fontSize: 32, fontWeight: 'bold' },
+    paragraph: { marginVertical: 8 },
+    link: { color: 'blue', textDecorationLine: 'underline' },
+  },
+  onLinkPress: url => {
+    Linking.openURL(url)
+  },
+})
 
-```md
-Hello. _Beautiful_ day isn't it?
-```
+const markdown = `# Hello world
 
-But this string would be considered "block" due to the existence of a header tag, which is a block-level HTML element:
+This is a [link](https://example.com) with **bold** and *italic* text.
+`
 
-```md
-# Whaddup?
+function App() {
+  return (
+    <View>
+      <Markdown
+        children={markdown}
+        options={{
+          styles: StyleSheet.create({
+            heading1: { fontSize: 32, fontWeight: 'bold' },
+            paragraph: { marginVertical: 8 },
+            link: { color: 'blue', textDecorationLine: 'underline' },
+          }),
+          onLinkPress: url => {
+            Linking.openURL(url)
+          },
+        }}
+      />
+    </View>
+  )
+}
 ```
 
-However, if you really want all input strings to be treated as "block" layout, simply pass `options.forceBlock = true` like this:
+**React Native-specific options:**
 
-```tsx
-<Markdown options={{ forceBlock: true }}>Hello there old chap!</Markdown>
+- `onLinkPress?: (url: string, title?: string) => void` - Custom handler for link presses (defaults to `Linking.openURL`)
+- `onLinkLongPress?: (url: string, title?: string) => void` - Handler for link long presses
+- `styles?: Partial<Record<NativeStyleKey, StyleProp<ViewStyle | TextStyle | ImageStyle>>>` - Style overrides for each element type
+- `wrapperProps?: ViewProps | TextProps` - Props for the wrapper component (defaults to `View` for block, `Text` for inline)
 
-// or
+**HTML Tag Mapping:**
+HTML tags are automatically mapped to React Native components:
 
-compiler('Hello there old chap!', { forceBlock: true })
+- `<img>` → `Image` component
+- Block elements (`<div>`, `<section>`, `<article>`, `<blockquote>`, `<ul>`, `<ol>`, `<li>`, `<table>`, etc.) → `View` component
+- Inline elements (`<span>`, `<strong>`, `<em>`, `<a>`, etc.) → `Text` component
+- Type 1 blocks (`<pre>`, `<script>`, `<style>`, `<textarea>`) → `View` component
 
-// renders
-<p>Hello there old chap!</p>
-```
+**Note:** Links are underlined by default for better accessibility and discoverability. You can override this via the `styles.link` option.
 
-#### options.forceInline
+#### SolidJS
 
-The inverse is also available by passing `options.forceInline = true`:
+For SolidJS usage, import from the `/solid` entry point:
 
 ```tsx
-<Markdown options={{ forceInline: true }}># You got it babe!</Markdown>
-
-// or
-compiler('# You got it babe!', { forceInline: true })
+import Markdown, {
+  compiler,
+  parser,
+  astToJSX,
+  MarkdownProvider,
+} from 'markdown-to-jsx/solid'
+import { createSignal } from 'solid-js'
 
-// renders
-<span># You got it babe!</span>
-```
+// Static content
+const solidElement = compiler('# Hello world')
 
-#### options.wrapper
-
-When there are multiple children to be rendered, the compiler will wrap the output in a `div` by default. You can override this default by setting the `wrapper` option to either a string (React Element) or a component.
-
-```tsx
-const str = '# Heck Yes\n\nThis is great!'
-
-<Markdown options={{ wrapper: 'article' }}>
-  {str}
-</Markdown>;
-
-// or
+function App() {
+  return <Markdown children="# Hello world" />
+}
 
-compiler(str, { wrapper: 'article' });
+// Reactive content (automatically updates when content changes)
+function ReactiveApp() {
+  const [content, setContent] = createSignal('# Hello world')
+  return <Markdown>{content}</Markdown>
+}
 
-// renders
+// Or use parser + astToJSX
+const ast = parser('# Hello world')
+const solidElement2 = astToJSX(ast)
 
-<article>
-  <h1>Heck Yes</h1>
-  <p>This is great!</p>
-</article>
+// Use context for default options
+function AppWithContext() {
+  return (
+    <MarkdownProvider options={{ sanitizer: customSanitizer }}>
+      <Markdown># Content</Markdown>
+    </MarkdownProvider>
+  )
+}
 ```
 
-##### Other useful recipes
-
-To get an array of children back without a wrapper, set `wrapper` to `null`. This is particularly useful when using `compiler(…)` directly.
-
-```tsx
-compiler('One\n\nTwo\n\nThree', { wrapper: null })
-
-// returns
-;[<p>One</p>, <p>Two</p>, <p>Three</p>]
-```
+**SolidJS-specific features:**
 
-To render children at the same DOM level as `<Markdown>` with no HTML wrapper, set `wrapper` to `React.Fragment`. This will still wrap your children in a React node for the purposes of rendering, but the wrapper element won't show up in the DOM.
+- **Reactive content**: The `Markdown` component accepts signals/accessors for automatic updates when markdown content changes
+- **Memoization**: AST parsing is automatically memoized for optimal performance
+- **Context API**: Use `MarkdownProvider` to provide default options and avoid prop drilling
 
-#### options.wrapperProps
+#### Vue.js
 
-Props to apply to the wrapper element when `wrapper` is used.
+For Vue.js 3 usage, import from the `/vue` entry point:
 
 ```tsx
-<Markdown options={{
-  wrapper: 'article',
-  wrapperProps: { className: 'post', 'data-testid': 'markdown-content' }
-}}>
-  # Hello World
-</Markdown>
+import Markdown, { compiler, parser, astToJSX } from 'markdown-to-jsx/vue'
+import { h } from 'vue'
 
-// renders
-<article class="post" data-testid="markdown-content">
-  <h1>Hello World</h1>
-</article>
-```
+// Using compiler
+const vnode = compiler('# Hello world')
 
-#### options.forceWrapper
-
-By default, the compiler does not wrap the rendered contents if there is only a single child. You can change this by setting `forceWrapper` to `true`. If the child is inline, it will not necessarily be wrapped in a `span`.
+// Using component
+<Markdown children="# Hello world" />
 
-```tsx
-// Using `forceWrapper` with a single, inline child…
-<Markdown options={{ wrapper: 'aside', forceWrapper: true }}>
-  Mumble, mumble…
-</Markdown>
-
-// renders
-
-<aside>Mumble, mumble…</aside>
+// Or use parser + astToJSX
+const ast = parser('# Hello world')
+const vnode2 = astToJSX(ast)
 ```
 
-#### options.overrides - Void particular banned tags
+**Vue.js-specific features:**
 
-Pass the `options.overrides` prop to the compiler or `<Markdown>` component with an implementation that return `null` for tags you wish to exclude from the rendered output. This provides complete removal of tags from the output.
+- **Vue 3 support**: Uses Vue 3's `h()` render function API
+- **JSX support**: Works with Vue 3 JSX via `@vue/babel-plugin-jsx` or `@vitejs/plugin-vue-jsx`
+- **HTML attributes**: Uses standard HTML attributes (`class` instead of `className`)
+- **Component overrides**: Support for both Options API and Composition API componen
 
-**Note**: The `tagfilter` option provides default escaping of dangerous tags (`script`, `iframe`, `style`, `title`, `textarea`, `xmp`, `noembed`, `noframes`, `plaintext`). Use `overrides` when you need to:
-
-- Remove additional tags not covered by `tagfilter` (like `object`)
-- Have more control over tag removal vs. escaping
-- Disable `tagfilter` but still want to remove specific tags
+#### HTML
 
-For example, to void the `iframe` tag:
+For HTML string output (server-side rendering), import from the `/html` entry point:
 
 ```tsx
-import Markdown from 'markdown-to-jsx'
-import React from 'react'
-import { render } from 'react-dom'
+import { compiler, html, parser } from 'markdown-to-jsx/html'
 
-render(
-  <Markdown options={{ overrides: { iframe: () => null } }}>
-    <iframe src="https://potentially-malicious-web-page.com/"></iframe>
-  </Markdown>,
-  document.body
-)
+const htmlString = compiler('# Hello world')
 
-// renders: ""
+/** Or use parser + html */
+const ast = parser('# Hello world')
+const htmlString2 = html(ast)
 ```
 
-The library does not void any tags by default (except through `tagfilter` escaping), allowing you to choose the appropriate security approach for your use case.
-
-#### options.overrides - Override Any HTML Tag's Representation
-
-Pass the `options.overrides` prop to the compiler or `<Markdown>` component to seamlessly revise the rendered representation of any HTML tag. You can choose to change the component itself, add/change props, or both.
-
-```tsx
-import Markdown from 'markdown-to-jsx'
-import React from 'react'
-import { render } from 'react-dom'
-
-// surprise, it's a div instead!
-const MyParagraph = ({ children, ...props }) => <div {...props}>{children}</div>
-
-render(
-  <Markdown
-    options={{
-      overrides: {
-        h1: {
-          component: MyParagraph,
-          props: {
-            className: 'foo',
-          },
-        },
-      },
-    }}
-  >
-    # Hello world!
-  </Markdown>,
-  document.body
-)
+#### Markdown
 
-/*
-    renders:
+For markdown-to-markdown compilation (normalization and formatting), import from the `/markdown` entry point:
 
-    <div class="foo">
-        Hello World
-    </div>
- */
-```
+```typescript
+import { compiler, astToMarkdown, parser } from 'markdown-to-jsx/markdown'
 
-If you only wish to provide a component override, a simplified syntax is available:
+const normalizedMarkdown = compiler('# Hello  world\n\nExtra spaces!')
 
-```js
-{
-    overrides: {
-        h1: MyParagraph,
-    },
-}
+/** Or work with AST */
+const ast = parser('# Hello  world')
+const normalizedMarkdown2 = astToMarkdown(ast)
 ```
 
-Depending on the type of element, there are some props that must be preserved to ensure the markdown is converted as intended. They are:
-
-- `a`: `title`, `href`
-- `img`: `title`, `alt`, `src`
-- `input[type="checkbox"]`: `checked`, `readonly` (specifically, the one rendered by a GFM task list)
-- `ol`: `start`
-- `td`: `style`
-- `th`: `style`
-
-Any conflicts between passed `props` and the specific properties above will be resolved in favor of `markdown-to-jsx`'s code.
-
-Some element mappings are a bit different from other libraries, in particular:
-
-- `span`: Used for inline text.
-- `code`: Used for inline code.
-- `pre > code`: Code blocks are a `code` element with a `pre` as its direct ancestor.
-
-#### options.overrides - Rendering Arbitrary React Components
+### Library Options
 
-One of the most interesting use cases enabled by the HTML syntax processing in `markdown-to-jsx` is the ability to use any kind of element, even ones that aren't real HTML tags like React component classes.
+#### All Options
+
+| Option                  | Type                          | Default  | Description                                                                                                                  |
+| ----------------------- | ----------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `createElement`         | `function`                    | -        | Custom createElement behavior (React/React Native/SolidJS/Vue only). See [createElement](#optionscreateelement) for details. |
+| `disableAutoLink`       | `boolean`                     | `false`  | Disable automatic conversion of bare URLs to anchor tags.                                                                    |
+| `disableParsingRawHTML` | `boolean`                     | `false`  | Disable parsing of raw HTML into JSX.                                                                                        |
+| `enforceAtxHeadings`    | `boolean`                     | `false`  | Require space between `#` and header text (GFM spec compliance).                                                             |
+| `forceBlock`            | `boolean`                     | `false`  | Force all content to be treated as block-level.                                                                              |
+| `forceInline`           | `boolean`                     | `false`  | Force all content to be treated as inline.                                                                                   |
+| `forceWrapper`          | `boolean`                     | `false`  | Force wrapper even with single child (React/React Native/Vue only). See [forceWrapper](#optionsforcewrapper) for details.    |
+| `overrides`             | `object`                      | -        | Override HTML tag rendering. See [overrides](#optionsoverrides) for details.                                                 |
+| `preserveFrontmatter`   | `boolean`                     | `false`  | Include frontmatter in rendered output (as `<pre>` for HTML/JSX, included in markdown). Behavior varies by compiler type.    |
+| `renderRule`            | `function`                    | -        | Custom rendering for AST rules. See [renderRule](#optionsrenderrule) for details.                                            |
+| `sanitizer`             | `function`                    | built-in | Custom URL sanitizer function. See [sanitizer](#optionssanitizer) for details.                                               |
+| `slugify`               | `function`                    | built-in | Custom slug generation for heading IDs. See [slugify](#optionsslugify) for details.                                          |
+| `tagfilter`             | `boolean`                     | `true`   | Escape dangerous HTML tags (`script`, `iframe`, `style`, etc.) to prevent XSS.                                               |
+| `wrapper`               | `string \| component \| null` | `'div'`  | Wrapper element for multiple children (React/React Native/Vue only). See [wrapper](#optionswrapper) for details.             |
+| `wrapperProps`          | `object`                      | -        | Props for wrapper element (React/React Native/Vue only). See [wrapperProps](#optionswrapperprops) for details.               |
+
+#### options.createElement
 
-By adding an override for the components you plan to use in markdown documents, it's possible to dynamically render almost anything. One possible scenario could be writing documentation:
+Sometimes, you might want to override the `React.createElement` default behavior to hook into the rendering process before the JSX gets rendered. This might be useful to add extra children or modify some props based on runtime conditions. The function mirrors the `React.createElement` function, so the params are [`type, [props], [...children]`](https://reactjs.org/docs/react-api.html#createelement):
 
-```tsx
+```javascript
 import Markdown from 'markdown-to-jsx'
 import React from 'react'
 import { render } from 'react-dom'
 
-import DatePicker from './date-picker'
-
 const md = `
-# DatePicker
-
-The DatePicker works by supplying a date to bias towards,
-as well as a default timezone.
-
-<DatePicker biasTowardDateTime="2017-12-05T07:39:36.091Z" timezone="UTC+5" />
+# Hello world
 `
 
 render(
   <Markdown
     children={md}
     options={{
-      overrides: {
-        DatePicker: {
-          component: DatePicker,
-        },
+      createElement(type, props, children) {
+        return (
+          <div className="parent">
+            {React.createElement(type, props, children)}
+          </div>
+        )
       },
     }}
   />,
@@ -530,129 +426,61 @@ render(
 )
 ```
 
-`markdown-to-jsx` also handles JSX interpolation syntax, but in a minimal way to not introduce a potential attack vector. Interpolations are sent to the component as their raw string, which the consumer can then `eval()` or process as desired to their security needs.
+#### options.forceWrapper
 
-In the following case, `DatePicker` could simply run `parseInt()` on the passed `startTime` for example:
+By default, the compiler does not wrap the rendered contents if there is only a single child. You can change this by setting `forceWrapper` to `true`. If the child is inline, it will not necessarily be wrapped in a `span`.
 
 ```tsx
-import Markdown from 'markdown-to-jsx'
-import React from 'react'
-import { render } from 'react-dom'
-
-import DatePicker from './date-picker'
-
-const md = `
-# DatePicker
-
-The DatePicker works by supplying a date to bias towards,
-as well as a default timezone.
+// Using `forceWrapper` with a single, inline child…
+<Markdown options={{ wrapper: 'aside', forceWrapper: true }}>
+  Mumble, mumble…
+</Markdown>
 
-<DatePicker
-  biasTowardDateTime="2017-12-05T07:39:36.091Z"
-  timezone="UTC+5"
-  startTime={1514579720511}
-/>
-`
+// renders
 
-render(
-  <Markdown
-    children={md}
-    options={{
-      overrides: {
-        DatePicker: {
-          component: DatePicker,
-        },
-      },
-    }}
-  />,
-  document.body
-)
+<aside>Mumble, mumble…</aside>
 ```
 
-Another possibility is to use something like [recompose's `withProps()` HOC](https://github.com/acdlite/recompose/blob/main/docs/API.md#withprops) to create various pregenerated scenarios and then reference them by name in the markdown:
-
-```tsx
-import Markdown from 'markdown-to-jsx'
-import React from 'react'
-import { render } from 'react-dom'
-import withProps from 'recompose/withProps'
-
-import DatePicker from './date-picker'
+#### options.overrides
 
-const DecemberDatePicker = withProps({
-  range: {
-    start: new Date('2017-12-01'),
-    end: new Date('2017-12-31'),
-  },
-  timezone: 'UTC+5',
-})(DatePicker)
+Override HTML tag rendering or render custom React components. Three use cases:
 
-const md = `
-# DatePicker
+**1. Remove tags:** Return `null` to completely remove tags (beyond `tagfilter` escaping):
 
-The DatePicker works by supplying a date to bias towards,
-as well as a default timezone.
+```tsx
+<Markdown options={{ overrides: { iframe: () => null } }}>
+  <iframe src="..."></iframe>
+</Markdown>
+```
 
-<DatePicker
-  biasTowardDateTime="2017-12-05T07:39:36.091Z"
-  timezone="UTC+5"
-  startTime={1514579720511}
-/>
+**2. Override HTML tags:** Change component, props, or both:
 
-Here's an example of a DatePicker pre-set to only the month of December:
+```tsx
+const MyParagraph = ({ children, ...props }) => <div {...props}>{children}</div>
 
-<DecemberDatePicker />
-`
+<Markdown options={{ overrides: { h1: { component: MyParagraph, props: { className: 'foo' } } } }}>
+  # Hello
+</Markdown>
 
-render(
-  <Markdown
-    children={md}
-    options={{
-      overrides: {
-        DatePicker,
-        DecemberDatePicker,
-      },
-    }}
-  />,
-  document.body
-)
+/** Simplified */ { overrides: { h1: MyParagraph } }
 ```
 
-#### options.createElement - Custom React.createElement behavior
-
-Sometimes, you might want to override the `React.createElement` default behavior to hook into the rendering process before the JSX gets rendered. This might be useful to add extra children or modify some props based on runtime conditions. The function mirrors the `React.createElement` function, so the params are [`type, [props], [...children]`](https://reactjs.org/docs/react-api.html#createelement):
+**3. Render React components:** Use custom components in markdown:
 
-```javascript
-import Markdown from 'markdown-to-jsx'
-import React from 'react'
-import { render } from 'react-dom'
+```tsx
+import DatePicker from './date-picker'
 
-const md = `
-# Hello world
-`
+const md = `<DatePicker timezone="UTC+5" startTime={1514579720511} />`
 
-render(
-  <Markdown
-    children={md}
-    options={{
-      createElement(type, props, children) {
-        return (
-          <div className="parent">
-            {React.createElement(type, props, children)}
-          </div>
-        )
-      },
-    }}
-  />,
-  document.body
-)
+<Markdown options={{ overrides: { DatePicker } }}>{md}</Markdown>
 ```
 
-#### options.enforceAtxHeadings
-
-Forces the compiler to have space between hash sign `#` and the header text which is explicitly stated in the most of the [markdown specs](https://github.github.com/gfm/#atx-heading).
+**Important notes:**
 
-> The opening sequence of `#` characters must be followed by a space or by the end of line.
+- Props are passed as strings; parse them in your component (e.g., `JSON.parse(columns)`)
+- JSX interpolations (`{value}`) are passed as raw strings
+- Some props are preserved: `a` (`href`, `title`), `img` (`src`, `alt`, `title`), `input[type="checkbox"]` (`checked`, `readonly`), `ol` (`start`), `td`/`th` (`style`)
+- Element mappings: `span` for inline text, `code` for inline code, `pre > code` for code blocks
 
 #### options.renderRule
 
@@ -702,7 +530,7 @@ This can be overridden and replaced with a custom sanitizer if desired via `opti
 // or
 
 compiler('[foo](javascript:alert("foo"))', {
-  sanitizer: (value, tag, attribute) => value,
+  sanitizer: value => value,
 })
 ```
 
@@ -711,135 +539,51 @@ compiler('[foo](javascript:alert("foo"))', {
 By default, a [lightweight deburring function](https://github.com/quantizor/markdown-to-jsx/blob/bc2f57412332dc670f066320c0f38d0252e0f057/index.js#L261-L275) is used to generate an HTML id from headings. You can override this by passing a function to `options.slugify`. This is helpful when you are using non-alphanumeric characters (e.g. Chinese or Japanese characters) in headings. For example:
 
 ```tsx
-<Markdown options={{ slugify: str => str }}># 中文</Markdown>
-
-// or
-
+;<Markdown options={{ slugify: str => str }}># 中文</Markdown>
 compiler('# 中文', { slugify: str => str })
-
-// renders:
-<h1 id="中文">中文</h1>
 ```
 
 The original function is available as a library export called `slugify`.
 
-#### options.disableAutoLink
+#### options.wrapper
 
-By default, bare URLs in the markdown document will be converted into an anchor tag. This behavior can be disabled if desired.
+When there are multiple children to be rendered, the compiler will wrap the output in a `div` by default. You can override this default by setting the `wrapper` option to either a string (React Element) or a component.
 
 ```tsx
-<Markdown options={{ disableAutoLink: true }}>
-  The URL https://quantizor.dev will not be rendered as an anchor tag.
-</Markdown>
-
-// or
-
-compiler(
-  'The URL https://quantizor.dev will not be rendered as an anchor tag.',
-  { disableAutoLink: true }
-)
+const str = '# Heck Yes\n\nThis is great!'
 
-// renders:
+<Markdown options={{ wrapper: 'article' }}>{str}</Markdown>
 
-<span>
-  The URL https://quantizor.dev will not be rendered as an anchor tag.
-</span>
+compiler(str, { wrapper: 'article' })
 ```
 
-#### options.preserveFrontmatter
-
-By default, YAML frontmatter at the beginning of markdown documents is parsed but not rendered in the output. Set this option to `true` to include the frontmatter in the rendered output. For HTML/JSX output, frontmatter is rendered as a `<pre>` element. For markdown-to-markdown compilation, frontmatter is included in the output markdown.
-
-| Compiler Type            | Default Behavior            | When `preserveFrontmatter: true` | When `preserveFrontmatter: false` |
-| ------------------------ | --------------------------- | -------------------------------- | --------------------------------- |
-| **React/HTML**           | ❌ Don't render frontmatter | ✅ Render as `<pre>` element     | ❌ Don't render frontmatter       |
-| **Markdown-to-Markdown** | ✅ Preserve frontmatter     | ✅ Preserve frontmatter          | ❌ Exclude frontmatter            |
-
-```tsx
-<Markdown options={{ preserveFrontmatter: true }}>
-{`---
-title: My Document
-author: John Doe
----
-
-# Content
-
-This is the main content.`
-}
-</Markdown>
-
-// renders:
-
-<div>
-  <pre>---
-title: My Document
-author: John Doe
----</pre>
-  <h1>Content</h1>
-  <p>This is the main content.</p>
-</div>
-```
+##### Other useful recipes
 
-For markdown-to-markdown compilation:
+To get an array of children back without a wrapper, set `wrapper` to `null`. This is particularly useful when using `compiler(…)` directly.
 
 ```tsx
-import { compiler } from 'markdown-to-jsx/markdown'
-
-const markdown = `---
-title: My Document
-author: John Doe
----
-
-# Content`
-
-// With preserveFrontmatter: true (default)
-compiler(markdown, { preserveFrontmatter: true })
-// returns: "---\ntitle: My Document\nauthor: John Doe\n---\n\n# Content"
-
-// With preserveFrontmatter: false
-compiler(markdown, { preserveFrontmatter: false })
-// returns: "# Content"
+compiler('One\n\nTwo\n\nThree', { wrapper: null })[
+  /** Returns */ ((<p>One</p>), (<p>Two</p>), (<p>Three</p>))
+]
 ```
 
-#### options.disableParsingRawHTML
-
-By default, raw HTML is parsed to JSX. This behavior can be disabled if desired.
-
-```tsx
-<Markdown options={{ disableParsingRawHTML: true }}>
-    This text has <span>html</span> in it but it won't be rendered
-</Markdown>;
-
-// or
-
-compiler('This text has <span>html</span> in it but it won't be rendered', { disableParsingRawHTML: true });
-
-// renders:
-
-<span>This text has &lt;span&gt;html&lt;/span&gt; in it but it won't be rendered</span>
-```
+To render children at the same DOM level as `<Markdown>` with no HTML wrapper, set `wrapper` to `React.Fragment`. This will still wrap your children in a React node for the purposes of rendering, but the wrapper element won't show up in the DOM.
 
-#### options.tagfilter
+#### options.wrapperProps
 
-By default, dangerous HTML tags are filtered and escaped to prevent XSS attacks. This applies to both HTML string output and React JSX output. The following tags are filtered: `script`, `iframe`, `style`, `title`, `textarea`, `xmp`, `noembed`, `noframes`, `plaintext`.
+Props to apply to the wrapper element when `wrapper` is used.
 
 ```tsx
-// Tags are escaped by default (GFM-compliant)
-compiler('<script>alert("xss")</script>')
-// HTML output: '<span>&lt;script&gt;</span>'
-// React output: <span>&lt;script&gt;</span>
-
-// Disable tag filtering:
-compiler('<script>alert("xss")</script>', { tagfilter: false })
-// HTML output: '<script></script>'
-// React output: <script></script>
+<Markdown
+  options={{
+    wrapper: 'article',
+    wrapperProps: { className: 'post', 'data-testid': 'markdown-content' },
+  }}
+>
+  # Hello World
+</Markdown>
 ```
 
-**Note**: Even when `tagfilter` is disabled, other security measures remain active:
-
-- URL sanitization preventing `javascript:` and `vbscript:` schemes in `href` and `src` attributes
-- Protection against `data:` URLs (except safe `data:image/*` MIME types)
-
 ### Syntax highlighting
 
 When using [fenced code blocks](https://www.markdownguide.org/extended-syntax/#syntax-highlighting) with language annotation, that language will be added to the `<code>` element as `class="lang-${language}"`. For best results, you can use `options.overrides` to provide an appropriate syntax highlighting integration like this one using `highlight.js`:
@@ -876,7 +620,7 @@ function App() {
 }
 
 function SyntaxHighlightedCode(props) {
-  const ref = (React.useRef < HTMLElement) | (null > null)
+  const ref = React.useRef<HTMLElement | null>(null)
 
   React.useEffect(() => {
     if (ref.current && props.className?.includes('lang-') && window.hljs) {
@@ -933,24 +677,10 @@ function Example() {
     </Markdown>
   )
 }
-
-// renders
-// <span>On a beautiful summer day, all I want to do is <span>🙂</span>.</span>
 ```
 
 When you use `options.renderRule`, any React-renderable JSX may be returned including images and GIFs. Ensure you benchmark your solution as the `text` rule is one of the hottest paths in the system!
 
-### Getting the smallest possible bundle size
-
-Many development conveniences are placed behind `process.env.NODE_ENV !== "production"` conditionals. When bundling your app, it's a good idea to replace these code snippets such that a minifier (like uglify) can sweep them away and leave a smaller overall bundle.
-
-Here are instructions for some of the popular bundlers:
-
-- [webpack](https://webpack.js.org/guides/production/#specify-the-environment)
-- [browserify plugin](https://github.com/hughsk/envify)
-- [parcel](https://parceljs.org/production.html)
-- [fuse-box](http://fuse-box.org/plugins/replace-plugin#notes)
-
 ### Usage with Preact
 
 Everything will work just fine! Simply [Alias `react` to `preact/compat`](https://preactjs.com/guide/v10/switching-to-preact#setting-up-compat) like you probably already are doing.
@@ -1122,88 +852,24 @@ if (node.type === RuleType.heading) {
 
 ### Gotchas
 
-#### Passing props to stringified React components
-
-Using the [`options.overrides`](#optionsoverrides---rendering-arbitrary-react-components) functionality to render React components, props are passed into the component in stringifed form. It is up to you to parse the string to make use of the data.
+**Props are stringified:** When using `overrides` with React components, props are passed as strings. Parse them in your component:
 
 ```tsx
-const Table: React.FC<
-  JSX.IntrinsicElements['table'] & {
-    columns: string
-    dataSource: string
-  }
-> = ({ columns, dataSource, ...props }) => {
+const Table = ({ columns, dataSource, ...props }) => {
   const parsedColumns = JSON.parse(columns)
   const parsedData = JSON.parse(dataSource)
-
-  return (
-    <div {...props}>
-      <h1>Columns</h1>
-      {parsedColumns.map(column => (
-        <span key={column.key}>{column.title}</span>
-      ))}
-
-      <h2>Data</h2>
-      {parsedData.map(datum => (
-        <span key={datum.key}>{datum.Month}</span>
-      ))}
-    </div>
-  )
+  // ... use parsed data
 }
-
-/**
- * Example HTML in markdown:
- *
- * <Table
- *    columns={[{ title: 'Month', dataIndex: 'Month', key: 'Month' }]}
- *    dataSource={[
- *      {
- *        Month: '2024-09-01',
- *        'Forecasted Revenue': '$3,137,678.85',
- *        'Forecasted Expenses': '$2,036,660.28',
- *        key: 0,
- *      },
- *    ]}
- *  />
- */
-```
-
-#### Significant indentation inside arbitrary HTML
-
-People usually write HTML like this:
-
-```html
-<div>Hey, how are you?</div>
-```
-
-Note the leading spaces before the inner content. This sort of thing unfortunately clashes with existing markdown syntaxes since 4 spaces === a code block and other similar collisions.
-
-To get around this, `markdown-to-jsx` left-trims approximately as much whitespace as the first line inside the HTML block. So for example:
-
-```html
-<div># Hello How are you?</div>
 ```
 
-The two leading spaces in front of "# Hello" would be left-trimmed from all lines inside the HTML block. In the event that there are varying amounts of indentation, only the amount of the first line is trimmed.
-
-> NOTE! These syntaxes work just fine when you aren't writing arbitrary HTML wrappers inside your markdown. This is very much an edge case of an edge case. 🙃
-
-#### Code blocks
-
-⛔️
-
-```md
-<div>
-    var some = code();
-</div>
-```
+**HTML indentation:** Leading whitespace in HTML blocks is auto-trimmed based on the first line's indentation to avoid markdown syntax conflicts.
 
-✅
+**Code in HTML:** Don't put code directly in HTML divs. Use fenced code blocks instead:
 
 ````md
 <div>
 ```js
-var some = code();
+var code = here();
 ```
 </div>
 ````