markdown-to-jsx 8.0.0 → 9.0.0-rc.1

package/README.md

@@ -1,12 +1,25 @@
-**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, and more.
+
+- Fenced code blocks with [highlight.js](https://highlightjs.org/) support; see [Syntax highlighting](#syntax-highlighting) for instructions on setting up highlight.js.
+
+## Table of Contents
 
 <!-- TOC -->
 
+- [Table of Contents](#table-of-contents)
 - [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)
@@ -24,10 +37,8 @@ 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)
   - [Syntax highlighting](#syntax-highlighting)
   - [Handling shortcodes](#handling-shortcodes)
   - [Getting the smallest possible bundle size](#getting-the-smallest-possible-bundle-size)
@@ -36,31 +47,106 @@ The most lightweight, customizable React markdown component.
   - [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)
+- [Entry Points](#entry-points)
+  - [Main](#main)
+  - [React](#react)
+  - [HTML](#html)
+  - [Markdown](#markdown)
+- [Using The Parser Low-Level AST API](#using-the-parser-low-level-ast-api)
+- [AST Anatomy](#ast-anatomy)
+  - [Node Types](#node-types)
+  - [Example AST Structure](#example-ast-structure)
+  - [Type Checking](#type-checking)
 - [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
+```
+
+**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 +172,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 +188,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'
@@ -134,37 +222,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 +274,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
@@ -200,7 +287,7 @@ To render children at the same DOM level as `<Markdown>` with no HTML wrapper, s
 
 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…
@@ -236,7 +323,7 @@ The library does not void any tags by default to avoid surprising behavior for p
 
 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 +391,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 +426,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 +463,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 +583,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 +600,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 +615,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 +642,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 +656,24 @@ 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
-
-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!**
-
-```tsx
-import { compiler } from 'markdown-to-jsx'
-import type { MarkdownToJSX } from 'markdown-to-jsx'
+### Syntax highlighting
 
-// Get the AST directly
-const ast = compiler('# Hello world', { ast: true })
+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`:
 
-// TypeScript: AST is MarkdownToJSX.AST[]
-console.log(ast) // Array of parsed nodes with types
+```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"
+/>
 
-// You can manipulate, transform, or analyze the AST before rendering
+<script
+  crossorigin
+  src="https://unpkg.com/@highlightjs/cdn-assets@11.9.0/highlight.min.js"
+></script>
 ```
 
-The AST format is `MarkdownToJSX.AST[]` and enables:
-
-- 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.
-
-### 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
+````tsx
 import { Markdown, RuleType } from 'markdown-to-jsx'
 
 const mdContainingFencedCodeBlock = '```js\nconsole.log("Hello world!");\n```\n'
@@ -650,23 +691,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)
 
@@ -831,40 +855,267 @@ 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
+## Entry Points
 
-If desired, the compiler function is a "named" export on the `markdown-to-jsx` module:
+`markdown-to-jsx` provides multiple entry points for different use cases:
 
-```jsx
-import { compiler } from 'markdown-to-jsx'
-import React from 'react'
-import { render } from 'react-dom'
+### Main
 
-render(compiler('# Hello world!'), document.body)
+The legacy\*default entry point exports everything, including the React compiler and component:
 
-/*
-    renders:
+```tsx
+import Markdown, { compiler, parser } from 'markdown-to-jsx'
+```
 
-    <h1>Hello world!</h1>
- */
+_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)
 ```
 
-It accepts the following arguments:
+### HTML
 
-```js
-compiler(markdown: string, options: object?)
+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'
+```
+
+## Using The Parser (Low-Level AST API)
+
+The `parser` function provides direct access to the parsed AST without rendering:
+
+```tsx
+import { parser } from 'markdown-to-jsx'
+import type { MarkdownToJSX } from 'markdown-to-jsx'
+
+// Parse markdown to AST
+const ast = parser('# Hello world')
+
+// TypeScript: AST is MarkdownToJSX.ASTNode[]
+console.log(ast) // Array of parsed nodes
+
+// You can then render with html() or compiler()
+```
+
+The `parser` function accepts:
+
+- `source: string` - markdown source
+- `state?: MarkdownToJSX.State` - parsing state (defaults: `{ inline: false, refs: {} }`)
+- `options?: MarkdownToJSX.Options` - parsing options
+
+Use `parser` when you need:
+
+- Direct AST access without React rendering
+- Custom rendering logic
+- AST manipulation before rendering
+
+## 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: [[...]], ordered: false }
+  ```
+- `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" }
+  ```
+- `RuleType.refLink` / `RuleType.refImage` - Reference-style links/images
+  ```tsx
+  { type: RuleType.refLink, ref: "linkref", children: [...] }
+  ```
+
+**Other nodes:**
+
+- `RuleType.breakLine` - Hard line breaks (`  `)
+- `RuleType.breakThematic` - Horizontal rules (`---`)
+- `RuleType.gfmTask` - GFM task list items (`- [ ]`)
+- `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]`)
+
+### 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 `RuleType` constants to check node types:
+
+```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.
+
 ## 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)!