Rendering Markdown in React: markdown-to-jsx vs react-markdown

markdown-to-jsx is a gfm+commonmark compliant markdown parser and compiler toolchain for JavaScript and TypeScript-based projects. It is extremely fast, capable of processing large documents fast enough for real-time interactivity.

Some special features of the library:

• Arbitrary HTML is supported and parsed into the appropriate JSX representation without dangerouslySetInnerHTML

• Any HTML tags rendered by the compiler and/or <Markdown> component can be overridden to include additional props or even a different HTML representation entirely.

• All GFM special syntaxes are supported, including tables, task lists, strikethrough, autolinks, tag filtering, and more.

• Fenced code blocks with highlight.js support; see Syntax highlighting for instructions on setting up highlight.js.

Table of Contents

• Upgrading
  • From v8.x to v9.x
  • From v7.x to v8.x
• Installation
• Usage
  • Entry Points
    • Main
    • React
      • React Server Components RSC
    • React Native
    • SolidJS
    • Vue.js
    • HTML
    • Markdown
  • Library Options
    • All Options
    • options.createElement
    • options.forceWrapper
    • options.overrides
    • options.evalUnserializableExpressions
    • options.ignoreHTMLBlocks
    • options.renderRule
    • options.sanitizer
    • options.slugify
    • options.wrapper
      • Other useful recipes
    • options.wrapperProps
  • Syntax highlighting
  • Handling shortcodes
  • Streaming Markdown
  • Usage with Preact
  • AST Anatomy
    • Node Types
    • Example AST Structure
    • Type Checking
  • Gotchas
• Changelog
• Donate

Upgrading

From v8.x to v9.x

Breaking Changes:

• ast option removed: The ast: true option on compiler() has been removed. Use the new parser() function instead to access the AST directly.

/** 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.

/** 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.

/** v8 */ tags rendered as JSX elements
/** v9 */ tags escaped by default
compiler('<script>alert("xss")</script>') // <span>&lt;script&gt;</span>

/** Restore old behavior */
compiler('<script>alert("xss")</script>', { tagfilter: false })

New Features:

• New parser function: Provides direct access to the parsed AST without rendering. This is the recommended way to get AST nodes.

• New entry points: React-specific, HTML-specific, and markdown-specific entry points are now available for better tree-shaking and separation of concerns.

// React-specific usage
import Markdown, { compiler, parser } from 'markdown-to-jsx/react'

// HTML string output
import { compiler, astToHTML, parser } from 'markdown-to-jsx/html'

// Markdown string output (round-trip compilation)
import { compiler, astToMarkdown, parser } from 'markdown-to-jsx/markdown'

Migration Guide:

1. Replace compiler(..., { ast: true }) with parser():

/** v8 */ compiler(markdown, { ast: true })
/** v9 */ parser(markdown)

2. Migrate React imports to /react entry point (optional but recommended):

/** 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.

/** v8 */ compiler('≤ symbol', { namedCodesToUnicode: { le: '\u2264' } })
/** v9 */ compiler('≤ 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.

/** v7 */ MarkdownToJSX.ParserResult[]
/** v8+ */ MarkdownToJSX.ASTNode[]

/** v7 */ RuleType.textBolded
/** v8+ */ RuleType.textFormatted && node.bold

Installation

Install markdown-to-jsx with your favorite package manager.

npm i markdown-to-jsx

Usage

markdown-to-jsx exports a React component by default for easy JSX composition:

ES6-style usage*:

import Markdown from 'markdown-to-jsx'
import React from 'react'
import { render } from 'react-dom'

render(<Markdown># Hello world!</Markdown>, document.body)

/*
    renders:

    <h1>Hello world!</h1>
 */

* NOTE: JSX does not natively preserve newlines in multiline text. In general, writing markdown directly in JSX is discouraged and it's a better idea to keep your content in separate .md files and require them, perhaps using webpack's raw-loader.

Entry Points

markdown-to-jsx provides multiple entry points for different use cases:

Main

The legacy default entry point exports everything, including the React compiler and component:

import Markdown, { compiler, parser } from 'markdown-to-jsx'

The React code in this entry point is deprecated and will be removed in a future major release, migrate to markdown-to-jsx/react.

React

For React-specific usage, import from the /react entry point:

import Markdown, { compiler, parser, astToJSX } from 'markdown-to-jsx/react'

const jsxElement = compiler('# Hello world')

function App() {
  return <Markdown children="# Hello world" />
}

/** Or use parser + astToJSX */
const ast = parser('# Hello world')
const jsxElement2 = astToJSX(ast)

React Server Components (RSC)

The Markdown component automatically detects whether it's running in a React Server Component (RSC) or client environment and adapts accordingly. No 'use client' directive is required.

Server Component (RSC) usage:

// Server Component - works automatically
import Markdown from 'markdown-to-jsx/react'

export default async function Page() {
  const content = await fetchMarkdownContent()
  return <Markdown>{content}</Markdown>
}

Client Component usage:

// Client Component - also works automatically
'use client'
import Markdown from 'markdown-to-jsx/react'

export function ClientMarkdown({ content }: { content: string }) {
  return <Markdown>{content}</Markdown>
}

Notes:

• MarkdownProvider and MarkdownContext are client-only and become no-ops in RSC environments
• RSC rendering provides better performance by avoiding client-side hydration
• The component maintains identical output in both environments
• No migration needed for existing code

React Native

For React Native usage, import from the /native entry point:

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)
  },
})

const markdown = `# Hello world

This is a [link](https://example.com) with **bold** and *italic* text.
`

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>
  )
}

React Native-specific options:

• 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)

HTML Tag Mapping: HTML tags are automatically mapped to React Native components:

• <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

Note: Links are underlined by default for better accessibility and discoverability. You can override this via the styles.link option.

SolidJS

For SolidJS usage, import from the /solid entry point:

import Markdown, {
  compiler,
  parser,
  astToJSX,
  MarkdownProvider,
} from 'markdown-to-jsx/solid'
import { createSignal } from 'solid-js'

// Static content
const solidElement = compiler('# Hello world')

function App() {
  return <Markdown children="# Hello world" />
}

// Reactive content (automatically updates when content changes)
function ReactiveApp() {
  const [content, setContent] = createSignal('# Hello world')
  return <Markdown>{content}</Markdown>
}

// Or use parser + astToJSX
const ast = parser('# Hello world')
const solidElement2 = astToJSX(ast)

// Use context for default options
function AppWithContext() {
  return (
    <MarkdownProvider options={{ sanitizer: customSanitizer }}>
      <Markdown># Content</Markdown>
    </MarkdownProvider>
  )
}

SolidJS-specific features:

• 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

Vue.js

For Vue.js 3 usage, import from the /vue entry point:

import Markdown, { compiler, parser, astToJSX } from 'markdown-to-jsx/vue'
import { h } from 'vue'

// Using compiler
const vnode = compiler('# Hello world')

// Using component
<Markdown children="# Hello world" />

// Or use parser + astToJSX
const ast = parser('# Hello world')
const vnode2 = astToJSX(ast)

Vue.js-specific features:

• 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 components

HTML

For HTML string output (server-side rendering), import from the /html entry point:

import { compiler, html, parser } from 'markdown-to-jsx/html'

const htmlString = compiler('# Hello world')

/** Or use parser + html */
const ast = parser('# Hello world')
const htmlString2 = html(ast)

Markdown

For markdown-to-markdown compilation (normalization and formatting), import from the /markdown entry point:

import { compiler, astToMarkdown, parser } from 'markdown-to-jsx/markdown'

const normalizedMarkdown = compiler('# Hello  world\n\nExtra spaces!')

/** Or work with AST */
const ast = parser('# Hello  world')
const normalizedMarkdown2 = astToMarkdown(ast)

Library Options

All Options

options.createElement

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]:

import Markdown from 'markdown-to-jsx'
import React from 'react'
import { render } from 'react-dom'

const md = `
# Hello world
`

render(
  <Markdown
    children={md}
    options={{
      createElement(type, props, children) {
        return (
          <div className="parent">
            {React.createElement(type, props, children)}
          </div>
        )
      },
    }}
  />,
  document.body
)

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 `forceWrapper` with a single, inline child…
<Markdown options={{ wrapper: 'aside', forceWrapper: true }}>
  Mumble, mumble…
</Markdown>

// renders

<aside>Mumble, mumble…</aside>

options.overrides

Override HTML tag rendering or render custom React components. Three use cases:

1. Remove tags: Return null to completely remove tags (beyond tagfilter escaping):

<Markdown options={{ overrides: { iframe: () => null } }}>
  <iframe src="..."></iframe>
</Markdown>

2. Override HTML tags: Change component, props, or both:

const MyParagraph = ({ children, ...props }) => <div {...props}>{children}</div>

<Markdown options={{ overrides: { h1: { component: MyParagraph, props: { className: 'foo' } } } }}>
  # Hello
</Markdown>

/** Simplified */ { overrides: { h1: MyParagraph } }

3. Render React components: Use custom components in markdown:

import DatePicker from './date-picker'

const md = `<DatePicker timezone="UTC+5" startTime={1514579720511} />`

<Markdown options={{ overrides: { DatePicker } }}>{md}</Markdown>

Important notes:

• JSX props are intelligently parsed (v9.1+):
  • Arrays and objects: data={[1, 2, 3]} → parsed as [1, 2, 3]
  • Booleans: enabled={true} → parsed as true
  • Functions: onClick={() => ...} → kept as string for security (use renderRule for case-by-case handling, or see evalUnserializableExpressions)
  • Complex expressions: value={someVar} → kept as string
• 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.evalUnserializableExpressions

⚠️ SECURITY WARNING: STRONGLY DISCOURAGED FOR USER INPUTS

When enabled, attempts to eval expressions in JSX props that cannot be serialized as JSON (functions, variables, complex expressions). This uses eval() which can execute arbitrary code.

By default (recommended), unserializable expressions are kept as strings for security:

import { parser } from 'markdown-to-jsx'

const ast = parser('<Button onClick={() => alert("hi")} />')
// ast[0].attrs.onClick === "() => alert(\"hi\")" (string, safe)

// Arrays and objects are automatically parsed (no eval needed):
const ast2 = parser('<Table data={[1, 2, 3]} />')
// ast2[0].attrs.data === [1, 2, 3] (parsed via JSON.parse)

ONLY enable this option when:

• The markdown source is completely trusted (e.g., your own documentation)
• You control all JSX components and their props
• The content is NOT user-generated or user-editable

DO NOT enable this option when:

• Processing user-submitted markdown
• Rendering untrusted content
• Building public-facing applications with user content

Example of the danger:

// User-submitted markdown with malicious code
const userMarkdown = '<Component onClick={() => fetch("/admin/delete-all")} />'

// ❌ DANGEROUS - function will be executable
parser(userMarkdown, { evalUnserializableExpressions: true })

// ✅ SAFE - function kept as string
parser(userMarkdown) // default behavior

Safe alternative: Use renderRule for case-by-case handling:

// Instead of eval'ing arbitrary expressions, handle them selectively in renderRule:
const handlers = {
  handleClick: () => console.log('clicked'),
  handleSubmit: () => console.log('submitted'),
}

compiler(markdown, {
  renderRule(next, node) {
    if (
      node.type === RuleType.htmlBlock &&
      typeof node.attrs?.onClick === 'string'
    ) {
      // Option 1: Named handler lookup (safest)
      const handler = handlers[node.attrs.onClick]
      if (handler) {
        return <button onClick={handler}>{/* ... */}</button>
      }

      // Option 2: Selective eval with allowlist (still risky)
      if (
        node.tag === 'TrustedComponent' &&
        node.attrs.onClick.startsWith('() =>')
      ) {
        try {
          const fn = eval(`(${node.attrs.onClick})`)
          return <button onClick={fn}>{/* ... */}</button>
        } catch (e) {
          // Handle error
        }
      }
    }
    return next()
  },
})

This approach gives you full control over which expressions are evaluated and under what conditions.

options.ignoreHTMLBlocks

When enabled, the parser will not attempt to parse HTML blocks. HTML syntax will be treated as plain text and rendered as-is.

<Markdown options={{ ignoreHTMLBlocks: true }}>
  {'<div class="custom">This will be rendered as text</div>'}
</Markdown>

options.renderRule

Supply your own rendering function that can selectively override how rules are rendered (note, this is different than options.overrides which operates at the HTML tag level and is more general). The renderRule function always executes before any other rendering code, giving you full control over how nodes are rendered, including normally-skipped nodes like ref, footnote, and frontmatter.

You can use this functionality to do pretty much anything with an established AST node; here's an example of selectively overriding the "codeBlock" rule to process LaTeX syntax using the @matejmazur/react-katex library:

import Markdown, { RuleType } from 'markdown-to-jsx'
import TeX from '@matejmazur/react-katex'

const exampleContent =
  'Some important formula:\n\n```latex\nmathbb{N} = { a in mathbb{Z} : a > 0 }\n```\n'

function App() {
  return (
    <Markdown
      children={exampleContent}
      options={{
        renderRule(next, node, renderChildren, state) {
          if (node.type === RuleType.codeBlock && node.lang === 'latex') {
            return (
              <TeX as="div" key={state.key}>{String.raw`${node.text}`}</TeX>
            )
          }

          return next()
        },
      }}
    />
  )
}

Accessing parsed HTML content: For HTML blocks (like <script>, <style>, <pre>), renderRule can access the fully parsed AST in children:

<Markdown
  options={{
    renderRule(next, node, renderChildren) {
      if (node.type === RuleType.htmlBlock && node.tag === 'script') {
        // Access parsed children for custom rendering
        const parsedContent = node.children || []
        return <CustomScript content={parsedContent} />
      }
      return next()
    },
  }}
>
  <script>Hello **world**</script>
</Markdown>

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:

// sanitizer in this situation would receive:
// ('javascript:alert("foo")', 'a', 'href')

<Markdown options={{ sanitizer: (value, tag, attribute) => value }}>
  {`[foo](javascript:alert("foo"))`}
</Markdown>

// or

compiler('[foo](javascript:alert("foo"))', {
  sanitizer: value => value,
})

options.slugify

By default, a lightweight deburring function 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:

<Markdown options={{ slugify: str => str }}># 中文</Markdown>
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.

const str = '# Heck Yes\n\nThis is great!'

<Markdown options={{ wrapper: 'article' }}>{str}</Markdown>

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.

compiler('One\n\nTwo\n\nThree', { wrapper: null })[
  /** Returns */ ((<p>One</p>), (<p>Two</p>), (<p>Three</p>))
]

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.wrapperProps

Props to apply to the wrapper element when wrapper is used.

<Markdown
  options={{
    wrapper: 'article',
    wrapperProps: { className: 'post', 'data-testid': 'markdown-content' },
  }}
>
  # Hello World
</Markdown>

Syntax highlighting

When using fenced code blocks 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:

<!-- Add the following tags to your page <head> to automatically load hljs and styles: -->
<link
  rel="stylesheet"
  href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/styles/obsidian.min.css"
/>

<script
  crossorigin
  src="https://unpkg.com/@highlightjs/cdn-assets@11.9.0/highlight.min.js"
></script>

import { Markdown, RuleType } from 'markdown-to-jsx'

const mdContainingFencedCodeBlock = '```js\nconsole.log("Hello world!");\n```\n'

function App() {
  return (
    <Markdown
      children={mdContainingFencedCodeBlock}
      options={{
        overrides: {
          code: SyntaxHighlightedCode,
        },
      }}
    />
  )
}

function SyntaxHighlightedCode(props) {
  const ref = React.useRef<HTMLElement | null>(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 <code {...props} ref={ref} />
}

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:

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 <span key={index}>{shortcodeMap[shortcode] || part}</span>
    }

    return part
  })
}

function Example() {
  return (
    <Markdown
      options={{
        renderRule(next, node) {
          if (node.type === RuleType.text && detector.test(node.text)) {
            return replaceEmoji(node.text)
          }

          return next()
        },
      }}
    >
      {`On a beautiful summer day, all I want to do is :smile:.`}
    </Markdown>
  )
}

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!

Streaming Markdown

When rendering markdown content that arrives incrementally (e.g., from an AI/LLM API, WebSocket, or Server-Sent Events), you may notice raw markdown syntax briefly appearing before it renders properly. This happens because incomplete syntax like **bold text or <CustomComponent>partial content gets rendered as text before the closing delimiter arrives.

The optimizeForStreaming option solves this by detecting incomplete markdown structures and returning null (React) or empty string (HTML) until the content is complete:

import Markdown from 'markdown-to-jsx/react'

function StreamingMarkdown({ content }) {
  return <Markdown options={{ optimizeForStreaming: true }}>{content}</Markdown>
}

LLM / AI chatbot integration:

A common pattern is rendering streamed responses from LLM APIs (OpenAI, Anthropic, etc.) where tokens arrive one at a time. Without optimizeForStreaming, users see distracting flashes of raw markdown syntax between each token. With it enabled, incomplete structures are suppressed until the closing delimiter arrives, producing a smooth reading experience:

import Markdown from 'markdown-to-jsx/react'
import { useState, useEffect } from 'react'

function ChatMessage({ stream }) {
  const [content, setContent] = useState('')

  useEffect(() => {
    // Accumulate tokens from the LLM stream
    stream.on('token', token => setContent(prev => prev + token))
  }, [stream])

  return <Markdown options={{ optimizeForStreaming: true }}>{content}</Markdown>
}

What it suppresses:

• Unclosed HTML tags (<div>content without </div>)
• Incomplete tag syntax (<div attr="value without closing >)
• Unclosed HTML comments (<!-- comment without -->)
• Unclosed inline code (`code without closing backtick)
• Unclosed bold/italic (**text or *text without closing)
• Unclosed strikethrough (~~text without closing ~~)
• Unclosed links ([text](url without closing ))
• Incomplete tables (header and separator row without any data rows)

What renders normally (content visible as it streams):

• Fenced code blocks - content is displayed as it arrives, waiting for closing fence

Usage with Preact

Everything will work just fine! Simply Alias react to preact/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 <footer> 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)

  { type: RuleType.heading, level: 1, id: "heading", children: [...] }
  

• RuleType.paragraph - Paragraphs

  { type: RuleType.paragraph, children: [...] }
  

• RuleType.codeBlock - Fenced code blocks (```)

  { type: RuleType.codeBlock, lang: "javascript", text: "code content", attrs?: { "data-line": "1" } }
  

• RuleType.blockQuote - Blockquotes (>)

  { type: RuleType.blockQuote, children: [...], alert?: "note" }
  

• RuleType.orderedList / RuleType.unorderedList - Lists

  { type: RuleType.orderedList, items: [[...]], start?: 1 }
  { type: RuleType.unorderedList, items: [[...]] }
  

• RuleType.table - Tables

  { type: RuleType.table, header: [...], cells: [[...]], align: [...] }
  

• RuleType.htmlBlock - HTML blocks and JSX components

  { type: RuleType.htmlBlock, tag: "div", attrs?: Record<string, any>, children?: ASTNode[] }
  

  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. The renderRule callback can access the fully parsed AST in children for all HTML blocks.

Inline nodes:

• RuleType.text - Plain text

  { type: RuleType.text, text: "Hello world" }
  

• RuleType.textFormatted - Bold, italic, etc.

  { type: RuleType.textFormatted, tag: "strong", children: [...] }
  

• RuleType.codeInline - Inline code (`)

  { type: RuleType.codeInline, text: "code" }
  

• RuleType.link - Links

  { type: RuleType.link, target: "https://example.com", title?: "Link title", children: [...] }
  

• RuleType.image - Images

  { type: RuleType.image, target: "image.png", alt?: "description", title?: "Image title" }
  

Other nodes:

• RuleType.breakLine - Hard line breaks ( )
• RuleType.breakThematic - Horizontal rules (---)
• RuleType.gfmTask - GFM task list items (- [ ])

  { type: RuleType.gfmTask, completed: false }
  

• RuleType.ref - Reference definition node (not rendered, stored in refCollection)
• RuleType.refCollection - Reference definitions collection (appears at AST root, includes footnotes with ^ prefix)

  { type: RuleType.refCollection, refs: { "label": { target: "url", title: "title" } } }
  

• RuleType.footnote - Footnote definition node (not rendered, stored in refCollection)
• RuleType.footnoteReference - Footnote reference ([^identifier])

  { type: RuleType.footnoteReference, target: "#fn-identifier", text: "1" }
  

• RuleType.frontmatter - YAML frontmatter blocks

  { type: RuleType.frontmatter, text: "---\ntitle: My Title\n---" }
  

• RuleType.htmlComment - HTML comment nodes

  { type: RuleType.htmlComment, text: "comment text" }
  

• RuleType.htmlSelfClosing - Self-closing HTML tags

  { 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

Example AST Structure

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:

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 <Markdown>:

• Use <Markdown> 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:

// In markdown:
<Table
  columns={['Name', 'Age']}
  data={[
    ['Alice', 30],
    ['Bob', 25],
  ]}
/>

// 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 for case-by-case handling, or see evalUnserializableExpressions 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:

<div>
```js
var code = here();
```
</div>

Changelog

See Github 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!