markdown-to-jsx 7.7.16 → 8.0.0

package/README.md

@@ -6,6 +6,8 @@ The most lightweight, customizable React markdown component.
 
 <!-- TOC -->
 
+- [Upgrading](#upgrading)
+  - [From v7.x to v8.x](#from-v7x-to-v8x)
 - [Installation](#installation)
 - [Usage](#usage)
   - [Parsing Options](#parsing-options)
@@ -25,6 +27,7 @@ The most lightweight, customizable React markdown component.
     - [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)
@@ -53,10 +56,36 @@ The most lightweight, customizable React markdown component.
 
 - Fenced code blocks with [highlight.js](https://highlightjs.org/) support; see [Syntax highlighting](#syntax-highlighting) for instructions on setting up highlight.js.
 
-All this clocks in at around 6 kB gzipped, which is a fraction of the size of most other React markdown components.
+All this clocks in at around 7.5 kB gzipped, which is a fraction of the size of most other React markdown components.
 
 Requires React >= 0.14.
 
+## Upgrading
+
+### From v7.x to v8.x
+
+**Breaking Changes:**
+
+- Type `ParserResult` renamed to `ASTNode` - If you were using `MarkdownToJSX.ParserResult` in your code, update to `MarkdownToJSX.ASTNode`
+
+```typescript
+// Before
+const nodes: MarkdownToJSX.ParserResult[] = parse(markdown)
+
+// After
+const nodes: MarkdownToJSX.ASTNode[] = parse(markdown)
+```
+
+- Multiple `RuleType` enums consolidated into `RuleType.textFormatted` - If you were checking for `RuleType.textBolded`, `RuleType.textEmphasized`, `RuleType.textMarked`, or `RuleType.textStrikethroughed`, update to check for `RuleType.textFormatted` and inspect the node's boolean flags:
+
+```typescript
+// Before
+if (node.type === RuleType.textBolded) { ... }
+
+// After
+if (node.type === RuleType.textFormatted && node.bold) { ... }
+```
+
 ## Installation
 
 Install `markdown-to-jsx` with your favorite package manager.
@@ -573,6 +602,32 @@ 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'
+
+// 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
+```
+
+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`: