markdown-to-jsx 8.0.0 → 9.0.0

package/README.md

@@ -1,20 +1,38 @@
-**markdown-to-jsx**
+[![npm version](https://badge.fury.io/js/markdown-to-jsx.svg)](https://badge.fury.io/js/markdown-to-jsx) [![downloads](https://badgen.net/npm/dy/markdown-to-jsx)](https://npm-stat.com/charts.html?package=markdown-to-jsx)
 
-The most lightweight, customizable React markdown component.
+`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.
 
-[![npm version](https://badge.fury.io/js/markdown-to-jsx.svg)](https://badge.fury.io/js/markdown-to-jsx) [![downloads](https://badgen.net/npm/dy/markdown-to-jsx)](https://npm-stat.com/charts.html?package=markdown-to-jsx)
+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](https://highlightjs.org/) support; see [Syntax highlighting](#syntax-highlighting) for instructions on setting up highlight.js.
+
+<h2>Table of Contents</h2>
 
 <!-- TOC -->
 
 - [Upgrading](#upgrading)
+  - [From v8.x to v9.x](#from-v8x-to-v9x)
   - [From v7.x to v8.x](#from-v7x-to-v8x)
 - [Installation](#installation)
 - [Usage](#usage)
-  - [Parsing Options](#parsing-options)
+  - [Entry Points](#entry-points)
+    - [Main](#main)
+    - [React](#react)
+    - [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)
     - [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)
@@ -24,43 +42,124 @@ The most lightweight, customizable React markdown component.
     - [options.renderRule](#optionsrenderrule)
     - [options.sanitizer](#optionssanitizer)
     - [options.slugify](#optionsslugify)
-    - [options.namedCodesToUnicode](#optionsnamedcodestounicode)
     - [options.disableAutoLink](#optionsdisableautolink)
     - [options.disableParsingRawHTML](#optionsdisableparsingrawhtml)
-    - [options.ast](#optionsast)
+    - [options.tagfilter](#optionstagfilter)
   - [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)
-- [Gotchas](#gotchas)
-  - [Passing props to stringified React components](#passing-props-to-stringified-react-components)
-  - [Significant indentation inside arbitrary HTML](#significant-indentation-inside-arbitrary-html)
+  - [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)
-- [Using The Compiler Directly](#using-the-compiler-directly)
 - [Changelog](#changelog)
 - [Donate](#donate)
 
 <!-- /TOC -->
 
----
+## Upgrading
 
-`markdown-to-jsx` offers the following additional benefits over simple markdown parsing:
+### From v8.x to v9.x
 
-- Arbitrary HTML is supported and parsed into the appropriate JSX representation
-  without `dangerouslySetInnerHTML`
+**Breaking Changes:**
 
-- 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.
+- **`ast` option removed**: The `ast: true` option on `compiler()` has been removed. Use the new `parser()` function instead to access the AST directly.
 
-- GFM task list support.
+```typescript
+// Before (v8)
+import { compiler } from 'markdown-to-jsx'
+const ast = compiler('# Hello world', { ast: true })
 
-- Fenced code blocks with [highlight.js](https://highlightjs.org/) support; see [Syntax highlighting](#syntax-highlighting) for instructions on setting up highlight.js.
+// After (v9)
+import { parser } from 'markdown-to-jsx'
+const ast = parser('# Hello world')
+```
 
-All this clocks in at around 7.5 kB gzipped, which is a fraction of the size of most other React markdown components.
+- **`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.
 
-Requires React >= 0.14.
+```typescript
+// Before (v8)
+import { compiler } from 'markdown-to-jsx'
+compiler('&le; symbol', { namedCodesToUnicode: { le: '\u2264' } })
 
-## Upgrading
+// After (v9)
+import { compiler } from 'markdown-to-jsx'
+compiler('&le; symbol') // All entities supported automatically
+```
+
+- **`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
+
+// After (v9) - tags escaped by default
+compiler('<script>alert("xss")</script>') // Renders as <span>&lt;script&gt;</span>
+
+// To 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.
+
+```typescript
+// 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()`**:
+
+```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)
+```
+
+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'
+```
+
+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
+```
+
+**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.
+
+<details>
+<summary>### Older Migration Guides</summary>
 
 ### From v7.x to v8.x
 
@@ -86,6 +185,8 @@ if (node.type === RuleType.textBolded) { ... }
 if (node.type === RuleType.textFormatted && node.bold) { ... }
 ```
 
+</details>
+
 ## Installation
 
 Install `markdown-to-jsx` with your favorite package manager.
@@ -100,7 +201,7 @@ npm i markdown-to-jsx
 
 ES6-style usage\*:
 
-```jsx
+```tsx
 import Markdown from 'markdown-to-jsx'
 import React from 'react'
 import { render } from 'react-dom'
@@ -116,7 +217,75 @@ render(<Markdown># Hello world!</Markdown>, document.body)
 
 \* **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](https://github.com/webpack-contrib/raw-loader).**
 
-### Parsing Options
+### 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:
+
+```tsx
+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:
+
+```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} />
+}
+
+// Or use parser + astToJSX for total control
+const ast = parser('# Hello world')
+const jsxElement2 = astToJSX(ast)
+```
+
+#### HTML
+
+For HTML string output (server-side rendering), import from the `/html` 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
 
@@ -134,37 +303,36 @@ But this string would be considered "block" due to the existence of a header tag
 
 However, if you really want all input strings to be treated as "block" layout, simply pass `options.forceBlock = true` like this:
 
-```jsx
-;<Markdown options={{ forceBlock: true }}>Hello there old chap!</Markdown>
+```tsx
+<Markdown options={{ forceBlock: true }}>Hello there old chap!</Markdown>
 
 // or
 
 compiler('Hello there old chap!', { forceBlock: true })
 
 // renders
-;<p>Hello there old chap!</p>
+<p>Hello there old chap!</p>
 ```
 
 #### options.forceInline
 
 The inverse is also available by passing `options.forceInline = true`:
 
-```jsx
-;<Markdown options={{ forceInline: true }}># You got it babe!</Markdown>
+```tsx
+<Markdown options={{ forceInline: true }}># You got it babe!</Markdown>
 
 // or
-
 compiler('# You got it babe!', { forceInline: true })
 
 // renders
-;<span># You got it babe!</span>
+<span># You got it babe!</span>
 ```
 
 #### 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.
 
-```jsx
+```tsx
 const str = '# Heck Yes\n\nThis is great!'
 
 <Markdown options={{ wrapper: 'article' }}>
@@ -187,7 +355,7 @@ compiler(str, { wrapper: 'article' });
 
 To get an array of children back without a wrapper, set `wrapper` to `null`. This is particularly useful when using `compiler(…)` directly.
 
-```jsx
+```tsx
 compiler('One\n\nTwo\n\nThree', { wrapper: null })
 
 // returns
@@ -196,11 +364,29 @@ compiler('One\n\nTwo\n\nThree', { wrapper: null })
 
 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.
+
+```tsx
+<Markdown options={{
+  wrapper: 'article',
+  wrapperProps: { className: 'post', 'data-testid': 'markdown-content' }
+}}>
+  # Hello World
+</Markdown>
+
+// renders
+<article class="post" data-testid="markdown-content">
+  <h1>Hello World</h1>
+</article>
+```
+
 #### 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`.
 
-```jsx
+```tsx
 // Using `forceWrapper` with a single, inline child…
 <Markdown options={{ wrapper: 'aside', forceWrapper: true }}>
   Mumble, mumble…
@@ -213,7 +399,15 @@ By default, the compiler does not wrap the rendered contents if there is only a
 
 #### options.overrides - Void particular banned tags
 
-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. It is recommended to void `script`, `iframe`, `object`, and `style` tags to avoid XSS attacks when working with user-generated content. For example, to void the `iframe` tag:
+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.
+
+**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
+
+For example, to void the `iframe` tag:
 
 ```tsx
 import Markdown from 'markdown-to-jsx'
@@ -230,13 +424,13 @@ render(
 // renders: ""
 ```
 
-The library does not void any tags by default to avoid surprising behavior for personal use cases.
+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.
 
-```jsx
+```tsx
 import Markdown from 'markdown-to-jsx'
 import React from 'react'
 import { render } from 'react-dom'
@@ -304,7 +498,7 @@ One of the most interesting use cases enabled by the HTML syntax processing in `
 
 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:
 
-```jsx
+```tsx
 import Markdown from 'markdown-to-jsx'
 import React from 'react'
 import { render } from 'react-dom'
@@ -339,7 +533,7 @@ render(
 
 In the following case, `DatePicker` could simply run `parseInt()` on the passed `startTime` for example:
 
-```jsx
+```tsx
 import Markdown from 'markdown-to-jsx'
 import React from 'react'
 import { render } from 'react-dom'
@@ -376,7 +570,7 @@ render(
 
 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:
 
-```jsx
+```tsx
 import Markdown from 'markdown-to-jsx'
 import React from 'react'
 import { render } from 'react-dom'
@@ -496,7 +690,7 @@ By default a lightweight URL sanitizer function is provided to avoid common atta
 
 This can be overridden and replaced with a custom sanitizer if desired via `options.sanitizer`:
 
-```jsx
+```tsx
 // sanitizer in this situation would receive:
 // ('javascript:alert("foo")', 'a', 'href')
 
@@ -513,9 +707,9 @@ compiler('[foo](javascript:alert("foo"))', {
 
 #### options.slugify
 
-By default, a [lightweight deburring function](https://github.com/probablyup/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:
+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:
 
-```jsx
+```tsx
 <Markdown options={{ slugify: str => str }}># 中文</Markdown>
 
 // or
@@ -528,44 +722,11 @@ compiler('# 中文', { slugify: str => str })
 
 The original function is available as a library export called `slugify`.
 
-#### options.namedCodesToUnicode
-
-By default only a couple of named html codes are converted to unicode characters:
-
-- `&` (`&amp;`)
-- `'` (`&apos;`)
-- `>` (`&gt;`)
-- `<` (`&lt;`)
-- ` ` (`&nbsp;`)
-- `"` (`&quot;`)
-
-Some projects require to extend this map of named codes and unicode characters. To customize this list with additional html codes pass the option namedCodesToUnicode as object with the code names needed as in the example below:
-
-```jsx
-<Markdown options={{ namedCodesToUnicode: {
-    le: '\u2264',
-    ge: '\u2265',
-    '#39': '\u0027',
-} }}>This text is &le; than this text.</Markdown>;
-
-// or
-
-compiler('This text is &le; than this text.', namedCodesToUnicode: {
-    le: '\u2264',
-    ge: '\u2265',
-    '#39': '\u0027',
-});
-
-// renders:
-
-<p>This text is ≤ than this text.</p>
-```
-
 #### options.disableAutoLink
 
 By default, bare URLs in the markdown document will be converted into an anchor tag. This behavior can be disabled if desired.
 
-```jsx
+```tsx
 <Markdown options={{ disableAutoLink: true }}>
   The URL https://quantizor.dev will not be rendered as an anchor tag.
 </Markdown>
@@ -588,7 +749,7 @@ compiler(
 
 By default, raw HTML is parsed to JSX. This behavior can be disabled if desired.
 
-```jsx
+```tsx
 <Markdown options={{ disableParsingRawHTML: true }}>
     This text has <span>html</span> in it but it won't be rendered
 </Markdown>;
@@ -602,37 +763,45 @@ compiler('This text has <span>html</span> in it but it won't be rendered', { dis
 <span>This text has &lt;span&gt;html&lt;/span&gt; in it but it won't be rendered</span>
 ```
 
-#### options.ast
+#### options.tagfilter
 
-When `ast: true`, the compiler returns the parsed AST structure instead of rendered JSX. **This is the first time the AST is accessible to users!**
+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`.
 
 ```tsx
-import { compiler } from 'markdown-to-jsx'
-import type { MarkdownToJSX } from 'markdown-to-jsx'
-
-// Get the AST directly
-const ast = compiler('# Hello world', { ast: true })
-
-// TypeScript: AST is MarkdownToJSX.AST[]
-console.log(ast) // Array of parsed nodes with types
-
-// You can manipulate, transform, or analyze the AST before rendering
+// 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>
 ```
 
-The AST format is `MarkdownToJSX.AST[]` and enables:
+**Note**: Even when `tagfilter` is disabled, other security measures remain active:
 
-- AST manipulation and transformation
-- Custom rendering logic without re-parsing
-- Caching parsed AST for performance
-- Linting or validation of markdown structure
-
-When footnotes are present, the returned value will be an object with `ast` and `footnotes` properties instead of just the AST array.
+- 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`:
 
-````jsx
+```html
+<!-- 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>
+```
+
+````tsx
 import { Markdown, RuleType } from 'markdown-to-jsx'
 
 const mdContainingFencedCodeBlock = '```js\nconsole.log("Hello world!");\n```\n'
@@ -650,23 +819,6 @@ function App() {
   )
 }
 
-/**
- * Add the following tags to your page <head> to automatically load hljs and styles:
-
-  <link
-    rel="stylesheet"
-    href="https://unpkg.com/@highlightjs/cdn-assets@11.9.0/styles/nord.min.css"
-  />
-
-  * NOTE: for best performance, load individual languages you need instead of all
-          of them. See their docs for more info: https://highlightjs.org/
-
-  <script
-    crossorigin
-    src="https://unpkg.com/@highlightjs/cdn-assets@11.9.0/highlight.min.js"
-  ></script>
- */
-
 function SyntaxHighlightedCode(props) {
   const ref = (React.useRef < HTMLElement) | (null > null)
 
@@ -747,9 +899,174 @@ Here are instructions for some of the popular bundlers:
 
 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.
 
-## Gotchas
+### 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`)
+  ```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
+  ```tsx
+  { type: RuleType.htmlBlock, tag: "div", attrs: {}, children: [...] }
+  ```
+
+**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: "<!-- comment -->" }
+  ```
+- `RuleType.htmlSelfClosing` - Self-closing HTML tags
+  ```tsx
+  { type: RuleType.htmlSelfClosing, tag: "img", attrs: { src: "image.png" } }
+  ```
+
+#### 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 `<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.
 
-### Passing props to stringified React components
+### 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.
 
@@ -795,7 +1112,7 @@ const Table: React.FC<
  */
 ```
 
-### Significant indentation inside arbitrary HTML
+#### Significant indentation inside arbitrary HTML
 
 People usually write HTML like this:
 
@@ -831,40 +1148,14 @@ The two leading spaces in front of "# Hello" would be left-trimmed from all line
 <div>
 ```js
 var some = code();
-``\`
+```
 </div>
 ````
 
-## Using The Compiler Directly
-
-If desired, the compiler function is a "named" export on the `markdown-to-jsx` module:
-
-```jsx
-import { compiler } from 'markdown-to-jsx'
-import React from 'react'
-import { render } from 'react-dom'
-
-render(compiler('# Hello world!'), document.body)
-
-/*
-    renders:
-
-    <h1>Hello world!</h1>
- */
-```
-
-It accepts the following arguments:
-
-```js
-compiler(markdown: string, options: object?)
-```
-
 ## Changelog
 
-See [Github Releases](https://github.com/probablyup/markdown-to-jsx/releases).
+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!
-
-MIT
+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)!