`, `

`, ``, etc.) → `View` component - Inline elements (``, ``, ``, ``, etc.) → `Text` component - Type 1 blocks (`
`, ` ``` #### options.sanitizer By default a lightweight URL sanitizer function is provided to avoid common attack vectors that might be placed into the `href` of an anchor tag, for example. The sanitizer receives the input, the HTML tag being targeted, and the attribute name. The original function is available as a library export called `sanitizer`. This can be overridden and replaced with a custom sanitizer if desired via `options.sanitizer`: ```tsx // sanitizer in this situation would receive: // ('javascript:alert("foo")', 'a', 'href') value }}> {`[foo](javascript:alert("foo"))`} // or compiler('[foo](javascript:alert("foo"))', { sanitizer: value => value, }) ``` #### options.slugify 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 str }}># 中文 compiler('# 中文', { slugify: str => str }) ``` The original function is available as a library export called `slugify`. #### 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!' {str} compiler(str, { wrapper: 'article' }) ``` ##### 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 */ ((
One
), (
Two
), (
Three
)) ] ``` To render children at the same DOM level as `` 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.wrapperProps Props to apply to the wrapper element when `wrapper` is used. ```tsx # Hello World ``` ### 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 `` 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`: ```html ``` ````tsx import { Markdown, RuleType } from 'markdown-to-jsx' const mdContainingFencedCodeBlock = '```js\nconsole.log("Hello world!");\n```\n' function App() { return ( ) } function SyntaxHighlightedCode(props) { const ref = React.useRef(null) React.useEffect(() => { if (ref.current && props.className?.includes('lang-') && window.hljs) { window.hljs.highlightElement(ref.current) // hljs won't reprocess the element unless this attribute is removed ref.current.removeAttribute('data-highlighted') } }, [props.className, props.children]) return } ```` ### Handling shortcodes For Slack-style messaging with arbitrary shortcodes like `:smile:`, you can use `options.renderRule` to hook into the plain text rendering and adjust things to your liking, for example: ```tsx import Markdown, { RuleType } from 'markdown-to-jsx' const shortcodeMap = { smile: '🙂', } const detector = /(:[^:]+:)/g const replaceEmoji = (text: string): React.ReactNode => { return text.split(detector).map((part, index) => { if (part.startsWith(':') && part.endsWith(':')) { const shortcode = part.slice(1, -1) return {shortcodeMap[shortcode] || part} } return part }) } function Example() { return ( {`On a beautiful summer day, all I want to do is :smile:.`} ) } ``` 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! ### 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. ### AST Anatomy The Abstract Syntax Tree (AST) is a structured representation of parsed markdown. Each node in the AST has a `type` property that identifies its kind, and type-specific properties. **Important:** The first node in the AST is typically a `RuleType.refCollection` node that contains all reference definitions found in the document, including footnotes (stored with keys prefixed with `^`). This node is skipped during rendering but is useful for accessing reference data. Footnotes are automatically extracted from the refCollection and rendered in a `` element by both `compiler()` and `astToJSX()`. #### Node Types The AST consists of the following node types (use `RuleType` to check node types): **Block-level nodes:** - `RuleType.heading` - Headings (`# Heading`) ```tsx { type: RuleType.heading, level: 1, id: "heading", children: [...] } ``` - `RuleType.paragraph` - Paragraphs ```tsx { type: RuleType.paragraph, children: [...] } ``` - `RuleType.codeBlock` - Fenced code blocks (```) ```tsx { type: RuleType.codeBlock, lang: "javascript", text: "code content" } ``` - `RuleType.blockQuote` - Blockquotes (`>`) ```tsx { type: RuleType.blockQuote, children: [...], alert?: "note" } ``` - `RuleType.orderedList` / `RuleType.unorderedList` - Lists ```tsx { type: RuleType.orderedList, items: [[...]], start?: 1 } { type: RuleType.unorderedList, items: [[...]] } ``` - `RuleType.table` - Tables ```tsx { type: RuleType.table, header: [...], cells: [[...]], align: [...] } ``` - `RuleType.htmlBlock` - HTML blocks and JSX components ```tsx { type: RuleType.htmlBlock, tag: "div", attrs: {}, rawAttrs?: string, children?: ASTNode[], verbatim?: boolean, rawText?: string, text?: string // @deprecated - use rawText instead } ``` **Note (v9.1+):** JSX components with blank lines between opening/closing tags now properly nest children instead of creating sibling nodes. **HTML Block Parsing (v9.2+):** HTML blocks are always fully parsed into the `children` property, even when marked as `verbatim`. The `verbatim` flag acts as a rendering hint (default renderers use `rawText` for verbatim blocks to maintain CommonMark compliance), but `renderRule` implementations can access the fully parsed AST in `children` for all HTML blocks. The `rawText` field contains the original raw HTML content for verbatim blocks, while `rawAttrs` contains the original attribute string. **Inline nodes:** - `RuleType.text` - Plain text ```tsx { type: RuleType.text, text: "Hello world" } ``` - `RuleType.textFormatted` - Bold, italic, etc. ```tsx { type: RuleType.textFormatted, tag: "strong", children: [...] } ``` - `RuleType.codeInline` - Inline code (`` ` ``) ```tsx { type: RuleType.codeInline, text: "code" } ``` - `RuleType.link` - Links ```tsx { type: RuleType.link, target: "https://example.com", children: [...] } ``` - `RuleType.image` - Images ```tsx { type: RuleType.image, target: "image.png", alt: "description" } ``` **Other nodes:** - `RuleType.breakLine` - Hard line breaks (` `) - `RuleType.breakThematic` - Horizontal rules (`---`) - `RuleType.gfmTask` - GFM task list items (`- [ ]`) - `RuleType.ref` - Reference definition node (not rendered, stored in refCollection) - `RuleType.refCollection` - Reference definitions collection (appears at AST root, includes footnotes with `^` prefix) - `RuleType.footnote` - Footnote definition node (not rendered, stored in refCollection) - `RuleType.footnoteReference` - Footnote reference (`[^identifier]`) - `RuleType.frontmatter` - YAML frontmatter blocks ```tsx { type: RuleType.frontmatter, text: "---\ntitle: My Title\n---" } ``` - `RuleType.htmlComment` - HTML comment nodes ```tsx { type: RuleType.htmlComment, text: "" } ``` - `RuleType.htmlSelfClosing` - Self-closing HTML tags ```tsx { type: RuleType.htmlSelfClosing, tag: "img", attrs: { src: "image.png" } } ``` **JSX Prop Parsing (v9.1+):** The parser intelligently parses JSX prop values: - Arrays/objects are parsed via `JSON.parse()`: `rows={[["a", "b"]]}` → `attrs.rows = [["a", "b"]]` - Functions are kept as strings for security: `onClick={() => ...}` → `attrs.onClick = "() => ..."` - Booleans are parsed: `enabled={true}` → `attrs.enabled = true` - The original raw attribute string is preserved in `rawAttrs` field #### Example AST Structure ````tsx import { parser, RuleType } from 'markdown-to-jsx' const ast = parser(`# Hello World This is a **paragraph** with [a link](https://example.com). [linkref]: https://example.com ```javascript console.log('code') ``` `) // AST structure: [ // Reference collection (first node, if references exist) { type: RuleType.refCollection, refs: { linkref: { target: 'https://example.com', title: undefined }, }, }, { type: RuleType.heading, level: 1, id: 'hello-world', children: [{ type: RuleType.text, text: 'Hello World' }], }, { type: RuleType.paragraph, children: [ { type: RuleType.text, text: 'This is a ' }, { type: RuleType.textFormatted, tag: 'strong', children: [{ type: RuleType.text, text: 'paragraph' }], }, { type: RuleType.text, text: ' with ' }, { type: RuleType.link, target: 'https://example.com', children: [{ type: RuleType.text, text: 'a link' }], }, { type: RuleType.text, text: '.' }, ], }, { type: RuleType.codeBlock, lang: 'javascript', text: "console.log('code')", }, ] ```` #### Type Checking Use the `RuleType` enum to identify AST nodes: ```tsx import { RuleType } from 'markdown-to-jsx' if (node.type === RuleType.heading) { const heading = node as MarkdownToJSX.HeadingNode console.log(`Heading level ${heading.level}: ${heading.id}`) } ``` **When to use `compiler` vs `parser` vs ``:** - Use `` when you need a simple React component that renders markdown to JSX. - Use `compiler` when you need React JSX output from markdown (the component uses this internally). - Use `parser` + `astToJSX` when you need the AST for custom processing before rendering to JSX, or just the AST itself. ### Gotchas **JSX prop parsing (v9.1+):** Arrays and objects in JSX props are automatically parsed: ```tsx // In markdown:

// In your component (v9.1+): const Table = ({ columns, data, ...props }) => { // columns is already an array: ["Name", "Age"] // data is already an array: [["Alice", 30], ["Bob", 25]] // No JSON.parse needed! } // For backwards compatibility, check types: const Table = ({ columns, data, ...props }) => { const parsedColumns = typeof columns === 'string' ? JSON.parse(columns) : columns const parsedData = typeof data === 'string' ? JSON.parse(data) : data } ``` **Function props are kept as strings** for security. Use [renderRule](#optionsrenderrule) for case-by-case handling, or see [evalUnserializableExpressions](#optionsevalunserializableexpressions) for opt-in eval. **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 ```js var code = here(); ``` ```` ## Changelog See [Github Releases](https://github.com/quantizor/markdown-to-jsx/releases). ## Donate Like this library? It's developed entirely on a volunteer basis; chip in a few bucks if you can via the [Sponsor link](https://github.com/sponsors/quantizor)!

Table of Contents

Hello world!