This docs/ directory documents the customization and extension surfaces of ai-react-markdown. The project README covers installation, quick start, and the basic prop reference; everything below is for when you outgrow defaults.
Audience. You've shipped
<AIMarkdown>with default settings and now need to:
- replace specific HTML element renderers (e.g. a chat-specific
<pre>with copy buttons),- swap or theme the typography wrapper,
- allow private URL schemes through sanitization,
- coordinate footnotes/references across chunked chat messages,
- or build your own integration package on top of
@ai-react-markdown/core.If you only need defaults, you don't need this guide —
<AIMarkdown content={…} />already does the right thing.
Most readers come in with a task, not a curriculum. Pick the row that matches what you're doing:
| You're doing… | Start with | Then read |
|---|---|---|
| Building a streaming chat UI | Streaming chat: end-to-end | Streaming & performance + Cross-chunk coordination + Metadata context |
| Rendering Chinese / Japanese / Korean content | CJK typography | Design tokens for font customization |
Splitting one logical document across multiple <AIMarkdown> instances |
Cross-chunk coordination | Streaming & performance |
| Retheming colors, spacing, fonts | Design tokens | Custom typography (only if tokens aren't enough) |
Replacing element renderers (custom <a>, <pre>, …) |
Custom components | Metadata context (for callbacks) |
| Doing a security review / allowing private URL schemes | URL sanitization | Architecture (for the pipeline picture) |
| Adding typed config / metadata fields | TypeScript generics | Extending via a sub-package (if you'll publish it) |
| Transforming raw markdown before render | Content preprocessors | — |
Building your own @yourorg/ai-react-markdown-… integration |
Extending via a sub-package | Architecture, TypeScript generics |
| Debugging unexpected render output | Architecture | Streaming & performance (cache invariants) |
| Tracking what changed across versions | Release highlights | — |
If none of these matches, the full topic index below covers every surface.
Full topic index (every document in this directory, by customization surface)
| # | Document | When you need it |
|---|---|---|
| 1 | Custom components | Replace any HTML element renderer (a, img, pre, table, …) with your own React component |
| 2 | Custom typography | Swap the Typography slot — themed wrapper, custom font stack, design system integration |
| 3 | Design tokens | Override CSS custom properties to retheme without writing a custom typography component |
| 4 | Content preprocessors | Transform the raw markdown string before parsing — frontmatter stripping, regex fixes, dialect normalization |
| 5 | URL sanitization & custom schemes | Allow myapp://, tel:, or any other scheme through both sanitization gates safely |
| 6 | Cross-chunk coordination | Render chunked chat messages whose footnotes / [ref] / ![ref] resolve across <AIMarkdown> instances |
| 7 | Metadata context | Pass arbitrary data (callbacks, ids, app state) to deeply nested custom components without prop drilling |
| 8 | Streaming & performance | Reason about block-level memoization, streaming-aware custom components, and the cache-flush footguns |
| 9 | TypeScript generics | Extend AIMarkdownRenderConfig and AIMarkdownMetadata with your own typed fields |
| 10 | Extending via a sub-package | Build your own @yourorg/ai-react-markdown-<integration> package, following the Mantine model |
| 11 | Architecture overview | Mental model: render pipeline, context layering, registry design |
| ★ | Streaming chat: end-to-end | Copy-runnable example — SSE backend, React state, Next.js App Router |
| ★ | CJK typography | Chinese / Japanese / Korean text — line breaking, pangu spacing, font stack |
| ★ | Release highlights | What's notable in each version — distilled from the commit log |
The documents are independent — read them in any order. Cross-references are inlined where helpful.
The library follows semver:
| Surface | Stability under minor versions |
|---|---|
Component props (AIMarkdownProps, MantineAIMarkdownProps) |
Stable. Additions are non-breaking; renames/removals require a major bump |
Hook signatures (useAIMarkdownRenderState, useAIMarkdownMetadata, useDocumentRegistry, useStableValue) |
Stable |
AIMarkdownRenderConfig field names and roles |
Stable |
AIMarkdownRenderConfig default values |
May shift under minor bumps as defaults evolve — override what you need locked |
CSS custom property names (e.g. --aim-spacing-md) |
Stable |
| CSS custom property default values | May shift under minor bumps as the visual design evolves |
UrlTransform, SanitizeSchema types |
Track upstream react-markdown / rehype-sanitize; may change with their majors |
Registry interface |
Stable read-only surface; mutator methods are intentionally not exported |
| Internal byte-for-byte HTML output | Not stable — never assert on raw HTML; use semantic queries |
When in doubt, pin your overrides explicitly rather than relying on defaults.
- Code blocks show the minimal version that compiles — apply your own imports for
katexCSS,MantineProvider, etc. - Footguns sections at the end of each document collect anti-patterns and stability traps. Read them once per surface.
// ✅and// ⚠️callouts mark recommended vs anti-pattern code lines.- Where a behavior is shared by
@ai-react-markdown/coreand@ai-react-markdown/mantine, the example usesAIMarkdown(core); apply identically toMantineAIMarkdown.
If you find a documented API that doesn't behave as described, or a customization recipe that breaks at a version boundary, please open an issue with:
- the document name and section,
- the package version (
@ai-react-markdown/core@1.4.x…), - a minimal reproduction,
- the observed vs expected behavior.
Issue tracker: https://github.com/AIEPhoenix/ai-react-markdown/issues