---
url: /roadmap.md
---
# 🗺️ Roadmap

Our future plans focus on enhancing the library's capabilities for building modern, accessible, and high-performance AI chat interfaces.

## ✨ Accomplished

### 🏗️ Core & Engine

* \[x] **BlockTransformer**: Cross-framework architecture for consistent typewriter effects.
* \[x] **Syntax Refinement**: Enhanced boundary parsing, commonmark compliance, and edge-case rendering.
* \[x] **Incremental Engine**: State-aware parsing for $O(N)$ performance.
* \[x] **Dual-Engine Architecture**: Support for both `marked` (fast, streaming-optimized) and `micromark` (stable, CommonMark-compliant) engines with tree-shaking optimization.
* \[x] **Micromark Enhancement**: Improved HTML parsing and stability.
* \[x] **Marked Enhancement**: Extended `marked` with footnotes, math, custom containers, and inline HTML parsing support.

### 🎨 Design System & Theme

* \[x] **@incremark/theme**: Unified styles with DesignToken support in a separate package.
* \[x] **ThemeProvider**: Context-based styling for all components.
* \[x] **Thematic Components**: Built-in support for specialized markdown blocks.

### 🍱 Framework Components

* \[x] **@incremark/vue**: Full-featured Vue component library.
* \[x] **@incremark/react**: Full-featured React component library.
* \[x] **@incremark/svelte**: Full-featured Svelte component library.
* \[x] **@incremark/solid**: Full-featured Solid component library.
* \[x] **IncremarkContent**: Declarative, easy-to-use entry component for all frameworks.

### 🔌 Features & Extensions

* \[x] **GFM Support**: Full support for GitHub Flavored Markdown.
* \[x] **Mermaid Support**: Integrated support for Mermaid diagrams within Markdown.
* \[x] **Math Support**: Robust support for LaTeX math formulas via KaTeX.
* \[x] **Custom Rendering**: Full support for custom markdown components.
* \[x] **Custom Code Blocks**: Flexible configuration for partial or full rendering takeover.
* \[x] **Custom Containers**: Support for `:::` container syntax.
* \[x] **Footnotes**: Full support for markdown footnotes.
* \[x] **HTML Parsing**: Robust handling of embedded HTML content.

***

## 🚀 Upcoming Features

### 🛠️ Markdown & Tooling

* \[x] **Code Component Refactoring**: Decouple Mermaid and Default renderers to allow for better composition and customization.
* \[x] **DevTools Rewrite**: Rebuilding DevTools using Svelte for better DX with i18n support (zh-CN/en-US), multi-parser monitoring, and framework-agnostic design.
* \[x] **sliceAST Optimization**: Simplified code structure, removed dead code; per-block processing ensures performance.
* \[x] **Internationalization (i18n)**: Built-in multi-language support with ConfigProvider.
* \[x] **Accessibility (A11y)**: Enhanced screen reader support and ARIA standards.
* \[x] **SSR Support**: Optimization for Server-Side Rendering (Nuxt/Next.js).

### ⚡ Performance Optimization

* \[x] **Shiki Stream Optimization**: Improve streaming code highlighting performance across all frameworks.
* \[x] **Block Component Rendering**: Optimize block-level component rendering performance, reduce unnecessary re-renders.

### 🏗️ Big Vision: Incremental Chat UI Kit

A comprehensive set of pre-built UI components powered by the Incremark engine.

* \[ ] **@incremark/chat-core**: Logic layer for message management, A2UI protocol, and mainstream LLM SDK adaptation.
* \[ ] **@incremark/chat-vue**: High-level chat components for Vue.
  * \[ ] **UI Adapters**: First-class support for `element-plus` and `shadcn-vue`.
* \[ ] **@incremark/chat-react**: High-level chat components for React.
* \[ ] **@incremark/chat-svelte**: High-level chat components for Svelte.

***

### 🔌 Plugin System

* \[x] **Micromark Extensions**: Full support for `micromark` syntax extensions.
* \[x] **mdast Extensions**: Full support for `mdast-util-from-markdown` AST extensions.
* \[x] **Marked Extensions**: Custom token transformers for the `marked` engine.

***

## 🔮 Long-term Research

* \[ ] **Collaborative Editing**: Researching solutions including: 1. Tiptap markdown parsing based on `micromark`, 2. Incremental appending scheme based on `incremark`.

---

---
url: /zh/roadmap.md
---
# 🗺️ 路线图

我们未来的计划专注于增强库的能力，以构建现代、无障碍且高性能的 AI 聊天界面。

## ✨ 已完成

### 🏗️ 核心引擎

* \[x] **BlockTransformer**: 跨框架打字机效果实现，确保渲染一致性。
* \[x] **语法完善**: 修复边界情况解析与渲染，增加更完善的 commonmark 测试用例。
* \[x] **增量解析**: 实现 O(N) 性能的状态感知解析引擎。
* \[x] **双引擎架构**: 支持 `marked`（极速流式优化）和 `micromark`（稳定 CommonMark 兼容）双引擎，支持 tree-shaking 优化。
* \[x] **Micromark 增强**: 提升 HTML 解析能力与稳定性。
* \[x] **Marked 增强**: 为 `marked` 扩展脚注、数学公式、自定义容器、内联 HTML 解析等功能。

### 🎨 设计系统与主题

* \[x] **@incremark/theme**: 统一各组件库样式，支持 DesignToken，并拆分为独立子包。
* \[x] **ThemeProvider**: 统一的样式上下文管理组件。
* \[x] **主题组件支持**: 内置多种 Markdown 块级主题组件。

### Bento 组件库

* \[x] **@incremark/vue**: 完整的 Vue 组件集成。
* \[x] **@incremark/react**: 完整的 React 组件集成。
* \[x] **@incremark/svelte**: 完整的 Svelte 组件集成。
* \[x] **@incremark/solid**: 完整的 Solid 组件集成。
* \[x] **IncremarkContent**: 简单易用的声明式入口组件。

### 🔌 功能与扩展

* \[x] **GFM 支持**: 支持 GFM 语法。
* \[x] **Mermaid 支持**: 支持在 Markdown 中嵌入 Mermaid 图表。
* \[x] **Math 支持**: 支持在 Markdown 中嵌入 Math 公式。
* \[x] **自定义组件**: 支持自定义 Markdown 渲染组件。
* \[x] **自定义代码块**: 支持全接管或完成时渲染接管。
* \[x] **自定义容器**: 支持 `:::` 容器块语法。
* \[x] **脚注支持**: 完整的 Markdown 脚注功能。
* \[x] **HTML 解析**: 支持在 Markdown 中嵌入 HTML 标签。

***

## 🚀 即将进行

### 🛠️ Markdown 与工具

* \[x] **Code 组件重构**: 解耦 Mermaid 与默认渲染器，提升定制化能力。
* \[x] **devtools 重构**: 使用 Svelte 重构开发工具，支持国际化（中英文）、多解析器监控、框架无关设计，提升开发体验。
* \[x] **sliceAST 优化**: 简化代码结构，移除死代码；按 block 处理确保性能。
* \[x] **i18n 国际化**: 内置多语言支持，提供 ConfigProvider 全局配置。
* \[x] **a11y 无障碍**: 完善屏幕阅读器支持与 ARIA 规范。
* \[x] **SSR 支持**: 针对 Nuxt/Next.js 的服务端渲染优化。

### ⚡ 性能优化

* \[x] **Shiki Stream 优化**: 优化各框架流式代码高亮性能。
* \[x] **Block 组件渲染优化**: 优化块级组件渲染性能，减少不必要的重新渲染。

### 🏗️ 大计划: 基于增量渲染的 chat-ui 组件库

利用 Incremark 引擎打造的一套开箱即用的 AI 聊天 UI 组件。

* \[ ] **@incremark/chat-core**: 消息管理逻辑层，支持 A2UI 协议及主流 SDK 适配。
* \[ ] **@incremark/chat-vue**: 基于 Vue 的高阶聊天组件。
  * \[ ] **UI 适配器**: 优先适配 `element-plus` 和 `shadcn-vue`。
* \[ ] **@incremark/chat-react**: 基于 React 的高阶聊天组件。
* \[ ] **@incremark/chat-svelte**: 基于 Svelte 的高阶聊天组件。

***

### 🔌 插件系统

* \[x] **Micromark 扩展**: 完整支持 `micromark` 语法扩展。
* \[x] **mdast 扩展**: 完整支持 `mdast-util-from-markdown` AST 扩展。
* \[x] **Marked 扩展**: 为 `marked` 引擎提供自定义 Token 转换器。

***

## 🔮 长期研究

* \[ ] **协作编辑**: 1. 基于 micromark 的 tiptap markdown 解析方案， 2. 基于 incremark 的增量追加方案。

---

---
url: /examples/anthropic.md
---
# Anthropic Integration

Using the `@anthropic-ai/sdk` library.

## Example

```ts
import Anthropic from '@anthropic-ai/sdk'
import { IncremarkContent } from '@incremark/react'

const anthropic = new Anthropic({
  apiKey: 'YOUR_API_KEY',
})

function App() {
  const [stream, setStream] = useState(null)

  async function startChat() {
    async function* getStream() {
      const stream = await anthropic.messages.create({
        max_tokens: 1024,
        messages: [{ role: 'user', content: 'Hello, Claude' }],
        model: 'claude-3-opus-20240229',
        stream: true,
      })

      for await (const chunk of stream) {
        if (chunk.type === 'content_block_delta') {
          yield chunk.delta.text
        }
      }
    }
    
    setStream(() => getStream)
  }

  return (
    <>
      <button onClick={startChat}>Send</button>
      <IncremarkContent stream={stream} />
    </>
  )
}
```

---

---
url: /zh/examples/anthropic.md
---
# Anthropic 集成

使用 `@anthropic-ai/sdk` 库。

## 示例

```ts
import Anthropic from '@anthropic-ai/sdk'
import { IncremarkContent } from '@incremark/react'

const anthropic = new Anthropic({
  apiKey: 'YOUR_API_KEY',
})

function App() {
  const [stream, setStream] = useState(null)

  async function startChat() {
    async function* getStream() {
      const stream = await anthropic.messages.create({
        max_tokens: 1024,
        messages: [{ role: 'user', content: 'Hello, Claude' }],
        model: 'claude-3-opus-20240229',
        stream: true,
      })

      for await (const chunk of stream) {
        if (chunk.type === 'content_block_delta') {
          yield chunk.delta.text
        }
      }
    }
    
    setStream(() => getStream)
  }

  return (
    <>
      <button onClick={startChat}>Send</button>
      <IncremarkContent stream={stream} />
    </>
  )
}
```

---

---
url: /api.md
---
# API Reference

A centralized reference for all Incremark types and components.

## Components

### `<IncremarkContent />`

The main component for rendering Markdown content.

**Props (`IncremarkContentProps`)**:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `content` | `string` | - | The Markdown string to render (content mode). |
| `stream` | `() => AsyncGenerator<string>` | - | Async generator function for streaming content (stream mode). |
| `isFinished` | `boolean` | `false` | Whether the content generation is finished (required for content mode). |
| `incremarkOptions` | `UseIncremarkOptions` | - | Configuration options for the parser and typewriter effect. |
| `components` | `ComponentMap` | `{}` | Custom components to override default element rendering. |
| `customContainers` | `Record<string, Component>` | `{}` | Custom container components for `::: name` syntax. |
| `customCodeBlocks` | `Record<string, Component>` | `{}` | Custom code block components for specific languages. |
| `codeBlockConfigs` | `Record<string, CodeBlockConfig>` | `{}` | Configuration for code blocks (e.g., `takeOver`). |
| `showBlockStatus` | `boolean` | `false` | Whether to visualize block processing status (pending/completed). |
| `pendingClass` | `string` | `'incremark-pending'` | CSS class applied to pending blocks. |
| `devtools` | `IncremarkDevTools` | - | DevTools instance to register with for debugging. |
| `devtoolsId` | `string` | *Auto-generated* | Unique identifier for this parser in DevTools. |
| `devtoolsLabel` | `string` | `devtoolsId` | Display label for this parser in DevTools. |

### `<AutoScrollContainer />`

A container that automatically scrolls to the bottom when content updates.

**Props**:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `enabled` | `boolean` | `true` | Whether auto-scroll functionality is active. |
| `threshold` | `number` | `50` | Distance in pixels from bottom to trigger auto-scroll. |
| `behavior` | `ScrollBehavior` | `'instant'` | Scroll behavior (`'auto'`, `'smooth'`, `'instant'`). |

## Composables / Hooks

### `useIncremark`

The core hook for advanced usage and fine-grained control.

**Options (`UseIncremarkOptions`)**:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `gfm` | `boolean` | `true` | Enable GitHub Flavored Markdown support. |
| `math` | `boolean` | `true` | Enable Math (KaTeX) support. |
| `htmlTree` | `boolean` | `true` | Enable parsing of raw HTML tags. |
| `containers` | `boolean` | `true` | Enable custom container syntax `:::`. |
| `typewriter` | `TypewriterOptions` | - | Configuration for typewriter effect. |

**Returns (`UseIncremarkReturn`)**:

| Property | Type | Description |
|----------|------|-------------|
| `blocks` | `Ref<Block[]>` | Reactive array of parsed blocks with stable IDs. |
| `append` | `(chunk: string) => void` | Append new content chunk to the parser. |
| `render` | `(content: string) => void` | Render a complete or updated content string. |
| `reset` | `() => void` | Reset parser state and clear all blocks. |
| `finalize` | `() => void` | Mark all blocks as completed. |
| `isDisplayComplete` | `Ref<boolean>` | Whether the typewriter effect has finished displaying all content. |

## Configuration Types

### `TypewriterOptions`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | `boolean` | `false` | Enable typewriter effect. |
| `charsPerTick` | `number \| [number, number]` | `2` | Characters to reveal per tick (or range). |
| `tickInterval` | `number` | `50` | ms between ticks. |
| `effect` | `'none' \| 'fade-in' \| 'typing'` | `'none'` | Animation style. |
| `cursor` | `string` | `'|'` | Cursor character for typing effect. |

---

---
url: /zh/api.md
---
# API 参考文档

Incremark 所有类型和组件的集中参考。

## 组件 (Components)

### `<IncremarkContent />`

渲染 Markdown 内容的主要组件。

**Props (`IncremarkContentProps`)**:

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `content` | `string` | - | 要渲染的 Markdown 字符串（content 模式）。 |
| `stream` | `() => AsyncGenerator<string>` | - | 用于流式内容的异步生成器函数（stream 模式）。 |
| `isFinished` | `boolean` | `false` | 内容生成是否完成（content 模式必需）。 |
| `incremarkOptions` | `UseIncremarkOptions` | - | 解析器和打字机效果的配置选项。 |
| `components` | `ComponentMap` | `{}` | 自定义组件，用于覆盖默认元素的渲染。 |
| `customContainers` | `Record<string, Component>` | `{}` | 用于 `::: name` 语法的自定义容器组件。 |
| `customCodeBlocks` | `Record<string, Component>` | `{}` | 特定语言的自定义代码块组件。 |
| `codeBlockConfigs` | `Record<string, CodeBlockConfig>` | `{}` | 代码块配置（例如 `takeOver`）。 |
| `showBlockStatus` | `boolean` | `false` | 是否可视化块的处理状态（pending/completed）。 |
| `pendingClass` | `string` | `'incremark-pending'` | 应用于 pending 状态块的 CSS 类。 |
| `devtools` | `IncremarkDevTools` | - | 要注册的 DevTools 实例，用于调试。 |
| `devtoolsId` | `string` | *自动生成* | 在 DevTools 中此解析器的唯一标识符。 |
| `devtoolsLabel` | `string` | `devtoolsId` | 在 DevTools 中此解析器的显示标签。 |

### `<AutoScrollContainer />`

当内容更新时自动滚动到底部的容器组件。

**Props**:

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `enabled` | `boolean` | `true` | 是否启用自动滚动功能。 |
| `threshold` | `number` | `50` | 触发自动滚动的底部距离阈值（像素）。 |
| `behavior` | `ScrollBehavior` | `'instant'` | 滚动行为 (`'auto'`, `'smooth'`, `'instant'`)。 |

## 组合式函数 / Hooks

### `useIncremark`

用于高级用法和细粒度控制的核心 Hook。

**选项 (`UseIncremarkOptions`)**:

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `gfm` | `boolean` | `true` | 启用 GitHub Flavored Markdown 支持。 |
| `math` | `boolean` | `true` | 启用数学公式 (KaTeX) 支持。 |
| `htmlTree` | `boolean` | `true` | 启用原始 HTML 标签解析。 |
| `containers` | `boolean` | `true` | 启用自定义容器语法 `:::`。 |
| `typewriter` | `TypewriterOptions` | - | 打字机效果配置。 |

**返回值 (`UseIncremarkReturn`)**:

| 属性 | 类型 | 说明 |
|------|------|------|
| `blocks` | `Ref<Block[]>` | 具有稳定 ID 的解析块响应式数组。 |
| `append` | `(chunk: string) => void` | 向解析器追加新的内容块。 |
| `render` | `(content: string) => void` | 渲染完整或更新的内容字符串。 |
| `reset` | `() => void` | 重置解析器状态并清空所有块。 |
| `finalize` | `() => void` | 将所有块标记为已完成。 |
| `isDisplayComplete` | `Ref<boolean>` | 打字机效果是否已显示完所有内容。 |

## 配置类型

### `TypewriterOptions`

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `enabled` | `boolean` | `false` | 启用打字机效果。 |
| `charsPerTick` | `number \| [number, number]` | `2` | 每次显示的字符数（或范围）。 |
| `tickInterval` | `number` | `50` | 更新间隔（毫秒）。 |
| `effect` | `'none' \| 'fade-in' \| 'typing'` | `'none'` | 动画风格。 |
| `cursor` | `string` | `'|'` | 打字效果的光标字符。 |

---

---
url: /advanced/architecture.md
---
# Architecture

This document explains the internal architecture of Incremark, helping you understand how the library achieves high-performance streaming markdown rendering.

## Overall Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                      IncremarkContent                           │
│  (Declarative component, handles content/stream input)          │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                       useIncremark                              │
│  (State management, reactive wrapper, typewriter coordination)  │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      IncremarkParser                            │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Dual-Engine AST Builder                     │   │
│  │  ┌──────────────────┐    ┌──────────────────┐           │   │
│  │  │  MarkedAstBuilder│    │MicromarkAstBuilder│          │   │
│  │  │  (Default, Fast) │    │ (Stable, Strict) │           │   │
│  │  └──────────────────┘    └──────────────────┘           │   │
│  └─────────────────────────────────────────────────────────┘   │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐       │
│  │   Boundary    │  │  Definition   │  │   Footnote    │       │
│  │   Detector    │  │   Manager     │  │   Manager     │       │
│  └───────────────┘  └───────────────┘  └───────────────┘       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                     BlockTransformer                            │
│  (Typewriter effect, character-level incremental rendering)     │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐       │
│  │    Plugins    │  │     Chunk     │  │   TextChunk   │       │
│  │    System     │  │   Animation   │  │    Tracking   │       │
│  └───────────────┘  └───────────────┘  └───────────────┘       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                        Renderer                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │     Vue      │  │    React     │  │    Svelte    │          │
│  │  Components  │  │  Components  │  │  Components  │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
```

## Dual-Engine Architecture

Incremark supports two parsing engines that can be switched at runtime:

### MarkedAstBuilder (Default)

The `marked` engine is optimized for streaming performance:

* **Speed**: Extremely fast tokenization, ideal for real-time AI chat
* **Extensions**: Custom extensions for footnotes, math, containers, inline HTML
* **Trade-off**: Slightly less strict CommonMark compliance

```ts
// Internal: packages/core/src/parser/ast/MarkedAstBuildter.ts
class MarkedAstBuilder implements IAstBuilder {
  // Custom marked extensions
  private extensions = [
    createFootnoteDefinitionExtension(),
    createBlockMathExtension(),
    createInlineMathExtension(),
    createContainerExtension(),
    createInlineHtmlExtension()
  ]
}
```

### MicromarkAstBuilder

The `micromark` engine prioritizes correctness and extensibility:

* **Compliance**: Strict CommonMark specification adherence
* **Ecosystem**: Full access to micromark/mdast plugin ecosystem
* **Trade-off**: Slightly higher overhead for parsing

```ts
// Internal: packages/core/src/parser/ast/MicromarkAstBuilder.ts
class MicromarkAstBuilder implements IAstBuilder {
  // Uses mdast-util-from-markdown with micromark extensions
}
```

### Engine Selection

Both engines produce identical mdast output, ensuring consistent rendering:

```ts
// Default: uses marked (fast mode)
const parser = new IncremarkParser({ gfm: true, math: true })

// To use micromark (import separately for tree-shaking)
import { MicromarkAstBuilder } from '@incremark/core/engines/micromark'
const parser = new IncremarkParser({
  astBuilder: MicromarkAstBuilder,
  gfm: true,
  math: true
})
```

## Core Components

### IncremarkParser

The central coordinator that manages the incremental parsing pipeline:

| Component | Responsibility |
|-----------|---------------|
| **BoundaryDetector** | Identifies stable boundaries (empty lines, new headings) to commit completed blocks |
| **AstBuilder** | Constructs mdast nodes from markdown text using the selected engine |
| **DefinitionManager** | Tracks link/image definitions across the document |
| **FootnoteManager** | Manages footnote definitions and references |

### BlockTransformer

Handles the typewriter animation layer:

| Component | Responsibility |
|-----------|---------------|
| **Plugins System** | Extensible plugin architecture for custom behavior |
| **Chunk Animation** | Manages the queue of text chunks to animate |
| **TextChunk Tracking** | Tracks which characters have been "played" for smooth animation |

### Renderer

Framework-specific rendering components:

* **Vue**: `@incremark/vue` - Uses Vue 3.5 Composition API
* **React**: `@incremark/react` - Uses React 18 hooks
* **Svelte**: `@incremark/svelte` - Uses Svelte 5 runes

All renderers share the same core logic and produce identical DOM output.

## Data Flow

```mermaid
sequenceDiagram
    participant App as Application
    participant IC as IncremarkContent
    participant UI as useIncremark
    participant P as Parser
    participant BT as BlockTransformer
    participant R as Renderer

    App->>IC: content += chunk
    IC->>UI: append(chunk)
    UI->>P: parse(markdown)
    
    Note over P: Boundary Detection
    P->>P: Find stable boundaries
    P->>P: Cache completed blocks
    P->>P: Re-parse only pending block
    
    P-->>UI: blocks[]
    UI->>BT: transform(blocks)
    
    Note over BT: Animation Processing
    BT->>BT: Diff with previous state
    BT->>BT: Create TextChunks for new text
    BT->>BT: Queue for typewriter effect
    
    BT-->>UI: animatedBlocks[]
    UI->>R: render(animatedBlocks)
    R->>R: Selective DOM update
```

## Performance Optimizations

### 1. Incremental Line Parsing

Only new lines are parsed; completed blocks are cached:

```ts
// Simplified concept
if (line.isNewlyAdded) {
  parse(line)
} else if (block.isCompleted) {
  return cachedAST[block.id]
}
```

### 2. Stable Block IDs

Each block receives a stable ID, enabling efficient React/Vue reconciliation:

```ts
interface Block {
  id: string      // Stable across updates
  node: RootContent
  status: 'pending' | 'completed'
}
```

### 3. AST Incremental Appending

New nodes are appended to the existing tree without rebuilding:

```ts
// Instead of: root = parse(entireMarkdown)
// We do:
existingRoot.children.push(...newNodes)
```

### 4. Context Caching

Parser state is preserved between chunks for efficient resumption:

```ts
interface ParserContext {
  inFencedCode: boolean
  inContainer: boolean
  listStack: ListInfo[]
  blockquoteDepth: number
}
```

## Extension Points

Incremark provides multiple extension points:

| Level | Extension Type | Example |
|-------|---------------|---------|
| **Parser** | micromark extensions | Custom syntax |
| **Parser** | mdast extensions | Custom AST nodes |
| **Parser** | marked transformers | Custom token handling |
| **Renderer** | Custom components | Replace heading rendering |
| **Renderer** | Custom code blocks | Echarts, Mermaid |
| **Renderer** | Custom containers | Warning, Info boxes |

See [Extensions](/advanced/extensions) for detailed documentation.

---

---
url: /features/auto-scroll.md
---
# Auto Scroll

## Using AutoScrollContainer

::: code-group

```vue [Vue]
<script setup>
import { ref } from 'vue'
import { IncremarkContent, AutoScrollContainer } from '@incremark/vue'

const content = ref('')
const isFinished = ref(false)
const scrollRef = ref()
</script>

<template>
  <AutoScrollContainer ref="scrollRef" :enabled="true" class="h-[500px]">
    <IncremarkContent :content="content" :is-finished="isFinished" />
  </AutoScrollContainer>
</template>
```

```tsx [React]
import { useRef } from 'react'
import { IncremarkContent, AutoScrollContainer } from '@incremark/react'

function App() {
  const scrollRef = useRef(null)

  return (
    <AutoScrollContainer ref={scrollRef} enabled className="h-[500px]">
      <IncremarkContent content={content} isFinished={isFinished} />
    </AutoScrollContainer>
  )
}
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent, AutoScrollContainer } from '@incremark/svelte'

  let content = $state('')
  let isFinished = $state(false)
</script>

<AutoScrollContainer enabled class="h-[500px]">
  <IncremarkContent {content} {isFinished} />
</AutoScrollContainer>
```

```tsx [Solid]
import { createSignal } from 'solid-js'
import { IncremarkContent, AutoScrollContainer } from '@incremark/solid'

function App() {
  const [content, setContent] = createSignal('')
  const [isFinished, setIsFinished] = createSignal(false)

  return (
    <AutoScrollContainer enabled class="h-[500px]">
      <IncremarkContent content={content()} isFinished={isFinished()} />
    </AutoScrollContainer>
  )
}
```

:::

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `enabled` | `boolean` | `true` | Enable auto scroll |
| `threshold` | `number` | `50` | Bottom threshold (pixels) |
| `behavior` | `ScrollBehavior` | `'instant'` | Scroll behavior |

## Exposed Methods

| Method | Description |
|---|---|
| `scrollToBottom()` | Force scroll to bottom |
| `isUserScrolledUp()` | Whether user manually scrolled up |

## Behavior

* Auto scrolls to bottom when content updates.
* Pauses auto scroll when user scrolls up.
* Resumes auto scroll when user scrolls back to bottom.

---

---
url: /features/basic-usage.md
---
# Basic Usage

**IncremarkContent Component Complete Guide**

## Two Input Modes

1. **content mode**: Pass accumulated string + isFinished flag
2. **stream mode**: Pass function returning AsyncGenerator

## Props Reference

```ts
interface IncremarkContentProps {
  // Input (Choose one)
  content?: string                       // Accumulated string
  stream?: () => AsyncGenerator<string>  // Async generator function

  // Status
  isFinished?: boolean                   // Stream finished flag (Required for content mode)

  // Configuration
  incremarkOptions?: UseIncremarkOptions // Parser + Typewriter config

  // Custom Rendering
  components?: ComponentMap              // Custom components
  customContainers?: Record<string, Component>
  customCodeBlocks?: Record<string, Component>
  codeBlockConfigs?: Record<string, CodeBlockConfig>

  // Styling
  showBlockStatus?: boolean              // Show block status border
  pendingClass?: string                  // CSS class for pending block
}
```

### UseIncremarkOptions

```ts
interface UseIncremarkOptions {
  // Parser Options
  gfm?: boolean              // GFM support (tables, tasklists, etc.)
  math?: boolean | MathOptions // Math formula support
  htmlTree?: boolean         // HTML fragment parsing
  containers?: boolean       // ::: container syntax

  // Typewriter Options
  typewriter?: {
    enabled?: boolean
    charsPerTick?: number | [number, number]
    tickInterval?: number
    effect?: 'none' | 'fade-in' | 'typing'
    cursor?: string
  }
}

interface MathOptions {
  // Enable TeX style \(...\) and \[...\] syntax
  tex?: boolean
}
```

### Math Configuration

By default, `math: true` only supports `$...$` and `$$...$$` syntax.

If you need to support TeX/LaTeX style `\(...\)` and `\[...\]` delimiters, enable the **tex** option:

```ts
// Enable TeX style delimiters
const options = {
  math: { tex: true }
}
```

This is useful when processing academic papers or outputs from certain AI tools.

## Advanced: Using `useIncremark`

When finer control is needed:

::: code-group

```vue [Vue]
<script setup>
import { useIncremark, Incremark } from '@incremark/vue'

const { blocks, append, finalize, reset } = useIncremark({ gfm: true })

async function handleStream(stream) {
  reset()
  for await (const chunk of stream) {
    append(chunk)
  }
  finalize()
}
</script>

<template>
  <Incremark :blocks="blocks" />
</template>
```

```tsx [React]
import { useIncremark, Incremark } from '@incremark/react'

function App() {
  const { blocks, append, finalize, reset } = useIncremark({ gfm: true })

  async function handleStream(stream) {
    reset()
    for await (const chunk of stream) {
      append(chunk)
    }
    finalize()
  }

  return <Incremark blocks={blocks} />
}
```

```svelte [Svelte]
<script lang="ts">
  import { useIncremark, Incremark } from '@incremark/svelte'

  const { blocks, append, finalize, reset } = useIncremark({ gfm: true })

  async function handleStream(stream) {
    reset()
    for await (const chunk of stream) {
      append(chunk)
    }
    finalize()
  }
</script>

<Incremark {blocks} />
```

```tsx [Solid]
import { useIncremark, Incremark } from '@incremark/solid'

function App() {
  const { blocks, append, finalize, reset } = useIncremark({ gfm: true })

  async function handleStream(stream) {
    reset()
    for await (const chunk of stream) {
      append(chunk)
    }
    finalize()
  }

  return <Incremark blocks={blocks()} />
}
```

:::

### useIncremark Return Values

| Property | Type | Description |
|---|---|---|
| `blocks` | `Block[]` | All blocks (with stable ID) |
| `markdown` | `string` | Accumulated Markdown |
| `append(chunk)` | `Function` | Append content |
| `finalize()` | `Function` | Complete parsing |
| `reset()` | `Function` | Reset state |
| `render(content)` | `Function` | Render once |
| `isDisplayComplete` | `boolean` | Is typewriter effect complete |

---

---
url: /advanced/benchmark.md
---
# Benchmark

This page describes how to run performance benchmarks comparing Incremark with other Markdown streaming parsers.

## Parsers Tested

| Parser | Approach | Complexity | Description |
|--------|----------|------------|-------------|
| **Incremark** | Incremental parsing | O(n) | Only parses new content |
| **Streamdown** | Full re-parsing | O(n²) | Re-parses entire content each time |
| **markstream-vue** | Full re-parsing | O(n²) | Re-parses entire content each time |
| **ant-design-x** | Full re-parsing | O(n²) | Based on Marked |

## Test Methodology

1. Read all `.md` files from `test-data/` directory
2. Split content into small chunks (5 chars each, simulating AI token-by-token output)
3. For each parser:
   * **Incremark**: Uses `append()` method - only parses new content
   * **Others**: Accumulates string and re-parses entire content each time
4. Measure total time, per-chunk average, and memory usage

## Run Benchmark

### Clone Repository

```bash
git clone https://github.com/kingshuaishuai/incremark.git
cd incremark/benchmark-compare
```

### Install Dependencies

```bash
pnpm install
```

### Add Test Data

Place your Markdown files in the `test-data/` directory:

```bash
# Example: copy some markdown files
cp /path/to/your/*.md test-data/
```

### Run

```bash
# Standard run
pnpm benchmark

# With garbage collection (more accurate memory stats)
pnpm benchmark:gc
```

## Output

The benchmark generates:

* **Console output**: Summary table with timing comparisons
* **benchmark-results.json**: Detailed results in JSON format

### Sample Output

```
📊 Performance Summary (sorted by lines)

| filename          | lines | chars   | Incremark | Streamdown | vs Streamdown |
|-------------------|-------|---------|-----------|------------|---------------|
| short-doc.md      |    91 |   2,341 |      12.0 |       50.5 |          4.2x |
| medium-doc.md     |   147 |   4,123 |       9.0 |       58.8 |          6.6x |
| long-doc.md       |   391 |  12,456 |      19.1 |      208.4 |         10.9x |
| extra-long-doc.md |   916 |  28,912 |      87.7 |     1441.1 |         16.4x |

📈 Performance Summary:
   - Incremark total: 127.8 ms
   - Streamdown total: 1758.8 ms (13.8x slower)
```

## Expected Results

| Document Size | Lines | Incremark Advantage |
|---------------|-------|---------------------|
| Short | ~100 | 4-6x faster |
| Medium | ~400 | 10x+ faster |
| Long | ~900 | 16-65x faster |

::: tip Key Insight
**The longer the document, the greater the advantage of incremental parsing.**

This is because:

* Incremark: O(n) - only processes new content
* Others: O(n²) - re-processes entire accumulated content on each chunk
  :::

## Benchmark Code

The benchmark script is located at `benchmark-compare/benchmark.ts`. Key implementation:

```typescript
// Incremark: O(n) incremental parsing
const parser = createIncremarkParser()
for (const chunk of chunks) {
  parser.append(chunk)  // Only parses new content
}
parser.finalize()

// Others: O(n²) full re-parsing
let accumulated = ''
for (const chunk of chunks) {
  accumulated += chunk
  parseMarkdown(accumulated)  // Re-parses entire content
}
```

## Contributing Test Data

We welcome contributions of real-world Markdown files for benchmarking. Please ensure:

1. Files are reasonably sized (100-1000+ lines)
2. Content is appropriate for public sharing
3. Files represent typical AI output scenarios

Submit via pull request to the `benchmark-compare/test-data/` directory.

---

---
url: /guide/comparison.md
---
# Comparison with Other Solutions

This guide provides a deep technical comparison between **Incremark**, **Ant Design X Markdown**, and **MarkStream Vue**, analyzing their architectural implementation of streaming Markdown rendering.

## Architecture & Flow

### 1. Incremark (Our Solution)

**Strategy: Incremental Parsing + Structural Typewriter Animation**

```mermaid
graph TD
    Input["Streaming Chunk (e.g. 'ng')"] --> Parser["IncremarkParser (Incremental)"]
    subgraph Core ["Incremental Engine"]
        Parser --> Boundary["Boundary Detection (State-aware)"]
        Boundary --> Completed["Completed Blocks (Cached)"]
        Boundary --> Pending["Pending Block (Updating)"]
    end
    Pending --> Transformer["BlockTransformer (Animation Manager)"]
    Transformer --> AST["Incremental AST Append (TextChunk tracking)"]
    AST --> Renderer["Framework Renderer (React/Vue)"]
    Renderer --> DOM["Targeted Patching"]
```

* **Key Advantage**: Only parses what is new or unstable. Animation happens at the AST node level, avoiding re-traversal of stable nodes. Performance is **O(N)**.

***

### 2. Ant Design X (`x-markdown`)

**Strategy: Regex Repair + Full Re-parsing (Marked)**

```mermaid
graph TD
    Input["Streaming String"] --> Hook["useStreaming (Regex Interception)"]
    subgraph Logic ["Repair Logic"]
        Hook --> Regex["STREAM_INCOMPLETE_REGEX (Detects broken links/images/tables)"]
        Regex --> Buffer["Buffer (Wait for complete Token)"]
    end
    Buffer --> Marked["Marked.js (Full Re-parse)"]
    Marked --> HTML["HTML String"]
    HTML --> ReactParser["html-react-parser (React Conversion)"]
    ReactParser --> Animation["AnimationText (Text Slicing)"]
    Animation --> DOM["React DOM"]
```

* **Key Advantage**: Robust visual state patching via regex. However, it requires a full re-parse of the entire accumulated string on every update. Performance is **O(N²)**.

***

### 3. MarkStream Vue

**Strategy: Full Re-parsing + Virtualized/Batched Rendering (markdown-it)**

```mermaid
graph TD
    Input["Full Markdown String"] --> PreProcess["Regex Patching (parseMarkdownToStructure)"]
    PreProcess --> MarkdownIt["markdown-it (Full Re-parse)"]
    subgraph Render ["Optimized Rendering Layer"]
        MarkdownIt --> Batch["Batch Rendering (requestIdleCallback)"]
        Batch --> Virtual["Virtualization (Render only visible nodes)"]
    end
    Virtual --> VueDOM["Vue Component Tree"]
```

* **Key Advantage**: Accepts the cost of re-parsing but optimizes the DOM layer via virtualization and idling batch updates. Perfect for viewing extremely large history or static documents.

***

## Technical Comparison Matrix

| Dimension | Ant Design X (epx) | MarkStream Vue (epx2) | Incremark (core) |
| :--- | :--- | :--- | :--- |
| **Parsing Engine** | `marked` | `markdown-it` | **Dual-Engine: `marked` (default) + `micromark`** |
| **Parsing Strategy** | Full Re-parse | Full Re-parse | **Incremental Parsing** |
| **Parsing Complexity** | O(N²) | O(N²) | **O(N)** |
| **Boundary Handling** | **Regex Interception** | **Regex Patching** | **State-based Boundary Detection** |
| **Typewriter Effect** | Text Layer (String slicing) | Component Layer (`<transition>`) | **AST Node Layer** (Incremental Append) |
| **Animation Perf** | Degrades with content length | O(1) per mounting | **Constant CPU usage per tick** |
| **Big Doc Optimization** | None | **Virtualization + Batching** | **Stable IDs + Selective Rendering** |
| **Plugin Ecosystem** | Limited | markdown-it plugins | **micromark + mdast + marked extensions** |
| **Framework Support** | React | Vue | **Vue + React + Svelte (Shared Core)** |

***

## Deep Dive

### 1. Incremental vs Full Parsing

For a 10,000-character document with 10 new characters added:

* **Full Parsing**: The parser must scan all 10,010 characters. Processing time grows exponentially with conversation length.
* **Incremental Parsing**: `IncremarkParser` identifies the first 10,000 characters as belonging to "stable blocks" and only performs limited contextual analysis on the new 10 characters.

### 2. Animation Precision

* **Text Layer (Ant Design X)**: The animator doesn't know if a character belongs to a heading or a code block; it just slices a string. This can cause structural "jumping" during high-frequency updates.
* **Component Layer (MarkStream Vue)**: Animation is often restricted to paragraph or block-level fade-ins, making it hard to achieve a smooth, character-by-character "typewriter" feel.
* **AST Layer (Incremark)**: `BlockTransformer` is aware of the AST structure. It knows exactly where the new text nodes are. By maintaining a `TextChunk` queue within nodes, it enables smooth character-level animation while maintaining structural integrity (e.g., ensuring a `**bold**` block never crashes the renderer mid-animation).

***

## Conclusion & Best Use Cases

### **Ant Design X** (The Design System Choice)

* **Best For**: Rapidly building AI chat interfaces for web applications already using Ant Design. Its regex repair strategy is very reliable for common Markdown edge cases in shorter chats.

### **MarkStream Vue** (The Document Viewer)

* **Best For**: Vue applications that need to display extremely large AI responses or long-form documents where virtualization (scrolling performance) is the priority.

### **Incremark** (The High-Performance Standard)

* **Best For**: Corporate-grade AI applications with long context windows (100k+ tokens), multi-framework teams, or any scenario where the smoothest possible "human-like" typing animation is required without sacrificing battery life or performance.

***

## Benchmark Results

We conducted extensive benchmarks across 38 real-world markdown documents (6,484 lines, 128.55 KB total).

> 📊 See the [complete benchmark data](/advanced/engines#complete-benchmark-data) for detailed results of all 38 test files.

### Overall Performance (Averages)

| Comparison | Average Advantage |
|------------|-------------------|
| vs Streamdown | ~**6.1x faster** |
| vs ant-design-x | ~**7.2x faster** |
| vs markstream-vue | ~**28.3x faster** |

> ⚠️ These are averages across all test scenarios. Individual performance varies by content type.

### Scaling with Document Size

The larger the document, the greater Incremark's advantage — O(n) vs O(n²):

| File | Lines | Size | Incremark | ant-design-x | Advantage |
|------|-------|------|-----------|--------------|-----------|
| introduction.md | 34 | 1.57 KB | 5.6 ms | 12.8 ms | **2.3x** |
| comparison.md | 109 | 5.39 KB | 20.5 ms | 85.2 ms | **4.1x** |
| BLOCK\_TRANSFORMER.md | 489 | 9.24 KB | 75.7 ms | 619.9 ms | **8.2x** |
| test-md-01.md | 916 | 17.67 KB | 87.7 ms | 1656.9 ms | **18.9x** 🚀 |

### Understanding Performance Differences

#### Why Incremark is Sometimes "Slower" vs Streamdown

In some benchmarks, Incremark appears slower than Streamdown:

| File | Incremark | Streamdown | Reason |
|------|-----------|------------|--------|
| footnotes.md | 1.7 ms | 0.2 ms | Streamdown **doesn't support footnotes** |
| FOOTNOTE\_FIX\_SUMMARY.md | 22.7 ms | 0.5 ms | Same — skips footnote parsing |

**This is a feature difference, not a performance issue:**

* Streamdown skips unsupported syntax → appears faster
* Incremark fully parses footnotes, math, containers → does more work

#### Incremark's Enhanced Features

Incremark extends Marked with custom extensions that Streamdown doesn't support:

| Feature | Incremark | Streamdown |
|---------|-----------|------------|
| **Footnotes** | ✅ Full GFM footnotes | ❌ Not supported |
| **Math Blocks** | ✅ `$...$` and `$$...$$` | ⚠️ Partial |
| **Custom Containers** | ✅ `:::tip`, `:::warning` | ❌ Not supported |
| **Inline HTML Parsing** | ✅ Full HTML tree | ⚠️ Basic |

#### Where Incremark Truly Shines

For standard markdown (no footnotes), Incremark consistently outperforms:

| File | Lines | Incremark | Streamdown | vs Streamdown |
|------|-------|-----------|------------|---------------|
| concepts.md | 91 | 12.0 ms | 50.5 ms | **4.2x** |
| complex-html-examples.md | 147 | 9.0 ms | 58.8 ms | **6.6x** |
| OPTIMIZATION\_SUMMARY.md | 391 | 19.1 ms | 208.4 ms | **10.9x** |
| test-md-01.md | 916 | 87.7 ms | 1441.1 ms | **16.4x** |

### Why Incremark Excels

1. **Incremental Parsing O(n)**: Each append only processes new content
2. **Linear Scaling**: Advantage grows with document size
3. **Streaming-Optimized**: Microsecond-level chunk processing
4. **Feature-Rich**: Supports footnotes, math, containers without sacrificing speed

### Ideal Use Cases

✅ **Incremark shines in:**

* AI chat with streaming output (Claude, ChatGPT, etc.)
* Real-time markdown editors
* Large document incremental rendering
* Long-running conversations with 100k+ tokens
* Content requiring footnotes, math, or custom containers

⚠️ **Consider alternatives for:**

* One-time static markdown rendering
* Very small files (<500 characters)

---

---
url: /guide/concepts.md
---
# Core Concepts

Understanding how Incremark works will help you build high-performance, flicker-free AI chat applications.

## Dual-Engine Architecture

Incremark supports two parsing engines, allowing you to choose based on your needs:

| Engine | Characteristics | Best For |
|--------|----------------|----------|
| **marked** (default) | Extremely fast, streaming-optimized | Real-time AI chat, performance-critical scenarios |
| **micromark** | CommonMark compliant, rich plugin ecosystem | Complex extensions, strict spec compliance |

Both engines share the same incremental parsing layer and produce identical mdast output, ensuring consistent behavior regardless of which engine you choose.

## Incremental Parsing Flow

Traditional Markdown parsers (like `marked` or `markdown-it`) are designed for static documents. In a streaming context, they must re-parse the entire document from scratch every time a new character is received.

**Incremark** employs a completely different "Incremental Parsing" strategy:

```mermaid
graph TD
    Stream["Markdown Stream"] --> Buffer["Line Buffer"]
    Buffer --> Boundary["Boundary Detection"]
    
    subgraph Engine ["Incremental Engine"]
        Boundary -- "Stable Boundary Detected" --> Completed["Completed Block (Cached)"]
        Boundary -- "Inside Unstable Region" --> Pending["Pending Block"]
    end
    
    Completed --> Cache["AST Cache (Mdast)"]
    Pending --> ReParse["Local Re-parse (Current Block Only)"]
    
    Cache --> FinalAST["Full AST (Root)"]
    ReParse --> FinalAST
    
    FinalAST --> Transformer["BlockTransformer (Animation handling)"]
```

## Block Lifecycle

In Incremark, every top-level element (heading, paragraph, code block, etc.) is treated as an independent **Block**. They go through a lifecycle from "uncertain" to "stable":

| State | Description | Handling Strategy |
| :--- | :--- | :--- |
| **Pending** | Currently streaming; content and type may change at any time. | Every time new content arrives, a micro-parse is performed only on the text segment for this block. |
| **Completed** | Confirmed as finished; subsequent input will not affect this block. | **Persistent Cache**. Unless the stream is reset, it is no longer involved in parsing or re-rendering. |

> \[!TIP]
> **Why do we need a Pending state?**
> In Markdown, the prefix determines the type. For example, when `#` is input, it could be a heading or just text. The type is only truly determined when a space or newline is received.

## Boundary Detection Rules

Incremark uses heuristic rules to determine when a block can transition from `Pending` to `Completed`:

### 1. Simple Block Boundaries

* **Empty Line**: The natural end of a paragraph.
* **New Heading / Thematic Break**: The appearance of a new block implies the end of the previous non-container block.

### 2. Fenced Block Boundaries

* **Code Block (\`\`\`)**: Must detect a matching closing fence. Until the closing fence appears, the entire code block remains `Pending`.
* **Custom Container (:::)**: Same as above; supports nested detection.

### 3. Nested Block Boundaries

* **Lists and Blockquotes**: The parser continuously tracks the current indentation level and blockquote depth. When a new line's indentation retreats or the quote marker disappears, the previous block is determined to be finished.

## Context Tracking

To accurately identify boundaries during the streaming process, the parser maintains a lightweight state machine:

```ts
interface BlockContext {
  inFencedCode: boolean;     // Processing a code block
  inContainer: boolean;      // Processing a custom container
  listStack: ListInfo[];     // Tracking nested list state
  blockquoteDepth: number;   // Tracking blockquote depth
}
```

## Performance Analysis

Thanks to the incremental mechanism, Incremark's performance is almost independent of the total document length and only linearly related to the current chunk size.

| Dimension | Traditional Full Parsing | Incremark Incremental Parsing |
| :--- | :--- | :--- |
| **Incremental Complexity** | O(N) | **O(K)** |
| **Total Parsing Complexity** | O(N²) | **O(N)** |
| **Memory Overhead** | High (Repeated object creation) | **Low (Incremental AST reuse)** |
| **UI Responsiveness** | Performance degrades as N grows | **Maintains 60fps smooth performance** |

*Note: N is total document length, K is current chunk size.*

## Typewriter Effect (BlockTransformer)

After the AST is parsed, the `BlockTransformer` acts as a filtering layer before rendering. It converts the "instant results" of parsing into a "progressive process":

1. **Node Tracking**: Keeps track of which characters have already been "played."
2. **TextChunk Wrapping**: Wraps newly added text nodes into `TextChunk`, allowing the rendering layer to implement fade-in animations.
3. **Smart Skipping**: It can strategically skip animations if the user requests immediate display or for non-text nodes (like images).

---

---
url: /features/custom-codeblocks.md
---
# Custom Code Blocks

## Overview

Incremark provides a layered architecture for code block customization:

1. **customCodeBlocks**: Language-specific custom components (highest priority)
2. **Built-in Mermaid**: Automatic Mermaid diagram support
3. **components\['code']**: Custom default code rendering
4. **Default**: Built-in Shiki syntax highlighting

## Custom Code Block Rendering

Useful for specialized rendering like echarts, custom diagrams, etc.

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent } from '@incremark/vue'
import EchartsBlock from './EchartsBlock.vue'
import PlantUMLBlock from './PlantUMLBlock.vue'

const customCodeBlocks = {
  echarts: EchartsBlock,
  plantuml: PlantUMLBlock
}

// Config: whether to render while pending
const codeBlockConfigs = {
  echarts: { takeOver: true }  // Render even when pending
}
</script>

<template>
  <IncremarkContent
    :content="content"
    :custom-code-blocks="customCodeBlocks"
    :code-block-configs="codeBlockConfigs"
  />
</template>
```

```tsx [React]
import { IncremarkContent } from '@incremark/react'

function EchartsBlock({ codeStr, lang, completed, takeOver }) {
  // codeStr is code content
  // lang is language identifier
  // completed indicates if the block is complete
  return <div className="echarts">{codeStr}</div>
}

const customCodeBlocks = {
  echarts: EchartsBlock
}

<IncremarkContent
  content={content}
  customCodeBlocks={customCodeBlocks}
/>
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent } from '@incremark/svelte'
  import EchartsBlock from './EchartsBlock.svelte'

  const customCodeBlocks = {
    echarts: EchartsBlock
  }
</script>

<IncremarkContent {content} {customCodeBlocks} />
```

```tsx [Solid]
import { IncremarkContent } from '@incremark/solid'

function EchartsBlock(props: {
  codeStr: string
  lang: string
  completed: boolean
  takeOver: boolean
}) {
  return <div class="echarts">{props.codeStr}</div>
}

const customCodeBlocks = {
  echarts: EchartsBlock
}

<IncremarkContent content={content()} customCodeBlocks={customCodeBlocks} />
```

:::

## Custom Code Block Props

When creating a custom code block component, your component will receive these props:

| Prop | Type | Description |
|---|---|---|
| `codeStr` | `string` | The code content |
| `lang` | `string` | Language identifier |
| `completed` | `boolean` | Whether the block is complete |
| `takeOver` | `boolean` | Whether takeOver mode is enabled |

## codeBlockConfigs

| Option | Type | Default | Description |
|---|---|---|---|
| `takeOver` | `boolean` | `false` | Take over rendering while pending |

## Built-in Mermaid Support

::: tip
Mermaid diagrams are supported out of the box! No configuration needed.
:::

Incremark automatically renders Mermaid diagrams with:

* Debounced rendering for streaming input
* Preview/source toggle
* Copy functionality
* Dark theme by default

```markdown
\`\`\`mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> A
\`\`\`
```

If you want to override the built-in Mermaid rendering, use `customCodeBlocks`:

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent } from '@incremark/vue'
import MyMermaidBlock from './MyMermaidBlock.vue'

const customCodeBlocks = {
  mermaid: MyMermaidBlock  // Override built-in Mermaid
}
</script>

<template>
  <IncremarkContent
    :content="content"
    :custom-code-blocks="customCodeBlocks"
  />
</template>
```

:::

## Comparison with components\['code']

| Feature | customCodeBlocks | components\['code'] |
|---|---|---|
| Scope | Specific languages | All code blocks (fallback) |
| Priority | Highest | Lower than customCodeBlocks and Mermaid |
| Use case | Specialized rendering (echarts, diagrams) | Custom syntax highlighting theme |
| Props | `codeStr`, `lang`, `completed`, `takeOver` | `node`, `theme`, `fallbackTheme`, `disableHighlight` |

See [Custom Components](/features/custom-components) for more details on `components['code']`.

---

---
url: /features/custom-components.md
---
# Custom Components

## Custom Node Rendering

::: code-group

```vue [Vue]
<script setup>
import { h } from 'vue'
import { IncremarkContent } from '@incremark/vue'

const CustomHeading = {
  props: ['node'],
  setup(props) {
    const level = props.node.depth
    return () => h(`h${level}`, { class: 'my-heading' }, props.node.children)
  }
}

const components = {
  heading: CustomHeading
}
</script>

<template>
  <IncremarkContent :content="content" :components="components" />
</template>
```

```tsx [React]
import { IncremarkContent } from '@incremark/react'

function CustomHeading({ node, children }) {
  const Tag = `h${node.depth}` as keyof JSX.IntrinsicElements
  return <Tag className="my-heading">{children}</Tag>
}

const components = {
  heading: CustomHeading
}

<IncremarkContent content={content} components={components} />
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent } from '@incremark/svelte'
  import CustomHeading from './CustomHeading.svelte'

  const components = {
    heading: CustomHeading
  }
</script>

<IncremarkContent {content} {components} />
```

```tsx [Solid]
import { IncremarkContent } from '@incremark/solid'
import CustomHeading from './CustomHeading'

const components = {
  heading: CustomHeading
}

<IncremarkContent content={content()} components={components} />
```

:::

## Component Types

| Type | Node |
|---|---|
| `heading` | Headings h1-h6 |
| `paragraph` | Paragraph |
| `code` | Code block (default rendering only) |
| `list` | List |
| `listItem` | List item |
| `table` | Table |
| `blockquote` | Blockquote |
| `thematicBreak` | Divider |
| `image` | Image |
| `link` | Link |
| `inlineCode` | Inline code |

## Code Component Behavior

::: tip Important
When customizing the `code` component, it only replaces the **default code block rendering**. The built-in Mermaid support and `customCodeBlocks` logic are preserved.
:::

The code block rendering follows this priority:

1. **customCodeBlocks**: Language-specific custom components (e.g., `echarts`, `mermaid`)
2. **Built-in Mermaid**: Automatic Mermaid diagram rendering
3. **components\['code']**: Custom default code block (if provided)
4. **Default**: Built-in syntax highlighting with Shiki

This means:

* If you set `components: { code: MyCodeBlock }`, it only affects regular code blocks
* Mermaid diagrams will still use the built-in Mermaid renderer
* `customCodeBlocks` configurations take precedence

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent } from '@incremark/vue'
import MyCodeBlock from './MyCodeBlock.vue'

// This only replaces default code rendering
// Mermaid and customCodeBlocks are not affected
const components = {
  code: MyCodeBlock
}
</script>

<template>
  <IncremarkContent :content="content" :components="components" />
</template>
```

```tsx [React]
import { IncremarkContent } from '@incremark/react'

function MyCodeBlock({ node }) {
  return (
    <pre className="my-code">
      <code>{node.value}</code>
    </pre>
  )
}

const components = {
  code: MyCodeBlock
}

<IncremarkContent content={content} components={components} />
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent } from '@incremark/svelte'
  import MyCodeBlock from './MyCodeBlock.svelte'

  const components = {
    code: MyCodeBlock
  }
</script>

<IncremarkContent {content} {components} />
```

```tsx [Solid]
import { IncremarkContent } from '@incremark/solid'

function MyCodeBlock(props: { node: any }) {
  return (
    <pre class="my-code">
      <code>{props.node.value}</code>
    </pre>
  )
}

const components = {
  code: MyCodeBlock
}

<IncremarkContent content={content()} components={components} />
```

:::

### Custom Code Component Props

When creating a custom code component, your component will receive these props:

| Prop | Type | Description |
|---|---|---|
| `node` | `Code` | The code node from mdast |
| `theme` | `string` | Shiki theme name |
| `fallbackTheme` | `string` | Fallback theme when loading fails |
| `disableHighlight` | `boolean` | Whether to disable syntax highlighting |

The `node` object contains:

* `node.value`: The code content as a string
* `node.lang`: The language identifier (e.g., `'typescript'`, `'python'`)
* `node.meta`: Optional metadata after the language identifier

---

---
url: /features/custom-containers.md
---
# Custom Containers

## Markdown Syntax

```markdown
::: warning
This is a warning
:::

::: info Title
This is an info box
:::
```

## Defining Container Components

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent } from '@incremark/vue'
import WarningContainer from './WarningContainer.vue'
import InfoContainer from './InfoContainer.vue'

const customContainers = {
  warning: WarningContainer,
  info: InfoContainer
}
</script>

<template>
  <IncremarkContent
    :content="content"
    :incremark-options="{ containers: true }"
    :custom-containers="customContainers"
  />
</template>
```

```tsx [React]
import { IncremarkContent } from '@incremark/react'

function WarningContainer({ node, children }) {
  return (
    <div className="warning-box">
      <div className="warning-title">{node.title || 'Warning'}</div>
      <div className="warning-content">{children}</div>
    </div>
  )
}

const customContainers = {
  warning: WarningContainer
}

<IncremarkContent
  content={content}
  incremarkOptions={{ containers: true }}
  customContainers={customContainers}
/>
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent } from '@incremark/svelte'
  import WarningContainer from './WarningContainer.svelte'

  const customContainers = {
    warning: WarningContainer
  }
</script>

<IncremarkContent
  {content}
  incremarkOptions={{ containers: true }}
  {customContainers}
/>
```

```tsx [Solid]
import { IncremarkContent } from '@incremark/solid'

function WarningContainer(props: { node: any; children: any }) {
  return (
    <div class="warning-box">
      <div class="warning-title">{props.node.title || 'Warning'}</div>
      <div class="warning-content">{props.children}</div>
    </div>
  )
}

const customContainers = {
  warning: WarningContainer
}

<IncremarkContent
  content={content()}
  incremarkOptions={{ containers: true }}
  customContainers={customContainers}
/>
```

:::

## Container Component Props

| Prop | Type | Description |
|---|---|---|
| `node` | `ContainerNode` | Container node |
| `node.name` | `string` | Container name (warning, info, etc.) |
| `node.title` | `string?` | Container title |
| `children` | - | Container content |

---

---
url: /examples/custom-stream.md
---
# Custom Stream Integration

Parsing a raw standard `Response` stream.

## Example

```ts
import { IncremarkContent } from '@incremark/react'

function App() {
  const [stream, setStream] = useState(null)

  function start() {
    async function* fetchStream() {
      const response = await fetch('/api/stream')
      const reader = response.body.getReader()
      const decoder = new TextDecoder()

      while (true) {
        const { done, value } = await reader.read()
        if (done) break
        yield decoder.decode(value, { stream: true })
      }
    }
    
    setStream(() => fetchStream)
  }

  return (
    <>
      <button onClick={start}>Start</button>
      <IncremarkContent stream={stream} />
    </>
  )
}
```

---

---
url: /features/devtools.md
---
# DevTools

Incremark DevTools provides a visual interface for debugging and inspecting incremental markdown rendering. It supports real-time monitoring of parser state, block details, AST structure, and append history.

## Installation

::: code-group

```bash [npm]
npm install @incremark/devtools
```

```bash [pnpm]
pnpm add @incremark/devtools
```

```bash [yarn]
yarn add @incremark/devtools
```

:::

## Basic Usage

### Vue

```vue
<script setup>
import { createDevTools } from '@incremark/devtools'
import { IncremarkContent } from '@incremark/vue'
import { onMounted, onUnmounted } from 'vue'

// Create devtools instance
const devtools = createDevTools({
  locale: 'en-US' // 'en-US' or 'zh-CN'
})

onMounted(() => {
  devtools.mount()
})

onUnmounted(() => {
  devtools.unmount()
})
</script>

<template>
  <IncremarkContent
    :content="markdown"
    :devtools="devtools"
    devtoolsId="main-parser"
    devtoolsLabel="Main Content"
  />
</template>
```

### React

```tsx
import { createDevTools } from '@incremark/devtools'
import { IncremarkContent } from '@incremark/react'
import { useEffect, useRef } from 'react'

function App() {
  const devtools = useRef(createDevTools({
    locale: 'en-US' // 'en-US' or 'zh-CN'
  }))

  useEffect(() => {
    devtools.current.mount()
    return () => devtools.current.unmount()
  }, [])

  return (
    <IncremarkContent
      content={markdown}
      devtools={devtools.current}
      devtoolsId="main-parser"
      devtoolsLabel="Main Content"
    />
  )
}
```

### Svelte

```svelte
<script lang="ts">
  import { createDevTools } from '@incremark/devtools'
  import { IncremarkContent } from '@incremark/svelte'
  import { onMount, onDestroy } from 'svelte'

  let devtools = createDevTools({
    locale: 'en-US' // 'en-US' or 'zh-CN'
  })

  onMount(() => {
    devtools.mount()
  })

  onDestroy(() => {
    devtools.unmount()
  })
</script>

<IncremarkContent
  {content}
  {devtools}
  devtoolsId="main-parser"
  devtoolsLabel="Main Content"
/>
```

### Solid

```tsx
import { createDevTools } from '@incremark/devtools'
import { IncremarkContent } from '@incremark/solid'
import { onMount, onCleanup } from 'solid-js'

const devtools = createDevTools({
  locale: 'en-US' // 'en-US' or 'zh-CN'
})

onMount(() => {
  devtools.mount()
})

onCleanup(() => {
  devtools.unmount()
})

return (
  <IncremarkContent
    content={markdown()}
    devtools={devtools}
    devtoolsId="main-parser"
    devtoolsLabel="Main Content"
  />
)
```

## Configuration Options

```ts
const devtools = createDevTools({
  open: false,                    // Initially open the panel
  position: 'bottom-right',       // Position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  theme: 'dark',                  // Theme: 'dark' | 'light'
  locale: 'en-US'                 // Locale: 'en-US' | 'zh-CN'
})
```

## Dynamic Locale Switching

You can dynamically change the DevTools language:

```ts
import { setLocale } from '@incremark/devtools'

// Switch to Chinese
setLocale('zh-CN')

// Switch to English
setLocale('en-US')
```

## IncremarkContent Props

When using DevTools with `IncremarkContent`, you can pass these additional props:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `devtools` | `IncremarkDevTools` | - | The devtools instance to register with |
| `devtoolsId` | `string` | Auto-generated | Unique identifier for this parser in devtools |
| `devtoolsLabel` | `string` | `devtoolsId` | Display label for this parser in devtools |

## Features

DevTools provides four main tabs:

### Overview

* Total block count
* Completed and pending blocks
* Character count
* Node type distribution
* Current streaming status

### Blocks

* List of all parsed blocks
* Block details (ID, type, status, raw text)
* AST node inspection
* Real-time status updates

### AST

* Complete Abstract Syntax Tree view
* Interactive tree structure
* Node property inspection

### Timeline

* Append history with timestamps
* Track incremental updates
* Block count changes over time

## Multiple Parsers

DevTools supports monitoring multiple parsers simultaneously:

```vue
<template>
  <IncremarkContent
    :content="content1"
    :devtools="devtools"
    devtoolsId="parser-1"
    devtoolsLabel="Main Content"
  />
  <IncremarkContent
    :content="content2"
    :devtools="devtools"
    devtoolsId="parser-2"
    devtoolsLabel="Sidebar Content"
  />
</template>
```

Use the dropdown in DevTools to switch between different parsers.

---

---
url: /zh/features/devtools.md
---
# DevTools 开发工具

Incremark DevTools 提供了一个可视化界面，用于调试和检查增量 Markdown 渲染。它支持实时监控解析器状态、块详情、AST 结构和追加历史。

## 安装

::: code-group

```bash [npm]
npm install @incremark/devtools
```

```bash [pnpm]
pnpm add @incremark/devtools
```

```bash [yarn]
yarn add @incremark/devtools
```

:::

## 基本用法

### Vue

```vue
<script setup>
import { createDevTools } from '@incremark/devtools'
import { IncremarkContent } from '@incremark/vue'
import { onMounted, onUnmounted } from 'vue'

// 创建 devtools 实例
const devtools = createDevTools({
  locale: 'zh-CN' // 'en-US' 或 'zh-CN'
})

onMounted(() => {
  devtools.mount()
})

onUnmounted(() => {
  devtools.unmount()
})
</script>

<template>
  <IncremarkContent
    :content="markdown"
    :devtools="devtools"
    devtoolsId="main-parser"
    devtoolsLabel="主内容"
  />
</template>
```

### React

```tsx
import { createDevTools } from '@incremark/devtools'
import { IncremarkContent } from '@incremark/react'
import { useEffect, useRef } from 'react'

function App() {
  const devtools = useRef(createDevTools({
    locale: 'zh-CN' // 'en-US' 或 'zh-CN'
  }))

  useEffect(() => {
    devtools.current.mount()
    return () => devtools.current.unmount()
  }, [])

  return (
    <IncremarkContent
      content={markdown}
      devtools={devtools.current}
      devtoolsId="main-parser"
      devtoolsLabel="主内容"
    />
  )
}
```

### Svelte

```svelte
<script lang="ts">
  import { createDevTools } from '@incremark/devtools'
  import { IncremarkContent } from '@incremark/svelte'
  import { onMount, onDestroy } from 'svelte'

  let devtools = createDevTools({
    locale: 'zh-CN' // 'en-US' 或 'zh-CN'
  })

  onMount(() => {
    devtools.mount()
  })

  onDestroy(() => {
    devtools.unmount()
  })
</script>

<IncremarkContent
  {content}
  {devtools}
  devtoolsId="main-parser"
  devtoolsLabel="主内容"
/>
```

### Solid

```tsx
import { createDevTools } from '@incremark/devtools'
import { IncremarkContent } from '@incremark/solid'
import { onMount, onCleanup } from 'solid-js'

const devtools = createDevTools({
  locale: 'zh-CN' // 'en-US' 或 'zh-CN'
})

onMount(() => {
  devtools.mount()
})

onCleanup(() => {
  devtools.unmount()
})

return (
  <IncremarkContent
    content={markdown()}
    devtools={devtools}
    devtoolsId="main-parser"
    devtoolsLabel="主内容"
  />
)
```

## 配置选项

```ts
const devtools = createDevTools({
  open: false,                    // 初始是否打开面板
  position: 'bottom-right',       // 位置: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  theme: 'dark',                  // 主题: 'dark' | 'light'
  locale: 'zh-CN'                 // 语言: 'en-US' | 'zh-CN'
})
```

## 动态语言切换

您可以动态更改 DevTools 的语言：

```ts
import { setLocale } from '@incremark/devtools'

// 切换到中文
setLocale('zh-CN')

// 切换到英文
setLocale('en-US')
```

## IncremarkContent 属性

将 DevTools 与 `IncremarkContent` 一起使用时，您可以传递以下额外属性：

| 属性 | 类型 | 默认值 | 描述 |
|------|------|---------|-------------|
| `devtools` | `IncremarkDevTools` | - | 要注册的 devtools 实例 |
| `devtoolsId` | `string` | 自动生成 | 在 devtools 中此解析器的唯一标识符 |
| `devtoolsLabel` | `string` | `devtoolsId` | 在 devtools 中此解析器的显示标签 |

## 功能特性

DevTools 提供四个主要选项卡：

### 概览

* 总块数
* 已完成和待处理的块
* 字符数
* 节点类型分布
* 当前流式处理状态

### 块

* 所有已解析块的列表
* 块详情（ID、类型、状态、原始文本）
* AST 节点检查
* 实时状态更新

### AST

* 完整的抽象语法树视图
* 交互式树结构
* 节点属性检查

### 时间线

* 带时间戳的追加历史
* 跟踪增量更新
* 块数随时间的变化

## 多解析器支持

DevTools 支持同时监控多个解析器：

```vue
<template>
  <IncremarkContent
    :content="content1"
    :devtools="devtools"
    devtoolsId="parser-1"
    devtoolsLabel="主内容"
  />
  <IncremarkContent
    :content="content2"
    :devtools="devtools"
    devtoolsId="parser-2"
    devtoolsLabel="侧边栏内容"
  />
</template>
```

使用 DevTools 中的下拉菜单在不同解析器之间切换。

---

---
url: /advanced/engines.md
---
# Dual-Engine Architecture

Incremark features a **dual-engine parsing system** — an important architectural decision we made during development. We want to give users the freedom to choose: find the perfect balance between extreme performance and perfect compatibility for your specific use case.

## Why Dual Engines?

During Incremark's development, we faced a core question: **How do we achieve the best performance in streaming AI scenarios?**

After extensive research and testing, we discovered:

* **Marked** is extremely fast, but doesn't natively support footnotes, math, and other advanced features
* **Micromark** has perfect spec compliance and a rich plugin ecosystem, but has a larger bundle size

Our decision: **Why not both?**

With the dual-engine architecture, users can choose based on their needs:

* Performance-sensitive AI chat scenarios → Use the Marked engine
* Documents requiring strict spec compliance → Use the Micromark engine

## Engine Overview

| Engine | Speed | Features | Bundle Size | Best For |
|--------|-------|----------|-------------|----------|
| **Marked** (Default) | ⚡⚡⚡⚡⚡ | Standard + Enhanced Extensions | Smaller | Real-time streaming, AI chat |
| **Micromark** | ⚡⚡⚡ | Full CommonMark + Plugins | Larger | Complex documents, strict compliance |

## Marked Engine (Default)

The **Marked engine** is our default choice, deeply optimized for **streaming AI scenarios**.

### Why Marked as the Default?

1. **Extreme parsing speed**: Marked is one of the fastest Markdown parsers in the JavaScript ecosystem
2. **Battle-tested stability**: Over 10 years of history, validated by countless projects
3. **Easy to extend**: Flexible extension mechanism allows us to add features as needed
4. **Small bundle size**: Benefits frontend tree-shaking optimization

### What We Enhanced for Marked

Native Marked is a "good enough" parser focused on standard Markdown syntax, without many advanced features. But in AI scenarios, we often need these features.

Therefore, Incremark extends Marked with custom extensions:

| Feature | Native Marked | Incremark Enhanced | Description |
|---------|---------------|-------------------|-------------|
| **Footnotes** | ❌ Not supported | ✅ Full GFM footnotes | `[^1]` references and `[^1]: content` definitions |
| **Math Blocks** | ❌ Not supported | ✅ Inline and block math | `$E=mc^2$` and `$$...$$` |
| **Custom Containers** | ❌ Not supported | ✅ Directive syntax | `:::tip`, `:::warning`, `:::danger` |
| **Inline HTML Parsing** | ⚠️ Preserved as-is | ✅ Structured parsing | Parses HTML into manipulable AST nodes |
| **Optimistic References** | ❌ Not supported | ✅ Streaming-friendly | Gracefully handles incomplete links/images during streaming |
| **Footnote Definition Blocks** | ❌ Not supported | ✅ Multi-line content | Supports complex footnotes with code blocks, lists, etc. |

> 💡 These extensions are carefully designed for AI scenarios. They provide full functionality while minimizing performance overhead.

### Usage

The Marked engine is the **default**, so you don't need any special configuration:

```vue
<script setup>
import { ref } from 'vue'
import { IncremarkContent } from '@incremark/vue'

const content = ref('')
const isFinished = ref(false)
</script>

<template>
  <!-- Marked engine is used by default -->
  <IncremarkContent 
    :content="content" 
    :is-finished="isFinished"
  />
</template>
```

### Enable/Disable Specific Features

```vue
<template>
  <IncremarkContent 
    :content="content" 
    :is-finished="isFinished"
    :incremark-options="{
      gfm: true,        // GFM extensions (tables, strikethrough, etc.)
      math: true,       // Math formulas
      containers: true, // Custom containers
      htmlTree: true    // HTML structured parsing
    }"
  />
</template>
```

## Micromark Engine

The **Micromark engine** is the choice for perfect spec compliance.

### Why Offer Micromark?

While the Marked engine satisfies most scenarios, some users may have stricter requirements:

1. **Strict CommonMark compliance**: Micromark is currently the most spec-compliant parser
2. **Rich plugin ecosystem**: GFM, Math, Directive plugins are all community-polished
3. **Precise position information**: AST nodes include accurate line/column positions for error locating
4. **Better edge case handling**: More stable in complex nested scenarios

### Usage

To use the Micromark engine, you need to import `MicromarkAstBuilder` and pass it via `astBuilder` option:

```ts
// In your composable or setup
import { createIncremarkParser } from '@incremark/core'
import { MicromarkAstBuilder } from '@incremark/core/engines/micromark'

const parser = createIncremarkParser({
  astBuilder: MicromarkAstBuilder,
  gfm: true,
  math: true
})
```

> **Note**: The `IncremarkContent` component currently uses the Marked engine by default. To use Micromark with the component, you would need to use `useIncremark` directly with a custom parser.

### When Should You Use Micromark?

* Your content includes complex nested structures
* You need to handle edge cases that Marked can't parse correctly
* Your application has strict CommonMark compliance requirements
* You need Micromark plugins beyond our built-in extensions

## Complete Benchmark Data

We benchmarked 38 real Markdown files. Here are the complete results:

### Test Environment

* **Test files**: 38 files, 6,484 lines total, 128.55 KB
* **Test method**: Simulated streaming input, character-by-character append
* **Compared solutions**: Streamdown, markstream-vue, ant-design-x

### Full Test Results

| Filename | Lines | Size(KB) | Incremark | Streamdown | markstream | ant-design-x | vs Streamdown | vs markstream | vs ant-design-x |
|----------|-------|----------|-----------|------------|------------|--------------|---------------|---------------|-----------------|
| test-footnotes-simple.md | 15 | 0.09 | 0.3 ms | 0.0 ms | 1.4 ms | 0.2 ms | 0.1x | 4.7x | 0.6x |
| simple-paragraphs.md | 16 | 0.41 | 0.9 ms | 0.9 ms | 5.9 ms | 1.0 ms | 1.1x | 6.7x | 1.2x |
| test-footnotes-multiline.md | 21 | 0.18 | 0.6 ms | 0.0 ms | 2.2 ms | 0.4 ms | 0.1x | 3.5x | 0.6x |
| test-footnotes-edge-cases.md | 27 | 0.25 | 0.8 ms | 0.0 ms | 4.2 ms | 1.2 ms | 0.0x | 5.3x | 1.5x |
| test-footnotes-complex.md | 28 | 0.24 | 2.1 ms | 0.0 ms | 4.8 ms | 1.0 ms | 0.0x | 2.3x | 0.5x |
| introduction.md | 34 | 1.57 | 5.6 ms | 12.6 ms | 75.6 ms | 12.8 ms | 2.2x | 13.4x | 2.3x |
| devtools.md | 51 | 0.92 | 1.2 ms | 0.9 ms | 6.1 ms | 1.1 ms | 0.8x | 5.0x | 0.9x |
| footnotes.md | 52 | 0.94 | 1.7 ms | 0.2 ms | 10.6 ms | 1.9 ms | 0.1x | 6.3x | 1.2x |
| html-elements.md | 55 | 1.02 | 1.6 ms | 2.2 ms | 12.6 ms | 2.8 ms | 1.4x | 7.8x | 1.7x |
| themes.md | 58 | 0.96 | 1.9 ms | 1.3 ms | 8.6 ms | 1.8 ms | 0.7x | 4.4x | 0.9x |
| test-footnotes-comprehensive.md | 63 | 0.66 | 5.6 ms | 0.1 ms | 25.8 ms | 7.7 ms | 0.0x | 4.6x | 1.4x |
| auto-scroll.md | 72 | 1.68 | 3.9 ms | 3.5 ms | 39.9 ms | 4.9 ms | 0.9x | 10.1x | 1.2x |
| custom-codeblocks.md | 72 | 1.44 | 3.4 ms | 2.0 ms | 14.9 ms | 2.5 ms | 0.6x | 4.4x | 0.7x |
| custom-components.md | 73 | 1.40 | 4.0 ms | 2.0 ms | 32.7 ms | 2.9 ms | 0.5x | 8.1x | 0.7x |
| custom-containers.md | 88 | 1.67 | 4.2 ms | 2.4 ms | 18.1 ms | 3.1 ms | 0.6x | 4.3x | 0.7x |
| typewriter.md | 88 | 1.89 | 5.6 ms | 4.1 ms | 35.0 ms | 4.9 ms | 0.7x | 6.2x | 0.9x |
| concepts.md | 91 | 4.29 | 12.0 ms | 50.5 ms | 381.9 ms | 53.6 ms | 4.2x | 31.9x | 4.5x |
| INLINE\_CODE\_UPDATE.md | 94 | 1.66 | 4.7 ms | 17.2 ms | 60.9 ms | 15.6 ms | 3.7x | 12.9x | 3.3x |
| comparison.md | 109 | 5.39 | 20.5 ms | 74.0 ms | 552.2 ms | 85.2 ms | 3.6x | 26.9x | 4.1x |
| basic-usage.md | 130 | 3.04 | 8.5 ms | 12.3 ms | 74.1 ms | 14.1 ms | 1.4x | 8.7x | 1.7x |
| CODE\_BACKGROUND\_SEPARATION.md | 131 | 2.83 | 8.7 ms | 28.8 ms | 153.6 ms | 31.3 ms | 3.3x | 17.6x | 3.6x |
| P2\_SUMMARY.md | 138 | 2.61 | 8.3 ms | 38.4 ms | 157.2 ms | 41.9 ms | 4.6x | 18.9x | 5.0x |
| quick-start.md | 146 | 3.04 | 7.3 ms | 7.3 ms | 64.2 ms | 9.6 ms | 1.0x | 8.8x | 1.3x |
| complex-html-examples.md | 147 | 3.99 | 9.0 ms | 58.8 ms | 279.3 ms | 57.2 ms | 6.6x | 31.1x | 6.4x |
| CODE\_COLOR\_SEPARATION.md | 162 | 3.51 | 10.0 ms | 32.8 ms | 191.1 ms | 36.9 ms | 3.3x | 19.1x | 3.7x |
| P0\_OPTIMIZATION\_REPORT.md | 168 | 3.53 | 10.1 ms | 56.2 ms | 228.0 ms | 58.1 ms | 5.6x | 22.6x | 5.8x |
| COLOR\_SYSTEM\_REFACTOR.md | 169 | 3.78 | 18.5 ms | 64.0 ms | 355.5 ms | 69.1 ms | 3.5x | 19.2x | 3.7x |
| FOOTNOTE\_TEST\_GUIDE.md | 219 | 2.87 | 12.3 ms | 0.2 ms | 167.6 ms | 45.0 ms | 0.0x | 13.7x | 3.7x |
| P2\_COLORS\_PACKAGE\_REPORT.md | 226 | 4.10 | 11.4 ms | 77.9 ms | 311.6 ms | 80.5 ms | 6.8x | 27.2x | 7.0x |
| FOOTNOTE\_FIX\_SUMMARY.md | 236 | 3.93 | 22.7 ms | 0.5 ms | 535.0 ms | 120.8 ms | 0.0x | 23.6x | 5.3x |
| BASE\_COLORS\_SYSTEM.md | 259 | 4.47 | 35.8 ms | 43.0 ms | 191.8 ms | 43.4 ms | 1.2x | 5.4x | 1.2x |
| OPTIMIZATION\_COMPARISON.md | 270 | 5.42 | 17.8 ms | 52.3 ms | 366.1 ms | 61.9 ms | 2.9x | 20.6x | 3.5x |
| P1\_OPTIMIZATION\_REPORT.md | 327 | 5.63 | 20.7 ms | 106.8 ms | 433.8 ms | 114.8 ms | 5.2x | 21.0x | 5.5x |
| OPTIMIZATION\_PLAN.md | 371 | 6.89 | 33.1 ms | 67.6 ms | 372.1 ms | 76.7 ms | 2.0x | 11.2x | 2.3x |
| OPTIMIZATION\_SUMMARY.md | 391 | 6.24 | 19.1 ms | 208.4 ms | 980.6 ms | 217.8 ms | 10.9x | 51.3x | 11.4x |
| P1.5\_COLOR\_SYSTEM\_REPORT.md | 482 | 9.12 | 22.0 ms | 145.5 ms | 789.8 ms | 168.2 ms | 6.6x | 35.9x | 7.7x |
| BLOCK\_TRANSFORMER\_ANALYSIS.md | 489 | 9.24 | 75.7 ms | 574.3 ms | 1984.1 ms | 619.9 ms | 7.6x | 26.2x | 8.2x |
| test-md-01.md | 916 | 17.67 | 87.7 ms | 1441.1 ms | 5754.7 ms | 1656.9 ms | 16.4x | 65.6x | 18.9x |
| **【Total】** | **6484** | **128.55** | **519.4 ms** | **3190.3 ms** | **14683.9 ms** | **3728.6 ms** | **6.1x** | **28.3x** | **7.2x** |

### How to Interpret This Data

#### We're Honest: Incremark is Slower in Some Scenarios

You may notice that for `test-footnotes-*.md` and `FOOTNOTE_*.md` files, Incremark is much slower than Streamdown (0.0x - 0.1x).

**The reason is simple: Streamdown doesn't support footnote syntax.**

When Streamdown encounters `[^1]` footnote references, it simply skips them. Meanwhile, Incremark:

1. Recognizes footnote references
2. Parses footnote definition blocks (which may contain multi-line content, code blocks, lists, etc.)
3. Establishes reference relationships
4. Generates correct AST structure

This isn't a performance issue — it's a **feature difference**. We believe complete footnote support is crucial for AI scenarios, so we chose to implement it.

#### Where's the Real Performance Advantage?

Excluding footnote-related files, look at standard Markdown content performance:

| File | Lines | Incremark | Streamdown | Advantage |
|------|-------|-----------|------------|-----------|
| concepts.md | 91 | 12.0 ms | 50.5 ms | **4.2x** |
| comparison.md | 109 | 20.5 ms | 74.0 ms | **3.6x** |
| complex-html-examples.md | 147 | 9.0 ms | 58.8 ms | **6.6x** |
| P0\_OPTIMIZATION\_REPORT.md | 168 | 10.1 ms | 56.2 ms | **5.6x** |
| OPTIMIZATION\_SUMMARY.md | 391 | 19.1 ms | 208.4 ms | **10.9x** |
| test-md-01.md | 916 | 87.7 ms | 1441.1 ms | **16.4x** |

**Conclusion**: For standard Markdown content, the larger the document, the more pronounced Incremark's advantage.

#### Why Such a Gap?

This is the direct result of **O(n) vs O(n²)** algorithmic complexity.

Traditional parsers (Streamdown, ant-design-x, markstream-vue) **re-parse the entire document** on every new chunk:

```
Chunk 1: Parse 100 chars
Chunk 2: Parse 200 chars (100 old + 100 new)
Chunk 3: Parse 300 chars (200 old + 100 new)
...
Chunk 100: Parse 10,000 chars
```

Total work: `100 + 200 + 300 + ... + 10000 = 5,050,000` character operations

**Incremark's incremental parsing** only processes new content:

```
Chunk 1: Parse 100 chars → cache stable blocks
Chunk 2: Parse only ~100 new chars
Chunk 3: Parse only ~100 new chars
...
Chunk 100: Parse only ~100 new chars
```

Total work: `100 × 100 = 10,000` character operations

That's a **500x difference**. This is why an 18KB document can be 16x+ faster.

## Feature Parity

We strive to keep both engines functionally consistent:

| Feature | Marked Engine | Micromark Engine |
|---------|---------------|------------------|
| GFM (Tables, Strikethrough, Autolinks) | ✅ | ✅ |
| Math Blocks (`$...$` and `$$...$$`) | ✅ | ✅ |
| Custom Containers (`:::tip`, etc.) | ✅ | ✅ |
| HTML Element Parsing | ✅ | ✅ |
| Footnotes | ✅ | ✅ |
| Typewriter Animation | ✅ | ✅ |
| Incremental Updates | ✅ | ✅ |

## Switching Engines

Engine selection is done at **initialization time**, not runtime. This is by design for tree-shaking optimization.

### Why Not Runtime Switching?

To ensure optimal bundle size:

* Default import only includes the `marked` engine
* `micromark` engine is imported separately when needed
* This allows bundlers to tree-shake unused engines

### How to Switch Engines

```vue
<script setup>
import { ref } from 'vue'
import { IncremarkContent } from '@incremark/vue'

const content = ref('')
const isFinished = ref(false)

// Engine is selected at initialization
// For marked (default): no extra import needed
// For micromark: import MicromarkAstBuilder
</script>

<template>
  <!-- Uses marked engine by default -->
  <IncremarkContent 
    :content="content" 
    :is-finished="isFinished"
    :incremark-options="{ gfm: true, math: true }"
  />
</template>
```

### Using Micromark Engine

To use micromark, import `MicromarkAstBuilder` from the separate engine entry:

```ts
import { createIncremarkParser } from '@incremark/core'
import { MicromarkAstBuilder } from '@incremark/core/engines/micromark'

// Create parser with micromark engine
const parser = createIncremarkParser({
  astBuilder: MicromarkAstBuilder,
  gfm: true,
  math: true
})
```

> ⚠️ **Tree-shaking Note**: Importing from `@incremark/core/engines/micromark` only adds micromark to your bundle. The default import keeps only marked.

## Extending Engines

Both engines support custom extensions. See the [Extensions Guide](/advanced/extensions) for details.

```ts
// Custom marked extension example
import { createCustomExtension } from '@incremark/core'

const myExtension = createCustomExtension({
  name: 'myPlugin',
  // ... extension config
})
```

## Summary and Recommendations

| Aspect | Marked | Micromark |
|--------|--------|-----------|
| Parsing Speed | ⚡⚡⚡⚡⚡ | ⚡⚡⚡ |
| Bundle Size | 📦 Smaller | 📦 Larger |
| CommonMark Compliance | ✅ Good | ✅ Perfect |
| Built-in Extensions | ✅ Footnotes, Math, Containers | ✅ Via plugins |
| Plugin Ecosystem | 🔧 Growing | 🔧 Mature |
| Recommended For | Streaming AI, Real-time rendering | Static documents, Strict compliance |

**Our Recommendations**:

1. **Most scenarios**: Use the default Marked engine — it's already great
2. **Parsing issues**: If Marked doesn't handle certain edge cases well, try switching to Micromark
3. **Extreme performance needs**: Marked engine is your best choice
4. **Strict compliance needs**: Micromark engine is more suitable

We'll continue optimizing both engines to ensure they provide the best experience for you.

---

---
url: /advanced/extensions.md
---
# Extensions

Incremark's dual-engine architecture provides flexible extension mechanisms for both `micromark` and `marked` engines.

## Engine Selection

Choose the appropriate engine based on your extension needs:

| Engine | Extension Type | Best For |
|--------|---------------|----------|
| `micromark` | micromark + mdast extensions | Rich ecosystem, CommonMark compliance |
| `marked` | Custom token transformers | Maximum performance, simple extensions |

## Micromark Extensions

When using the `micromark` engine, you can leverage the rich ecosystem of existing extensions.

### Syntax Extensions

Use `micromark` extensions to support new syntax:

```vue
<script setup>
import { ref } from 'vue'
import { IncremarkContent } from '@incremark/vue'
import { gfmTable } from 'micromark-extension-gfm-table'

const content = ref('')
const isFinished = ref(false)

// Note: extensions option is for micromark engine only
// Use with MicromarkAstBuilder
import { MicromarkAstBuilder } from '@incremark/core/engines/micromark'

const parser = createIncremarkParser({
  astBuilder: MicromarkAstBuilder,
  extensions: [gfmTable()]
})
</script>

<template>
  <IncremarkContent 
    :content="content" 
    :is-finished="isFinished"
    :incremark-options="options" 
  />
</template>
```

### AST Extensions

Use `mdast-util-from-markdown` extensions to transform syntax to AST nodes:

```ts
import { gfmTableFromMarkdown } from 'mdast-util-gfm-table'

import { MicromarkAstBuilder } from '@incremark/core/engines/micromark'

const parser = createIncremarkParser({
  astBuilder: MicromarkAstBuilder,
  extensions: [gfmTable()],
  mdastExtensions: [gfmTableFromMarkdown()]
})
```

### Common Extension Packages

| Package | Description |
|---------|-------------|
| `micromark-extension-gfm` | Full GFM support |
| `micromark-extension-math` | Math formulas |
| `micromark-extension-directive` | Custom containers |
| `micromark-extension-frontmatter` | YAML frontmatter |

## Marked Extensions

The `marked` engine uses a custom extension system. Incremark has already extended `marked` with support for:

* **Footnotes**: `[^1]` references and `[^1]: content` definitions
* **Math**: `$inline$` and `$$block$$` formulas
* **Custom Containers**: `:::type` syntax
* **Inline HTML**: Structured HTML element parsing

### Custom Token Transformers

For the `marked` engine, you can provide custom token transformers:

```ts
import type { BlockTokenTransformer, InlineTokenTransformer } from '@incremark/core'

// Custom block transformer
const myBlockTransformer: BlockTokenTransformer = (token, ctx) => {
  if (token.type === 'myCustomBlock') {
    return {
      type: 'paragraph',
      children: [{ type: 'text', value: token.raw }]
    }
  }
  return null
}

// For marked engine (default), use customBlockTransformers
const parser = createIncremarkParser({
  // marked is default, no astBuilder needed
  customBlockTransformers: {
    myCustomBlock: myBlockTransformer
  }
})
```

### Built-in Transformers

You can access and extend the built-in transformers:

```ts
import { 
  getBuiltinBlockTransformers, 
  getBuiltinInlineTransformers 
} from '@incremark/core'

// Get all built-in transformers
const blockTransformers = getBuiltinBlockTransformers()
const inlineTransformers = getBuiltinInlineTransformers()

// Override specific transformer
const customTransformers = {
  ...blockTransformers,
  code: (token, ctx) => {
    // Custom code block handling
    return { type: 'code', value: token.text, lang: token.lang }
  }
}
```

## UI-Level Extensions

Beyond parser extensions, Incremark provides UI-level customization:

### Custom Components

Replace default rendering for any node type:

```vue
<IncremarkContent 
  :content="content" 
  :is-finished="isFinished"
  :components="{ heading: MyCustomHeading }"
/>
```

### Custom Code Blocks

Handle specific code languages with custom components:

```vue
<IncremarkContent 
  :content="content" 
  :is-finished="isFinished"
  :custom-code-blocks="{ echarts: MyEchartsRenderer }"
  :code-block-configs="{ echarts: { takeOver: true } }"
/>
```

### Custom Containers

Render `:::type` containers with custom components:

```vue
<IncremarkContent 
  :content="content" 
  :is-finished="isFinished"
  :custom-containers="{ 
    warning: WarningBox,
    info: InfoBox,
    tip: TipBox 
  }"
/>
```

## Extension Best Practices

1. **Choose the right engine**: Use `micromark` for complex syntax extensions, `marked` for performance-critical scenarios.

2. **Leverage existing packages**: The micromark ecosystem has many well-tested extensions.

3. **UI-level first**: For visual customization, prefer UI-level extensions (custom components) over parser extensions.

4. **Test thoroughly**: Custom extensions can affect parsing behavior across different markdown inputs.

---

---
url: /features/footnotes.md
---
# Footnotes

Incremark supports GFM footnotes out of the box.

## Usage

Enable the `gfm` option in your configuration.

```markdown
Here is a footnote reference[^1].

[^1]: This is the footnote definition.
```

## Configuration

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent } from '@incremark/vue'
</script>

<template>
  <IncremarkContent
    :content="content"
    :incremark-options="{ gfm: true }"
  />
</template>
```

```tsx [React]
import { IncremarkContent } from '@incremark/react'

<IncremarkContent
  content={content}
  incremarkOptions={{ gfm: true }}
/>
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent } from '@incremark/svelte'
</script>

<IncremarkContent {content} incremarkOptions={{ gfm: true }} />
```

:::

## Rendering

Footnotes are automatically collected and rendered at the bottom of the content. You can customize the look using CSS or by overriding the `footnoteDefinition` component.

---

---
url: /features/html-elements.md
---
# HTML Elements

Incremark can parse and render raw HTML fragments embedded in Markdown.

## Usage

Enable the `htmlTree` option.

```markdown
This is <b>bold</b> and this is <span style="color: red">red</span>.

<div>
  <h3>Block HTML</h3>
  <p>Content inside HTML block</p>
</div>
```

## Configuration

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent } from '@incremark/vue'
</script>

<template>
  <IncremarkContent
    :content="content"
    :incremark-options="{ htmlTree: true }"
  />
</template>
```

```tsx [React]
import { IncremarkContent } from '@incremark/react'

<IncremarkContent
  content={content}
  incremarkOptions={{ htmlTree: true }}
/>
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent } from '@incremark/svelte'
</script>

<IncremarkContent {content} incremarkOptions={{ htmlTree: true }} />
```

:::

## Security Warning

⚠️ **XSS Risk**: Enabling `htmlTree` allows rendering of arbitrary HTML. Ensure that the content source is trusted or sanitized before passing it to Incremark.

---

---
url: /zh/features/html-elements.md
---
# HTML 元素

Incremark 可以解析和渲染嵌入在 Markdown 中的原始 HTML 片段。

## 用法

启用 `htmlTree` 选项。

```markdown
这是 <b>粗体</b> ，这是 <span style="color: red">红色文本</span>。

<div>
  <h3>块级 HTML</h3>
  <p>HTML 块内的内容</p>
</div>
```

## 配置

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent } from '@incremark/vue'
</script>

<template>
  <IncremarkContent
    :content="content"
    :incremark-options="{ htmlTree: true }"
  />
</template>
```

```tsx [React]
import { IncremarkContent } from '@incremark/react'

<IncremarkContent
  content={content}
  incremarkOptions={{ htmlTree: true }}
/>
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent } from '@incremark/svelte'
</script>

<IncremarkContent {content} incremarkOptions={{ htmlTree: true }} />
```

:::

## 安全警告

⚠️ **XSS 风险**：启用 `htmlTree` 允许渲染任意 HTML。在将内容传递给 Incremark 之前，请确保内容来源可信或已净化。

---

---
url: /features/i18n.md
---
# Internationalization & Accessibility

Incremark provides built-in internationalization (i18n) and accessibility (a11y) support, ensuring components work correctly across different languages and are screen reader friendly.

## Using ConfigProvider

`ConfigProvider` is used to provide global i18n configuration:

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent, ConfigProvider, zhCN } from '@incremark/vue'
</script>

<template>
  <ConfigProvider :locale="zhCN">
    <IncremarkContent :content="content" />
  </ConfigProvider>
</template>
```

```tsx [React]
import { IncremarkContent, ConfigProvider, zhCN } from '@incremark/react'

<ConfigProvider locale={zhCN}>
  <IncremarkContent content={content} />
</ConfigProvider>
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent, ConfigProvider, zhCN } from '@incremark/svelte'
</script>

<ConfigProvider locale={zhCN}>
  <IncremarkContent {content} />
</ConfigProvider>
```

```tsx [Solid]
import { IncremarkContent, ConfigProvider, zhCN } from '@incremark/solid'

<ConfigProvider locale={zhCN}>
  <IncremarkContent content={content()} />
</ConfigProvider>
```

:::

## Built-in Locales

Incremark includes the following built-in locales:

| Locale | Language |
|--------|----------|
| `en` | English (default) |
| `zhCN` | Simplified Chinese |

```ts
import { en, zhCN } from '@incremark/vue'
// or
import { en, zhCN } from '@incremark/react'
// or
import { en, zhCN } from '@incremark/svelte'
// or
import { en, zhCN } from '@incremark/solid'
```

## Custom Locales

You can create custom locales to support other languages:

```ts
import type { IncremarkLocale } from '@incremark/vue'

const jaJP: IncremarkLocale = {
  code: {
    copy: 'コードをコピー',
    copied: 'コピーしました'
  },
  mermaid: {
    copy: 'コードをコピー',
    copied: 'コピーしました',
    viewSource: 'ソースコードを表示',
    preview: 'プレビュー'
  }
}
```

## Accessibility Support

Incremark's UI components follow WAI-ARIA standards and provide comprehensive accessibility support:

### Code Blocks

* Copy buttons use `aria-label` for clear action descriptions
* Button state changes (e.g., after copying) update the `aria-label`
* Language labels are clearly readable

```html
<!-- Before copying -->
<button aria-label="Copy code">...</button>

<!-- After copying -->
<button aria-label="Code copied">...</button>
```

### Mermaid Diagrams

* Toggle buttons (source code/preview) use `aria-label`
* Chart containers provide appropriate semantic labels

## Combined Usage

`ConfigProvider` can be combined with `ThemeProvider`:

::: code-group

```vue [Vue]
<script setup>
import { 
  IncremarkContent, 
  ConfigProvider, 
  ThemeProvider, 
  zhCN 
} from '@incremark/vue'
</script>

<template>
  <ConfigProvider :locale="zhCN">
    <ThemeProvider theme="dark">
      <IncremarkContent :content="content" />
    </ThemeProvider>
  </ConfigProvider>
</template>
```

```tsx [React]
import { 
  IncremarkContent, 
  ConfigProvider, 
  ThemeProvider, 
  zhCN 
} from '@incremark/react'

<ConfigProvider locale={zhCN}>
  <ThemeProvider theme="dark">
    <IncremarkContent content={content} />
  </ThemeProvider>
</ConfigProvider>
```

```svelte [Svelte]
<script lang="ts">
  import {
    IncremarkContent,
    ConfigProvider,
    ThemeProvider,
    zhCN
  } from '@incremark/svelte'
</script>

<ConfigProvider locale={zhCN}>
  <ThemeProvider theme="dark">
    <IncremarkContent {content} />
  </ThemeProvider>
</ConfigProvider>
```

```tsx [Solid]
import {
  IncremarkContent,
  ConfigProvider,
  ThemeProvider,
  zhCN
} from '@incremark/solid'

<ConfigProvider locale={zhCN}>
  <ThemeProvider theme="dark">
    <IncremarkContent content={content()} />
  </ThemeProvider>
</ConfigProvider>
```

:::

## Dynamic Locale Switching

Locales can be switched dynamically at runtime:

::: code-group

```vue [Vue]
<script setup>
import { ref, computed } from 'vue'
import { ConfigProvider, en, zhCN } from '@incremark/vue'

const lang = ref('en')
const locale = computed(() => lang.value === 'zh' ? zhCN : en)

function toggleLocale() {
  lang.value = lang.value === 'en' ? 'zh' : 'en'
}
</script>

<template>
  <button @click="toggleLocale">Toggle Language</button>
  <ConfigProvider :locale="locale">
    <IncremarkContent :content="content" />
  </ConfigProvider>
</template>
```

```tsx [React]
import { useState, useMemo } from 'react'
import { ConfigProvider, en, zhCN } from '@incremark/react'

function App() {
  const [lang, setLang] = useState('en')
  const locale = useMemo(() => lang === 'zh' ? zhCN : en, [lang])
  
  return (
    <>
      <button onClick={() => setLang(l => l === 'en' ? 'zh' : 'en')}>
        Toggle Language
      </button>
      <ConfigProvider locale={locale}>
        <IncremarkContent content={content} />
      </ConfigProvider>
    </>
  )
}
```

```svelte [Svelte]
<script lang="ts">
  import { ConfigProvider, en, zhCN } from '@incremark/svelte'

  let lang = $state('en')
  const locale = $derived(lang === 'zh' ? zhCN : en)

  function toggleLocale() {
    lang = lang === 'en' ? 'zh' : 'en'
  }
</script>

<button onclick={toggleLocale}>Toggle Language</button>
<ConfigProvider locale={locale}>
  <IncremarkContent {content} />
</ConfigProvider>
```

```tsx [Solid]
import { createSignal, Index } from 'solid-js'
import { ConfigProvider, en, zhCN } from '@incremark/solid'

function App() {
  const [lang, setLang] = createSignal('en')
  const locale = () => lang() === 'zh' ? zhCN : en
  const [key, setKey] = createSignal(0)

  function toggleLocale() {
    setLang(l => l === 'en' ? 'zh' : 'en')
    setKey(k => k + 1)
  }

  return (
    <>
      <button onClick={toggleLocale}>Toggle Language</button>
      <Index each={[key()]}>
        {() => (
          <ConfigProvider locale={locale()}>
            <IncremarkContent content={content()} />
          </ConfigProvider>
        )}
      </Index>
    </>
  )
}
```

:::

## Locale Type Definition

```ts
interface IncremarkLocale {
  /** Code block translations */
  code: {
    /** Copy code button text */
    copy: string
    /** Text shown after copying */
    copied: string
  }
  /** Mermaid diagram translations */
  mermaid: {
    /** Copy code button text */
    copy: string
    /** Text shown after copying */
    copied: string
    /** View source code button text */
    viewSource: string
    /** Preview diagram button text */
    preview: string
  }
}
```

---

---
url: /guide/introduction.md
---
# Introduction

**Incremark** is a markdown renderer designed for the AI era. It prioritizes **streaming performance**, **incremental updates**, and **smooth visual effects**.

## Why Incremark?

With the rise of LLMs (Large Language Models), applications are increasingly displaying streaming text. Traditional markdown parsers were built for static documents, not for text that updates 50 times a second.

This mismatch leads to:

* High CPU usage on long responses.
* Janky scrolling and rendering.
* Difficulty implementing "Typewriter" effects without breaking markdown syntax.

**Incremark** rethinks markdown rendering as a stream processing problem.

## Key Features

* ⚡️ **Extreme Performance**: Average ~6x faster than Streamdown, ~7x faster than ant-design-x, ~28x faster than markstream-vue.
* 🔄 **Dual-Engine Architecture**: Marked with enhanced extensions for speed, or Micromark for strict CommonMark compliance.
* 🚀 **O(n) Incremental Parsing**: Only parse what's new — 18KB document is 19x faster than traditional parsers.
* ⌨️ **Built-in Typewriter**: Smooth character-by-character reveals that respect markdown structure.
* 🧩 **Framework Agnostic**: Core logic is shared; connectors for Vue, React, and Svelte.
* 🎨 **Themable**: Tailored for modern, dark-mode-first interfaces.
* 🛠 **DevTools**: Inspect the parsing process in real-time.

## Ready to Start?

Check out the [Quick Start](/guide/quick-start) to integrate it into your app in minutes.

## AI Friendliness

Incremark is designed for AI, and our documentation is too. We provide structured versions of our docs for better ingestion by LLMs:

* [llms.txt](/llms.txt): A concise index of our documentation.
* [llms-full.txt](/llms-full.txt): The entire documentation in a single file, perfect for providing context to Claude, Cursor, or ChatGPT.

---

---
url: /examples/openai.md
---
# OpenAI Integration

Using the `openai` Node.js library.

## Example

```ts
import OpenAI from 'openai'
import { IncremarkContent } from '@incremark/react'

const openai = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  dangerouslyAllowBrowser: true // For client-side demo only
})

function App() {
  const [stream, setStream] = useState(null)

  async function startChat() {
    async function* getStream() {
      const completion = await openai.chat.completions.create({
        model: "gpt-4",
        messages: [{ role: "user", content: "Explain quantum computing" }],
        stream: true,
      })

      for await (const chunk of completion) {
        yield chunk.choices[0]?.delta?.content || ''
      }
    }
    
    setStream(() => getStream)
  }

  return (
    <>
      <button onClick={startChat}>Send</button>
      <IncremarkContent stream={stream} />
    </>
  )
}
```

---

---
url: /zh/examples/openai.md
---
# OpenAI 集成

使用 `openai` Node.js 库。

## 示例

```ts
import OpenAI from 'openai'
import { IncremarkContent } from '@incremark/react'

const openai = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  dangerouslyAllowBrowser: true // 仅用于客户端演示
})

function App() {
  const [stream, setStream] = useState(null)

  async function startChat() {
    async function* getStream() {
      const completion = await openai.chat.completions.create({
        model: "gpt-4",
        messages: [{ role: "user", content: "Explain quantum computing" }],
        stream: true,
      })

      for await (const chunk of completion) {
        yield chunk.choices[0]?.delta?.content || ''
      }
    }
    
    setStream(() => getStream)
  }

  return (
    <>
      <button onClick={startChat}>Send</button>
      <IncremarkContent stream={stream} />
    </>
  )
}
```

---

---
url: /guide/quick-start.md
---
# Quick Start

Get up and running with specific framework integration in 5 minutes.

## Installation

::: code-group

```bash [pnpm]
pnpm add @incremark/vue @incremark/theme
# OR
pnpm add @incremark/react @incremark/theme
# OR
pnpm add @incremark/svelte @incremark/theme
# OR
pnpm add @incremark/solid @incremark/theme
```

```bash [npm]
npm install @incremark/vue @incremark/theme
# OR
npm install @incremark/react @incremark/theme
# OR
npm install @incremark/svelte @incremark/theme
# OR
npm install @incremark/solid @incremark/theme
```

```bash [yarn]
yarn add @incremark/vue @incremark/theme
# OR
yarn add @incremark/react @incremark/theme
# OR
yarn add @incremark/svelte @incremark/theme
# OR
yarn add @incremark/solid @incremark/theme
```

:::

## Basic Usage

::: code-group

```vue [Vue]
<script setup>
import { ref } from 'vue'
import { IncremarkContent } from '@incremark/vue'
import '@incremark/theme/styles.css' // [!code hl]

const content = ref('')
const isFinished = ref(false)

async function simulateStream() {
  content.value = ''
  isFinished.value = false

  const text = '# Hello\n\nThis is **Incremark**!'
  for (const chunk of text.match(/[\s\S]{1,5}/g) || []) {
    content.value += chunk
    await new Promise(r => setTimeout(r, 50))
  }
  isFinished.value = true
}
</script>

<template>
  <button @click="simulateStream">Start</button>
  <IncremarkContent :content="content" :is-finished="isFinished" />
</template>
```

```tsx [React]
import { useState } from 'react'
import { IncremarkContent } from '@incremark/react'
import '@incremark/theme/styles.css' // [!code hl]

function App() {
  const [content, setContent] = useState('')
  const [isFinished, setIsFinished] = useState(false)

  async function simulateStream() {
    setContent('')
    setIsFinished(false)

    const text = '# Hello\n\nThis is **Incremark**!'
    const chunks = text.match(/[\s\S]{1,5}/g) || []
    for (const chunk of chunks) {
      setContent(prev => prev + chunk)
      await new Promise(r => setTimeout(r, 50))
    }
    setIsFinished(true)
  }

  return (
    <>
      <button onClick={simulateStream}>Start</button>
      <IncremarkContent content={content} isFinished={isFinished} />
    </>
  )
}
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent } from '@incremark/svelte'
  import '@incremark/theme/styles.css' // [!code hl]

  let content = $state('')
  let isFinished = $state(false)

  async function simulateStream() {
    content = ''
    isFinished = false

    const text = '# Hello\n\nThis is **Incremark**!'
    for (const chunk of text.match(/[\s\S]{1,5}/g) || []) {
      content += chunk
      await new Promise(r => setTimeout(r, 50))
    }
    isFinished = true
  }
</script>

<button onclick={simulateStream}>Start</button>
<IncremarkContent {content} {isFinished} />
```

```tsx [Solid]
import { createSignal } from 'solid-js'
import { IncremarkContent } from '@incremark/solid'
import '@incremark/theme/styles.css' // [!code hl]

function App() {
  const [content, setContent] = createSignal('')
  const [isFinished, setIsFinished] = createSignal(false)

  async function simulateStream() {
    setContent('')
    setIsFinished(false)

    const text = '# Hello\n\nThis is **Incremark**!'
    const chunks = text.match(/[\s\S]{1,5}/g) || []
    for (const chunk of chunks) {
      setContent(prev => prev + chunk)
      await new Promise(r => setTimeout(r, 50))
    }
    setIsFinished(true)
  }

  return (
    <>
      <button onClick={simulateStream}>Start</button>
      <IncremarkContent content={content()} isFinished={isFinished()} />
    </>
  )
}
```

:::

## Using Stream Mode

```vue
<script setup>
import { IncremarkContent } from '@incremark/vue'

async function* fetchAIStream() {
  const res = await fetch('/api/chat', { method: 'POST' })
  const reader = res.body!.getReader()
  const decoder = new TextDecoder()

  while (true) {
    const { done, value } = await reader.read()
    if (done) break
    yield decoder.decode(value)
  }
}
</script>

<template>
  <IncremarkContent :stream="fetchAIStream" />
</template>
```

## Math Formulas (Optional)

If you need to support math formulas (KaTeX), make sure to also import the KaTeX CSS:

```ts
import 'katex/dist/katex.min.css'
```

---

---
url: /features/themes.md
---
# Themes

## Using ThemeProvider

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent, ThemeProvider } from '@incremark/vue'
</script>

<template>
  <ThemeProvider theme="dark">
    <IncremarkContent :content="content" />
  </ThemeProvider>
</template>
```

```tsx [React]
import { IncremarkContent, ThemeProvider } from '@incremark/react'

<ThemeProvider theme="dark">
  <IncremarkContent content={content} />
</ThemeProvider>
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent, ThemeProvider } from '@incremark/svelte'
</script>

<ThemeProvider theme="dark">
  <IncremarkContent {content} />
</ThemeProvider>
```

```tsx [Solid]
import { IncremarkContent, ThemeProvider } from '@incremark/solid'

<ThemeProvider theme="dark">
  <IncremarkContent content={content()} />
</ThemeProvider>
```

:::

## Built-in Themes

* `default` - Light theme
* `dark` - Dark theme

## Custom Theme

```ts
import { type DesignTokens } from '@incremark/vue'

const customTheme: Partial<DesignTokens> = {
  color: {
    brand: {
      primary: '#8b5cf6',
      primaryHover: '#7c3aed'
    }
  }
}

<ThemeProvider :theme="customTheme">
```

---

---
url: /features/typewriter.md
---
# Typewriter Effect

## Enable Typewriter Effect

::: code-group

```vue [Vue]
<script setup>
import { ref, computed } from 'vue'
import { IncremarkContent, type UseIncremarkOptions } from '@incremark/vue'

const content = ref('')
const isFinished = ref(false)

const options = computed<UseIncremarkOptions>(() => ({
  typewriter: {
    enabled: true,
    charsPerTick: [1, 3],
    tickInterval: 30,
    effect: 'typing'
  }
}))
</script>

<template>
  <IncremarkContent
    :content="content"
    :is-finished="isFinished"
    :incremark-options="options"
  />
</template>
```

```tsx [React]
import { IncremarkContent, UseIncremarkOptions } from '@incremark/react'

const options: UseIncremarkOptions = {
  typewriter: {
    enabled: true,
    charsPerTick: [1, 3],
    tickInterval: 30,
    effect: 'typing'
  }
}

<IncremarkContent
  content={content}
  isFinished={isFinished}
  incremarkOptions={options}
/>
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent, type UseIncremarkOptions } from '@incremark/svelte'

  let content = $state('')
  let isFinished = $state(false)

  const options: UseIncremarkOptions = {
    typewriter: {
      enabled: true,
      charsPerTick: [1, 3],
      tickInterval: 30,
      effect: 'typing'
    }
  }
</script>

<IncremarkContent {content} {isFinished} incremarkOptions={options} />
```

```tsx [Solid]
import { createSignal } from 'solid-js'
import { IncremarkContent, type UseIncremarkOptions } from '@incremark/solid'

function App() {
  const [content, setContent] = createSignal('')
  const [isFinished, setIsFinished] = createSignal(false)

  const options: UseIncremarkOptions = {
    typewriter: {
      enabled: true,
      charsPerTick: [1, 3],
      tickInterval: 30,
      effect: 'typing'
    }
  }

  return (
    <IncremarkContent
      content={content()}
      isFinished={isFinished()}
      incremarkOptions={options}
    />
  )
}
```

:::

## Configuration

| Option | Type | Default | Description |
|---|---|---|---|
| `enabled` | `boolean` | `false` | Enable typewriter |
| `charsPerTick` | `number \| [min, max]` | `2` | Characters per tick |
| `tickInterval` | `number` | `50` | Update interval (ms) |
| `effect` | `'none' \| 'fade-in' \| 'typing'` | `'none'` | Animation effect |
| `cursor` | `string` | `'\|'` | Cursor character |

## Animation Effects

* **none**: No animation, display immediately.
* **fade-in**: Fade in effect, new characters opacity transition.
* **typing**: Typewriter effect with cursor.

---

---
url: /zh.md
---

## 为什么选择 Incremark？

传统 Markdown 解析器每次收到新内容都会**重新解析整个文档**，导致 O(n²) 的复杂度。Incremark 的增量解析实现了 O(n) —— 文档越大，优势越明显：

| 文件 | 行数 | Incremark | Streamdown | markstream | ant-design-x |
|------|------|-----------|------------|------------|--------------|
| concepts.md | 91 | 12.0 ms | 50.5 ms (**4.2x**) | 381.9 ms (**31.9x**) | 53.6 ms (**4.5x**) |
| comparison.md | 109 | 20.5 ms | 74.0 ms (**3.6x**) | 552.2 ms (**26.9x**) | 85.2 ms (**4.1x**) |
| complex-html.md | 147 | 9.0 ms | 58.8 ms (**6.6x**) | 279.3 ms (**31.1x**) | 57.2 ms (**6.4x**) |
| OPTIMIZATION\_SUMMARY.md | 391 | 19.1 ms | 208.4 ms (**10.9x**) | 980.6 ms (**51.3x**) | 217.8 ms (**11.4x**) |
| test-md-01.md | 916 | 87.7 ms | 1441.1 ms (**16.4x**) | 5754.7 ms (**65.6x**) | 1656.9 ms (**18.9x**) |
| **总计 (38个文件)** | **6484** | **519.4 ms** | **3190.3 ms** (**6.1x**) | **14683.9 ms** (**28.3x**) | **3728.6 ms** (**7.2x**) |

> 📊 基准测试: 38 个真实 Markdown 文件，共 128.55 KB。[查看完整结果 →](/zh/advanced/engines#完整测试结果)

## 快速体验

::: code-group

```bash [Vue]
pnpm add @incremark/vue @incremark/theme
```

```bash [React]
pnpm add @incremark/react @incremark/theme
```

```bash [Svelte]
pnpm add @incremark/svelte @incremark/theme
```

```bash [Solid]
pnpm add @incremark/solid @incremark/theme
```

:::

::: code-group

```vue [Vue]
<script setup>
import { ref } from 'vue'
import { IncremarkContent } from '@incremark/vue'
import '@incremark/theme/styles.css'

const content = ref('')
const isFinished = ref(false)

// 处理 AI 流式输出
async function handleStream(stream) {
  for await (const chunk of stream) {
    content.value += chunk
  }
  isFinished.value = true
}
</script>

<template>
  <IncremarkContent :content="content" :is-finished="isFinished" />
</template>
```

```tsx [React]
import { useState } from 'react'
import { IncremarkContent } from '@incremark/react'
import '@incremark/theme/styles.css'

function App() {
  const [content, setContent] = useState('')
  const [isFinished, setIsFinished] = useState(false)

  // 处理 AI 流式输出
  async function handleStream(stream) {
    for await (const chunk of stream) {
      setContent(prev => prev + chunk)
    }
    setIsFinished(true)
  }

  return <IncremarkContent content={content} isFinished={isFinished} />
}
```

```svelte [Svelte]
<script>
import { IncremarkContent } from '@incremark/svelte'
import '@incremark/theme/styles.css'

let content = $state('')
let isFinished = $state(false)

// 处理 AI 流式输出
async function handleStream(stream) {
  for await (const chunk of stream) {
    content += chunk
  }
  isFinished = true
}
</script>

<IncremarkContent {content} {isFinished} />
```

```tsx [Solid]
import { createSignal } from 'solid-js'
import { IncremarkContent } from '@incremark/solid'
import '@incremark/theme/styles.css'

function App() {
  const [content, setContent] = createSignal('')
  const [isFinished, setIsFinished] = createSignal(false)

  // 处理 AI 流式输出
  async function handleStream(stream) {
    for await (const chunk of stream) {
      setContent(prev => prev + chunk)
    }
    setIsFinished(true)
  }

  return <IncremarkContent content={content()} isFinished={isFinished()} />
}
```

:::

---

---
url: /examples/vercel-ai.md
---
# Vercel AI SDK Integration

Using the `ai` SDK.

## Example

```tsx
import { useChat } from 'ai/react'
import { IncremarkContent } from '@incremark/react'

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat()

  const lastMessage = messages[messages.length - 1]
  const isAssistant = lastMessage?.role === 'assistant'

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          {m.role === 'user' ? (
            <p>{m.content}</p>
          ) : (
            // Pass content to Incremark
            // Vercel AI SDK updates content reactively
            <IncremarkContent 
              content={m.content} 
              isFinished={false} // You might check if status === 'ready'
            />
          )}
        </div>
      ))}

      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
      </form>
    </div>
  )
}
```

---

---
url: /zh/examples/vercel-ai.md
---
# Vercel AI SDK 集成

使用 `ai` SDK。

## 示例

```tsx
import { useChat } from 'ai/react'
import { IncremarkContent } from '@incremark/react'

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat()

  const lastMessage = messages[messages.length - 1]
  const isAssistant = lastMessage?.role === 'assistant'

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          {m.role === 'user' ? (
            <p>{m.content}</p>
          ) : (
            // 将内容传递给 Incremark
            // Vercel AI SDK 响应式更新内容
            <IncremarkContent 
              content={m.content} 
              isFinished={false} // 你可以检查 status === 'ready'
            />
          )}
        </div>
      ))}

      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
      </form>
    </div>
  )
}
```

---

---
url: /guide/why-incremark.md
---
# Why Incremark?

In the age of Large Language Models, displaying AI-generated content has become one of the most common requirements in web development. You might wonder: there are already so many Markdown rendering libraries out there — why do we need another one?

This article will answer that question honestly.

## The Problem We're Solving

### AI Output is Getting Longer

If you've been following AI trends, you'll notice a clear pattern:

* **2022**: GPT-3.5 responses were typically a few hundred words
* **2023**: GPT-4 responses could reach 2,000-4,000 words
* **2024-2025**: Reasoning models like OpenAI o1 and DeepSeek R1 output "thinking processes" that can exceed 10,000+ words

Single conversation token counts are moving from 4K toward 32K, even 128K.

**The challenge**: For frontend developers, rendering 500 words versus 50,000 words of Markdown are completely different problems.

### Traditional Parsers Can't Keep Up

Here's what happens when you use traditional Markdown parsers with streaming AI output:

```
Chunk 1: Parse 100 characters ✓
Chunk 2: Parse 200 characters (100 old + 100 new)
Chunk 3: Parse 300 characters (200 old + 100 new)
...
Chunk 100: Parse 10,000 characters 😰
```

Every time a new chunk arrives, the entire document gets re-parsed. This is **O(n²) complexity**.

For a 20KB document, this means:

* **ant-design-x**: 1,657 ms total parsing time
* **markstream-vue**: 5,755 ms (almost 6 seconds!)
* **Incremark**: 88 ms ✨

**The difference is not 2x or 3x — it's 19x to 65x.**

## Why Incremark is Different

### 1. True Incremental Parsing

Incremark doesn't just "optimize" the traditional approach — it fundamentally rethinks how streaming Markdown should work.

```
Chunk 1: Parse 100 chars → cache stable blocks
Chunk 2: Parse only ~100 new chars (previous cached)
Chunk 3: Parse only ~100 new chars (previous cached)
...
Chunk 100: Parse only ~100 new chars
```

This is **O(n) complexity**. The larger your document, the greater our advantage.

### 2. Dual-Engine Architecture

We understand that different scenarios have different needs:

| Engine | Speed | Best For |
|--------|-------|----------|
| **Marked** (Default) | ⚡⚡⚡⚡⚡ | Real-time streaming, AI chat |
| **Micromark** | ⚡⚡⚡ | Complex documents, strict CommonMark compliance |

You can switch engines with a single configuration option.

### 3. Enhanced Features Out of the Box

Native Marked doesn't support footnotes, math, or custom containers. We've added these through carefully designed extensions:

* ✅ **Footnotes**: Full GFM footnote support (`[^1]`)
* ✅ **Math Blocks**: Inline (`$...$`) and block (`$$...$$`) formulas
* ✅ **Custom Containers**: `:::tip`, `:::warning`, `:::danger`
* ✅ **HTML Parsing**: Structured HTML tree parsing
* ✅ **Optimistic References**: Graceful handling of incomplete links during streaming

### 4. Framework Agnostic

We provide first-class support for all major frameworks:

```bash
# Vue
pnpm add @incremark/core @incremark/vue

# React
pnpm add @incremark/core @incremark/react

# Svelte
pnpm add @incremark/core @incremark/svelte
```

One core library, consistent APIs, identical features across frameworks.

## Honest Performance Comparison

We believe in transparency. Here are our actual benchmark results across 38 test files:

### Overall Averages

| vs Competitor | Average Advantage |
|---------------|-------------------|
| vs Streamdown | ~**6.1x faster** |
| vs ant-design-x | ~**7.2x faster** |
| vs markstream-vue | ~**28.3x faster** |

### Where We're Not Faster

We won't hide this: in some benchmarks, Incremark appears slower than Streamdown:

| File | Incremark | Streamdown | Why |
|------|-----------|------------|-----|
| footnotes.md | 1.7 ms | 0.2 ms | Streamdown doesn't support footnotes |
| FOOTNOTE\_FIX\_SUMMARY.md | 22.7 ms | 0.5 ms | Same — skips footnote parsing |

**This isn't a performance issue — it's a feature difference.** We chose to fully implement footnotes because they matter for AI content.

### Where We Truly Excel

For standard Markdown content, our advantage is clear:

| File | Lines | Incremark | ant-design-x | Advantage |
|------|-------|-----------|--------------|-----------|
| concepts.md | 91 | 12.0 ms | 53.6 ms | **4.5x** |
| OPTIMIZATION\_SUMMARY.md | 391 | 19.1 ms | 217.8 ms | **11.4x** |
| test-md-01.md | 916 | 87.7 ms | 1656.9 ms | **18.9x** |

**The larger the document, the greater our advantage.**

## Who Should Use Incremark?

### ✅ Perfect For

* **AI Chat Applications**: Claude, ChatGPT, custom LLM interfaces
* **Long-Form AI Content**: Reasoning models, code generation, document analysis
* **Real-Time Editors**: Collaborative Markdown editing
* **Enterprise RAG Systems**: Knowledge bases with large document rendering
* **Multi-Framework Teams**: Consistent behavior across Vue, React, and Svelte

### ⚠️ Consider Alternatives For

* **Static Site Generation**: If you're pre-rendering Markdown at build time, simpler libraries work fine
* **Very Short Content**: For content under 500 characters, the performance difference is negligible

## The Bigger Picture

We're not just building a library — we're preparing for the future of AI interfaces.

### The Trend is Clear

* AI output is getting longer (reasoning models, chain-of-thought)
* Streaming is becoming the default (better UX, lower latency)
* Users expect instant feedback (no loading spinners, no jank)

Traditional O(n²) parsers simply can't scale to this future. Incremark's O(n) architecture is built for it.

### Our Commitment

We're committed to:

* **Performance**: Continuously optimizing both engines
* **Features**: Adding new syntax support as needed
* **Stability**: Thorough testing and careful versioning
* **Documentation**: AI-friendly docs (see our `llms.txt`)

## Getting Started

Ready to try it? It takes less than 5 minutes:

```bash
pnpm add @incremark/core @incremark/vue
```

```vue
<script setup>
import { ref } from 'vue'
import { IncremarkContent } from '@incremark/vue'

const content = ref('')
const isFinished = ref(false)

// Handle AI streaming output
async function handleStream(stream) {
  content.value = ''
  isFinished.value = false
  
  for await (const chunk of stream) {
    content.value += chunk
  }
  
  isFinished.value = true
}
</script>

<template>
  <IncremarkContent 
    :content="content" 
    :is-finished="isFinished"
    :incremark-options="{ gfm: true, math: true }"
  />
</template>
```

That's it. Your AI chat just got 19x faster.

***

## FAQ

### Q: Is Incremark production-ready?

Yes. The core parsing engine has been extensively tested with real-world AI content, including edge cases like incomplete code blocks, nested lists, and complex footnotes.

### Q: Will WebAssembly-based parsers make Incremark obsolete?

This is a valid concern. Rust-based Wasm parsers (like `pulldown-cmark`) could theoretically be faster. However:

1. Wasm-JS interop has overhead (especially for string passing)
2. Incremental parsing is hard to implement in Wasm
3. 88ms for a 20KB document is already imperceptible to humans

As long as we maintain our current performance level, Wasm isn't a threat.

### Q: How does Incremark compare to `react-markdown`?

`react-markdown` is designed for static documents, not streaming. It re-renders the entire component tree on every update, causing severe performance issues with AI streaming. Incremark only updates what changed.

### Q: Can I customize the rendering?

Absolutely. All three framework packages support custom components:

```vue
<IncremarkContent 
  :content="content" 
  :is-finished="isFinished"
  :custom-code-blocks="{ echarts: MyEchartsCodeBlock }"
  :custom-containers="{ warning: MyWarningContainer }"
  :components="{ heading: MyCustomHeading }"
/>
```

***

We built Incremark because we needed it ourselves. We hope it helps you build better AI experiences.

Questions? Issues? [Open a GitHub issue](https://github.com/kingshuaishuai/incremark/issues) or check our [documentation](/).

---

---
url: /zh/guide/why-incremark.md
---
# 为什么选择 Incremark？

在大语言模型时代，展示 AI 生成的内容已经成为 Web 开发中最常见的需求之一。你可能会问：市面上已经有那么多 Markdown 渲染库了，为什么还需要一个新的？

这篇文章会诚实地回答这个问题。

## 我们要解决的问题

### AI 输出正在变得越来越长

如果你关注 AI 领域的趋势，会发现一个明显的规律：

* **2022 年**：GPT-3.5 的回复通常只有几百字
* **2023 年**：GPT-4 的回复可以达到 2,000-4,000 字
* **2024-2025 年**：OpenAI o1、DeepSeek R1 等推理模型会输出"思考过程"，可能超过 10,000+ 字

单次会话的 Token 量级正在从 4K 向 32K，甚至 128K 迈进。

**挑战**：对于前端开发者来说，渲染 500 字和渲染 50,000 字的 Markdown，完全是两个不同的问题。

### 传统解析器跟不上了

当你用传统的 Markdown 解析器处理 AI 流式输出时，会发生这样的事情：

```
Chunk 1: 解析 100 字符 ✓
Chunk 2: 解析 200 字符 (100 旧 + 100 新)
Chunk 3: 解析 300 字符 (200 旧 + 100 新)
...
Chunk 100: 解析 10,000 字符 😰
```

每当新的 chunk 到达，整个文档都要重新解析一遍。这是 **O(n²) 复杂度**。

对于一个 20KB 的文档，这意味着：

* **ant-design-x**：1,657 ms 总解析时间
* **markstream-vue**：5,755 ms（将近 6 秒！）
* **Incremark**：88 ms ✨

**差距不是 2 倍或 3 倍 —— 是 19 倍到 65 倍。**

## 为什么 Incremark 不一样

### 1. 真正的增量解析

Incremark 不只是"优化"传统方案 —— 它从根本上重新思考了流式 Markdown 应该如何工作。

```
Chunk 1: 解析 100 字符 → 缓存稳定块
Chunk 2: 仅解析 ~100 新字符（之前的已缓存）
Chunk 3: 仅解析 ~100 新字符（之前的已缓存）
...
Chunk 100: 仅解析 ~100 新字符
```

这是 **O(n) 复杂度**。文档越大，我们的优势越明显。

### 2. 双引擎架构

我们理解不同场景有不同的需求：

| 引擎 | 速度 | 最佳场景 |
|------|------|----------|
| **Marked**（默认） | ⚡⚡⚡⚡⚡ | 实时流式、AI 对话 |
| **Micromark** | ⚡⚡⚡ | 复杂文档、严格 CommonMark 兼容 |

你可以通过一个配置选项切换引擎。

### 3. 开箱即用的增强功能

原生 Marked 不支持脚注、数学公式或自定义容器。我们通过精心设计的扩展添加了这些功能：

* ✅ **脚注**：完整的 GFM 脚注支持（`[^1]`）
* ✅ **数学公式**：行内（`$...$`）和块级（`$$...$$`）公式
* ✅ **自定义容器**：`:::tip`、`:::warning`、`:::danger`
* ✅ **HTML 解析**：结构化的 HTML 树解析
* ✅ **乐观引用处理**：在流式输入时优雅处理未完成的链接

### 4. 框架无关

我们为所有主流框架提供一等支持：

```bash
# Vue
pnpm add @incremark/core @incremark/vue

# React
pnpm add @incremark/core @incremark/react

# Svelte
pnpm add @incremark/core @incremark/svelte
```

一个核心库，一致的 API，跨框架相同的特性。

## 诚实的性能对比

我们相信透明度。以下是我们在 38 个测试文件上的实际基准测试结果：

### 总体平均值

| 对比方案 | 平均优势 |
|----------|----------|
| vs Streamdown | 约**快 6.1 倍** |
| vs ant-design-x | 约**快 7.2 倍** |
| vs markstream-vue | 约**快 28.3 倍** |

### 我们没有更快的地方

我们不会隐瞒这一点：在某些基准测试中，Incremark 看起来比 Streamdown 慢：

| 文件 | Incremark | Streamdown | 原因 |
|------|-----------|------------|------|
| footnotes.md | 1.7 ms | 0.2 ms | Streamdown 不支持脚注 |
| FOOTNOTE\_FIX\_SUMMARY.md | 22.7 ms | 0.5 ms | 同上 — 跳过脚注解析 |

**这不是性能问题 —— 这是功能差异。** 我们选择完整实现脚注，因为它们对 AI 内容很重要。

### 我们真正的优势场景

对于标准 Markdown 内容，我们的优势很明显：

| 文件 | 行数 | Incremark | ant-design-x | 优势倍数 |
|------|------|-----------|--------------|----------|
| concepts.md | 91 | 12.0 ms | 53.6 ms | **4.5x** |
| OPTIMIZATION\_SUMMARY.md | 391 | 19.1 ms | 217.8 ms | **11.4x** |
| test-md-01.md | 916 | 87.7 ms | 1656.9 ms | **18.9x** |

**文档越大，我们的优势越明显。**

## 谁应该使用 Incremark？

### ✅ 非常适合

* **AI 聊天应用**：Claude、ChatGPT、自定义 LLM 界面
* **长篇 AI 内容**：推理模型、代码生成、文档分析
* **实时编辑器**：协作式 Markdown 编辑
* **企业级 RAG 系统**：需要渲染大型文档的知识库
* **多框架团队**：在 Vue、React 和 Svelte 之间保持一致的行为

### ⚠️ 考虑其他方案

* **静态站点生成**：如果你在构建时预渲染 Markdown，更简单的库就够了
* **非常短的内容**：对于 500 字符以下的内容，性能差异可以忽略

## 更大的图景

我们不只是在构建一个库 —— 我们在为 AI 界面的未来做准备。

### 趋势很明确

* AI 输出正在变长（推理模型、思维链）
* 流式正在成为默认方式（更好的用户体验，更低的延迟）
* 用户期望即时反馈（没有加载动画，没有卡顿）

传统的 O(n²) 解析器根本无法扩展到这个未来。Incremark 的 O(n) 架构正是为此而生。

### 我们的承诺

我们承诺：

* **性能**：持续优化两个引擎
* **功能**：根据需要添加新的语法支持
* **稳定性**：彻底的测试和谨慎的版本控制
* **文档**：AI 友好的文档（查看我们的 `llms.txt`）

## 开始使用

准备好尝试了吗？只需要不到 5 分钟：

```bash
pnpm add @incremark/core @incremark/vue
```

```vue
<script setup>
import { ref } from 'vue'
import { IncremarkContent } from '@incremark/vue'

const content = ref('')
const isFinished = ref(false)

// 处理 AI 流式输出
async function handleStream(stream) {
  content.value = ''
  isFinished.value = false
  
  for await (const chunk of stream) {
    content.value += chunk
  }
  
  isFinished.value = true
}
</script>

<template>
  <IncremarkContent 
    :content="content" 
    :is-finished="isFinished"
    :incremark-options="{ gfm: true, math: true }"
  />
</template>
```

就这样。你的 AI 聊天刚刚快了 19 倍。

***

## 常见问题

### Q: Incremark 可以用于生产环境吗？

可以。核心解析引擎已经用真实的 AI 内容进行了广泛测试，包括未完成的代码块、嵌套列表和复杂脚注等边界情况。

### Q: 基于 WebAssembly 的解析器会让 Incremark 过时吗？

这是一个合理的担忧。基于 Rust 的 Wasm 解析器（如 `pulldown-cmark`）理论上可能更快。但是：

1. Wasm-JS 交互有开销（尤其是字符串传递）
2. 增量解析在 Wasm 中很难实现
3. 20KB 文档 88ms 的解析时间对人类来说已经是瞬间完成

只要我们保持目前的性能水平，Wasm 就不是威胁。

### Q: Incremark 和 `react-markdown` 相比如何？

`react-markdown` 是为静态文档设计的，不是为流式设计的。它在每次更新时都会重新渲染整个组件树，在 AI 流式输出时会造成严重的性能问题。Incremark 只更新发生变化的部分。

### Q: 我可以自定义渲染吗？

当然可以。三个框架包都支持自定义组件：

```vue
<IncremarkContent 
  :content="content" 
  :is-finished="isFinished"
  :custom-code-blocks="{ echarts: MyEchartsCodeBlock }"
  :custom-containers="{ warning: MyWarningContainer }"
  :components="{ heading: MyCustomHeading }"
/>
```

***

我们构建 Incremark 是因为我们自己需要它。希望它能帮助你构建更好的 AI 体验。

有问题？发现问题？[提交 GitHub Issue](https://github.com/kingshuaishuai/incremark/issues) 或查看我们的[文档](/)。

---

---
url: /zh/features/themes.md
---
# 主题

## 使用 ThemeProvider

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent, ThemeProvider } from '@incremark/vue'
</script>

<template>
  <ThemeProvider theme="dark">
    <IncremarkContent :content="content" />
  </ThemeProvider>
</template>
```

```tsx [React]
import { IncremarkContent, ThemeProvider } from '@incremark/react'

<ThemeProvider theme="dark">
  <IncremarkContent content={content} />
</ThemeProvider>
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent, ThemeProvider } from '@incremark/svelte'
</script>

<ThemeProvider theme="dark">
  <IncremarkContent {content} />
</ThemeProvider>
```

```tsx [Solid]
import { IncremarkContent, ThemeProvider } from '@incremark/solid'

<ThemeProvider theme="dark">
  <IncremarkContent content={content()} />
</ThemeProvider>
```

:::

## 内置主题

* `default` - 浅色主题
* `dark` - 深色主题

## 自定义主题

```ts
import { type DesignTokens } from '@incremark/vue'

const customTheme: Partial<DesignTokens> = {
  color: {
    brand: {
      primary: '#8b5cf6',
      primaryHover: '#7c3aed'
    }
  }
}

<ThemeProvider :theme="customTheme">
```

---

---
url: /zh/guide/introduction.md
---
# 介绍

**Incremark** 是专为 AI 时代设计的 Markdown 渲染器。它优先考虑**流式传输性能**、**增量更新**和**流畅的视觉效果**。

## 为什么选择 Incremark？

随着 LLM（大语言模型）的兴起，应用程序越来越多地展示流式文本。传统的 Markdown 解析器是为静态文档构建的，而不是为每秒更新 50 次的文本构建的。

这种不匹配导致：

* 长响应时 CPU 占用率高。
* 滚动和渲染卡顿。
* 难以在不破坏 Markdown 语法的情况下实现“打字机”效果。

**Incremark** 将 Markdown 渲染重新构想为一个流处理问题。

## 核心特性

* ⚡️ **极致性能**：平均比 Streamdown 快约 6 倍，比 ant-design-x 快约 7 倍，比 markstream-vue 快约 28 倍。
* 🔄 **双引擎架构**：Marked 引擎含增强扩展追求极速，Micromark 引擎追求 CommonMark 完美兼容。
* 🚀 **O(n) 增量解析**：只解析新增内容，18KB 文档比传统方案快 19 倍。
* ⌨️ **内置打字机**：流畅的逐字显示，且尊崇 Markdown 结构。
* 🧩 **框架无关**：核心逻辑共享；提供 Vue、React 和 Svelte 的连接器。
* 🎨 **主题化**：专为现代、暗黑模式优先的界面定制。
* 🛠 **DevTools**：实时检查解析过程。

## 准备好开始了吗？

查看 [快速开始](/zh/guide/quick-start) 以在几分钟内将其集成到您的应用中。

## AI 友好性

Incremark 为 AI 而生，我们的文档也是如此。我们为 LLM 提供了结构化的文档版本，以便更好地被索引和理解：

* [llms.txt](/llms.txt)：文档的精简索引。
* [llms-full.txt](/llms-full.txt)：完整文档的单文件版本，非常适合为 Claude、Cursor 或 ChatGPT 提供上下文。

---

---
url: /zh/advanced/engines.md
---
# 双引擎架构

Incremark 采用**双引擎解析系统**，这是我们在开发过程中做出的一个重要架构决策。我们希望为用户提供选择的自由：在追求极致性能和追求完美兼容性之间找到最适合自己的平衡点。

## 为什么需要双引擎？

在开发 Incremark 的过程中，我们面临一个核心问题：**如何在流式 AI 场景中实现最佳性能？**

经过大量调研和测试，我们发现：

* **Marked** 解析速度极快，但原生不支持脚注、数学公式等高级特性
* **Micromark** 规范兼容性完美，插件生态丰富，但包体积较大

最终我们决定：**两个都要**。

通过双引擎架构，用户可以根据实际场景灵活选择：

* 对性能敏感的 AI 聊天场景 → 使用 Marked 引擎
* 需要严格规范兼容的文档场景 → 使用 Micromark 引擎

## 引擎概览

| 引擎 | 速度 | 特性 | 包体积 | 最佳场景 |
|------|------|------|--------|----------|
| **Marked**（默认） | ⚡⚡⚡⚡⚡ | 标准 + 增强扩展 | 较小 | 实时流式、AI 对话 |
| **Micromark** | ⚡⚡⚡ | 完整 CommonMark + 插件 | 较大 | 复杂文档、严格规范 |

## Marked 引擎（默认）

**Marked 引擎**是我们的默认选择，专为**流式 AI 场景**深度优化。

### 为什么选择 Marked 作为默认引擎？

1. **极致的解析速度**：Marked 是 JavaScript 生态中最快的 Markdown 解析器之一
2. **成熟稳定**：拥有超过 10 年的历史，被无数项目验证
3. **易于扩展**：提供了灵活的扩展机制，我们可以按需增加功能
4. **小巧的包体积**：有利于前端项目的 tree-shaking 优化

### 我们为 Marked 做了什么增强？

原生 Marked 是一个"够用就好"的解析器，它专注于标准 Markdown 语法，不包含很多高级特性。但在 AI 场景中，我们经常需要这些特性。

因此，Incremark 通过自定义扩展为 Marked 增加了以下能力：

| 功能 | 原生 Marked | Incremark 增强 | 说明 |
|------|-------------|----------------|------|
| **脚注** | ❌ 不支持 | ✅ 完整 GFM 脚注 | `[^1]` 引用和 `[^1]: 内容` 定义 |
| **数学公式** | ❌ 不支持 | ✅ 行内和块级公式 | `$E=mc^2$` 和 `$$...$$` |
| **自定义容器** | ❌ 不支持 | ✅ 指令语法 | `:::tip`、`:::warning`、`:::danger` |
| **内联 HTML 解析** | ⚠️ 仅保留原文 | ✅ 结构化解析 | 将 HTML 解析为可操作的 AST 节点 |
| **乐观引用处理** | ❌ 不支持 | ✅ 流式友好 | 在流式输入时优雅处理未完成的链接/图片 |
| **脚注定义块** | ❌ 不支持 | ✅ 多行内容 | 支持包含代码块、列表的复杂脚注 |

> 💡 这些扩展是我们针对 AI 场景精心设计的。它们在提供完整功能的同时，尽可能减少性能开销。

### 使用方式

Marked 引擎是**默认**的，无需特殊配置：

```vue
<script setup>
import { ref } from 'vue'
import { IncremarkContent } from '@incremark/vue'

const content = ref('')
const isFinished = ref(false)
</script>

<template>
  <!-- 默认使用 Marked 引擎 -->
  <IncremarkContent 
    :content="content" 
    :is-finished="isFinished"
  />
</template>
```

### 启用/禁用特定功能

```vue
<template>
  <IncremarkContent 
    :content="content" 
    :is-finished="isFinished"
    :incremark-options="{
      gfm: true,        // GFM 扩展（表格、删除线等）
      math: true,       // 数学公式
      containers: true, // 自定义容器
      htmlTree: true    // HTML 结构化解析
    }"
  />
</template>
```

## Micromark 引擎

**Micromark 引擎**是追求完美规范兼容性的选择。

### 为什么提供 Micromark 选项？

尽管 Marked 引擎已经能满足大多数场景，但某些用户可能有更严格的需求：

1. **严格的 CommonMark 规范兼容**：Micromark 是目前最符合 CommonMark 规范的解析器
2. **丰富的插件生态**：GFM、Math、Directive 等插件都经过社区长期打磨
3. **精确的位置信息**：AST 节点包含准确的行列位置，便于错误定位
4. **更好的边界情况处理**：在一些复杂嵌套场景下表现更稳定

### 使用方式

要使用 Micromark 引擎，需要导入 `MicromarkAstBuilder` 并通过 `astBuilder` 选项传入：

```ts
// 在你的 composable 或 setup 中
import { createIncremarkParser } from '@incremark/core'
import { MicromarkAstBuilder } from '@incremark/core/engines/micromark'

const parser = createIncremarkParser({
  astBuilder: MicromarkAstBuilder,
  gfm: true,
  math: true
})
```

> **注意**：`IncremarkContent` 组件默认使用 Marked 引擎。如需使用 Micromark，你需要直接使用 `useIncremark` 配合自定义 parser。

### 何时应该使用 Micromark？

* 你的内容包含复杂的嵌套结构
* 你需要处理一些 Marked 无法正确解析的边界情况
* 你的应用对 CommonMark 规范兼容性有严格要求
* 你需要使用我们内置扩展之外的 Micromark 插件

## 完整基准测试数据

我们对 38 个真实的 Markdown 文件进行了基准测试，以下是完整的测试结果：

### 测试环境

* **测试文件**：38 个文件，共 6,484 行，128.55 KB
* **测试方式**：模拟流式输入，逐字符 append
* **对比方案**：Streamdown、markstream-vue、ant-design-x

### 完整测试结果

| 文件名 | 行数 | 大小(KB) | Incremark | Streamdown | markstream | ant-design-x | vs Streamdown | vs markstream | vs ant-design-x |
|--------|------|----------|-----------|------------|------------|--------------|---------------|---------------|-----------------|
| test-footnotes-simple.md | 15 | 0.09 | 0.3 ms | 0.0 ms | 1.4 ms | 0.2 ms | 0.1x | 4.7x | 0.6x |
| simple-paragraphs.md | 16 | 0.41 | 0.9 ms | 0.9 ms | 5.9 ms | 1.0 ms | 1.1x | 6.7x | 1.2x |
| test-footnotes-multiline.md | 21 | 0.18 | 0.6 ms | 0.0 ms | 2.2 ms | 0.4 ms | 0.1x | 3.5x | 0.6x |
| test-footnotes-edge-cases.md | 27 | 0.25 | 0.8 ms | 0.0 ms | 4.2 ms | 1.2 ms | 0.0x | 5.3x | 1.5x |
| test-footnotes-complex.md | 28 | 0.24 | 2.1 ms | 0.0 ms | 4.8 ms | 1.0 ms | 0.0x | 2.3x | 0.5x |
| introduction.md | 34 | 1.57 | 5.6 ms | 12.6 ms | 75.6 ms | 12.8 ms | 2.2x | 13.4x | 2.3x |
| devtools.md | 51 | 0.92 | 1.2 ms | 0.9 ms | 6.1 ms | 1.1 ms | 0.8x | 5.0x | 0.9x |
| footnotes.md | 52 | 0.94 | 1.7 ms | 0.2 ms | 10.6 ms | 1.9 ms | 0.1x | 6.3x | 1.2x |
| html-elements.md | 55 | 1.02 | 1.6 ms | 2.2 ms | 12.6 ms | 2.8 ms | 1.4x | 7.8x | 1.7x |
| themes.md | 58 | 0.96 | 1.9 ms | 1.3 ms | 8.6 ms | 1.8 ms | 0.7x | 4.4x | 0.9x |
| test-footnotes-comprehensive.md | 63 | 0.66 | 5.6 ms | 0.1 ms | 25.8 ms | 7.7 ms | 0.0x | 4.6x | 1.4x |
| auto-scroll.md | 72 | 1.68 | 3.9 ms | 3.5 ms | 39.9 ms | 4.9 ms | 0.9x | 10.1x | 1.2x |
| custom-codeblocks.md | 72 | 1.44 | 3.4 ms | 2.0 ms | 14.9 ms | 2.5 ms | 0.6x | 4.4x | 0.7x |
| custom-components.md | 73 | 1.40 | 4.0 ms | 2.0 ms | 32.7 ms | 2.9 ms | 0.5x | 8.1x | 0.7x |
| custom-containers.md | 88 | 1.67 | 4.2 ms | 2.4 ms | 18.1 ms | 3.1 ms | 0.6x | 4.3x | 0.7x |
| typewriter.md | 88 | 1.89 | 5.6 ms | 4.1 ms | 35.0 ms | 4.9 ms | 0.7x | 6.2x | 0.9x |
| concepts.md | 91 | 4.29 | 12.0 ms | 50.5 ms | 381.9 ms | 53.6 ms | 4.2x | 31.9x | 4.5x |
| INLINE\_CODE\_UPDATE.md | 94 | 1.66 | 4.7 ms | 17.2 ms | 60.9 ms | 15.6 ms | 3.7x | 12.9x | 3.3x |
| comparison.md | 109 | 5.39 | 20.5 ms | 74.0 ms | 552.2 ms | 85.2 ms | 3.6x | 26.9x | 4.1x |
| basic-usage.md | 130 | 3.04 | 8.5 ms | 12.3 ms | 74.1 ms | 14.1 ms | 1.4x | 8.7x | 1.7x |
| CODE\_BACKGROUND\_SEPARATION.md | 131 | 2.83 | 8.7 ms | 28.8 ms | 153.6 ms | 31.3 ms | 3.3x | 17.6x | 3.6x |
| P2\_SUMMARY.md | 138 | 2.61 | 8.3 ms | 38.4 ms | 157.2 ms | 41.9 ms | 4.6x | 18.9x | 5.0x |
| quick-start.md | 146 | 3.04 | 7.3 ms | 7.3 ms | 64.2 ms | 9.6 ms | 1.0x | 8.8x | 1.3x |
| complex-html-examples.md | 147 | 3.99 | 9.0 ms | 58.8 ms | 279.3 ms | 57.2 ms | 6.6x | 31.1x | 6.4x |
| CODE\_COLOR\_SEPARATION.md | 162 | 3.51 | 10.0 ms | 32.8 ms | 191.1 ms | 36.9 ms | 3.3x | 19.1x | 3.7x |
| P0\_OPTIMIZATION\_REPORT.md | 168 | 3.53 | 10.1 ms | 56.2 ms | 228.0 ms | 58.1 ms | 5.6x | 22.6x | 5.8x |
| COLOR\_SYSTEM\_REFACTOR.md | 169 | 3.78 | 18.5 ms | 64.0 ms | 355.5 ms | 69.1 ms | 3.5x | 19.2x | 3.7x |
| FOOTNOTE\_TEST\_GUIDE.md | 219 | 2.87 | 12.3 ms | 0.2 ms | 167.6 ms | 45.0 ms | 0.0x | 13.7x | 3.7x |
| P2\_COLORS\_PACKAGE\_REPORT.md | 226 | 4.10 | 11.4 ms | 77.9 ms | 311.6 ms | 80.5 ms | 6.8x | 27.2x | 7.0x |
| FOOTNOTE\_FIX\_SUMMARY.md | 236 | 3.93 | 22.7 ms | 0.5 ms | 535.0 ms | 120.8 ms | 0.0x | 23.6x | 5.3x |
| BASE\_COLORS\_SYSTEM.md | 259 | 4.47 | 35.8 ms | 43.0 ms | 191.8 ms | 43.4 ms | 1.2x | 5.4x | 1.2x |
| OPTIMIZATION\_COMPARISON.md | 270 | 5.42 | 17.8 ms | 52.3 ms | 366.1 ms | 61.9 ms | 2.9x | 20.6x | 3.5x |
| P1\_OPTIMIZATION\_REPORT.md | 327 | 5.63 | 20.7 ms | 106.8 ms | 433.8 ms | 114.8 ms | 5.2x | 21.0x | 5.5x |
| OPTIMIZATION\_PLAN.md | 371 | 6.89 | 33.1 ms | 67.6 ms | 372.1 ms | 76.7 ms | 2.0x | 11.2x | 2.3x |
| OPTIMIZATION\_SUMMARY.md | 391 | 6.24 | 19.1 ms | 208.4 ms | 980.6 ms | 217.8 ms | 10.9x | 51.3x | 11.4x |
| P1.5\_COLOR\_SYSTEM\_REPORT.md | 482 | 9.12 | 22.0 ms | 145.5 ms | 789.8 ms | 168.2 ms | 6.6x | 35.9x | 7.7x |
| BLOCK\_TRANSFORMER\_ANALYSIS.md | 489 | 9.24 | 75.7 ms | 574.3 ms | 1984.1 ms | 619.9 ms | 7.6x | 26.2x | 8.2x |
| test-md-01.md | 916 | 17.67 | 87.7 ms | 1441.1 ms | 5754.7 ms | 1656.9 ms | 16.4x | 65.6x | 18.9x |
| **【合计】** | **6484** | **128.55** | **519.4 ms** | **3190.3 ms** | **14683.9 ms** | **3728.6 ms** | **6.1x** | **28.3x** | **7.2x** |

### 如何理解这份数据？

#### 我们诚实地告诉你：有些场景 Incremark 更慢

你可能注意到，在 `test-footnotes-*.md` 和 `FOOTNOTE_*.md` 这些文件上，Incremark 比 Streamdown 慢很多（0.0x - 0.1x）。

**原因很简单：Streamdown 不支持脚注语法。**

当 Streamdown 遇到 `[^1]` 这样的脚注引用时，它直接跳过不处理。而 Incremark 会：

1. 识别脚注引用
2. 解析脚注定义块（可能包含多行内容、代码块、列表等）
3. 建立引用关系
4. 生成正确的 AST 结构

这不是性能问题，是**功能差异**。我们认为完整的脚注支持对于 AI 场景非常重要，所以选择实现它。

#### 真正的性能优势在哪里？

排除脚注相关的文件，看看标准 Markdown 内容的表现：

| 文件 | 行数 | Incremark | Streamdown | 优势 |
|------|------|-----------|------------|------|
| concepts.md | 91 | 12.0 ms | 50.5 ms | **4.2x** |
| comparison.md | 109 | 20.5 ms | 74.0 ms | **3.6x** |
| complex-html-examples.md | 147 | 9.0 ms | 58.8 ms | **6.6x** |
| P0\_OPTIMIZATION\_REPORT.md | 168 | 10.1 ms | 56.2 ms | **5.6x** |
| OPTIMIZATION\_SUMMARY.md | 391 | 19.1 ms | 208.4 ms | **10.9x** |
| test-md-01.md | 916 | 87.7 ms | 1441.1 ms | **16.4x** |

**结论**：对于标准 Markdown 内容，文档越大，Incremark 的优势越明显。

#### 为什么会有这样的差距？

这是 **O(n) vs O(n²)** 算法复杂度的直接体现。

传统解析器（Streamdown、ant-design-x、markstream-vue）每次接收新的 chunk 都要**重新解析整个文档**：

```
Chunk 1: 解析 100 字符
Chunk 2: 解析 200 字符 (100 旧 + 100 新)
Chunk 3: 解析 300 字符 (200 旧 + 100 新)
...
Chunk 100: 解析 10,000 字符
```

总工作量: `100 + 200 + 300 + ... + 10000 = 5,050,000` 次字符处理

**Incremark 的增量解析**只处理新内容：

```
Chunk 1: 解析 100 字符 → 缓存稳定块
Chunk 2: 仅解析 ~100 新字符
Chunk 3: 仅解析 ~100 新字符
...
Chunk 100: 仅解析 ~100 新字符
```

总工作量: `100 × 100 = 10,000` 次字符处理

差距是 **500 倍**。这就是为什么 18KB 的文档能快 16 倍以上。

## 功能对等性

我们努力确保两个引擎在功能上保持一致：

| 功能 | Marked 引擎 | Micromark 引擎 |
|------|-------------|----------------|
| GFM（表格、删除线、自动链接） | ✅ | ✅ |
| 数学公式（`$...$` 和 `$$...$$`） | ✅ | ✅ |
| 自定义容器（`:::tip` 等） | ✅ | ✅ |
| HTML 元素解析 | ✅ | ✅ |
| 脚注 | ✅ | ✅ |
| 打字机动画 | ✅ | ✅ |
| 增量更新 | ✅ | ✅ |

## 切换引擎

引擎选择是在**初始化时**进行的，而非运行时。这是为了 tree-shaking 优化而设计的。

### 为什么不支持运行时切换？

为了确保最优的打包体积：

* 默认导入只包含 `marked` 引擎
* `micromark` 引擎需要单独导入
* 这让打包工具可以 tree-shake 未使用的引擎

### 如何切换引擎

```vue
<script setup>
import { ref } from 'vue'
import { IncremarkContent } from '@incremark/vue'

const content = ref('')
const isFinished = ref(false)

// 引擎在初始化时选择
// 使用 marked（默认）：无需额外导入
// 使用 micromark：导入 MicromarkAstBuilder
</script>

<template>
  <!-- 默认使用 marked 引擎 -->
  <IncremarkContent 
    :content="content" 
    :is-finished="isFinished"
    :incremark-options="{ gfm: true, math: true }"
  />
</template>
```

### 使用 Micromark 引擎

要使用 micromark，从单独的引擎入口导入 `MicromarkAstBuilder`：

```ts
import { createIncremarkParser } from '@incremark/core'
import { MicromarkAstBuilder } from '@incremark/core/engines/micromark'

// 使用 micromark 引擎创建解析器
const parser = createIncremarkParser({
  astBuilder: MicromarkAstBuilder,
  gfm: true,
  math: true
})
```

> ⚠️ **Tree-shaking 说明**：从 `@incremark/core/engines/micromark` 导入只会将 micromark 添加到你的 bundle 中。默认导入只保留 marked。

## 扩展引擎

两个引擎都支持自定义扩展。详见 [扩展指南](/zh/advanced/extensions)。

```ts
// 自定义 marked 扩展示例
import { createCustomExtension } from '@incremark/core'

const myExtension = createCustomExtension({
  name: 'myPlugin',
  // ... 扩展配置
})
```

## 总结与建议

| 方面 | Marked | Micromark |
|------|--------|-----------|
| 解析速度 | ⚡⚡⚡⚡⚡ | ⚡⚡⚡ |
| 包体积 | 📦 更小 | 📦 较大 |
| CommonMark 兼容性 | ✅ 良好 | ✅ 完美 |
| 内置扩展 | ✅ 脚注、数学公式、容器 | ✅ 通过插件 |
| 插件生态 | 🔧 成长中 | 🔧 成熟 |
| 推荐场景 | 流式 AI、实时渲染 | 静态文档、严格规范 |

**我们的建议**：

1. **大多数场景**：使用默认的 Marked 引擎，它已经足够好
2. **遇到解析问题**：如果某些边界情况 Marked 处理不好，尝试切换到 Micromark
3. **极端性能需求**：Marked 引擎是你的最佳选择
4. **严格规范需求**：Micromark 引擎更适合你

我们会持续优化两个引擎，确保它们都能为你提供最好的体验。

---

---
url: /zh/features/i18n.md
---
# 国际化与无障碍

Incremark 提供了内置的国际化 (i18n) 和无障碍 (a11y) 支持，确保组件在不同语言环境下都能正常工作，并且对屏幕阅读器友好。

## 使用 ConfigProvider

`ConfigProvider` 用于提供全局的国际化配置：

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent, ConfigProvider, zhCN } from '@incremark/vue'
</script>

<template>
  <ConfigProvider :locale="zhCN">
    <IncremarkContent :content="content" />
  </ConfigProvider>
</template>
```

```tsx [React]
import { IncremarkContent, ConfigProvider, zhCN } from '@incremark/react'

<ConfigProvider locale={zhCN}>
  <IncremarkContent content={content} />
</ConfigProvider>
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent, ConfigProvider, zhCN } from '@incremark/svelte'
</script>

<ConfigProvider locale={zhCN}>
  <IncremarkContent {content} />
</ConfigProvider>
```

```tsx [Solid]
import { IncremarkContent, ConfigProvider, zhCN } from '@incremark/solid'

<ConfigProvider locale={zhCN}>
  <IncremarkContent content={content()} />
</ConfigProvider>
```

:::

## 内置语言包

Incremark 内置了以下语言包：

| 语言包 | 语言 |
|--------|------|
| `en` | 英文（默认） |
| `zhCN` | 简体中文 |

```ts
import { en, zhCN } from '@incremark/vue'
// 或
import { en, zhCN } from '@incremark/react'
// 或
import { en, zhCN } from '@incremark/svelte'
// 或
import { en, zhCN } from '@incremark/solid'
```

## 自定义语言包

你可以创建自定义语言包来支持其他语言：

```ts
import type { IncremarkLocale } from '@incremark/vue'

const jaJP: IncremarkLocale = {
  code: {
    copy: 'コードをコピー',
    copied: 'コピーしました'
  },
  mermaid: {
    copy: 'コードをコピー',
    copied: 'コピーしました',
    viewSource: 'ソースコードを表示',
    preview: 'プレビュー'
  }
}
```

## 无障碍支持

Incremark 的 UI 组件遵循 WAI-ARIA 规范，提供了完整的无障碍支持：

### 代码块

* 复制按钮使用 `aria-label` 提供清晰的操作描述
* 按钮状态变化（如复制成功）会更新 `aria-label`
* 语言标签清晰可读

```html
<!-- 复制前 -->
<button aria-label="复制代码">...</button>

<!-- 复制后 -->
<button aria-label="代码已复制">...</button>
```

### Mermaid 图表

* 切换按钮（源代码/预览）使用 `aria-label`
* 图表容器提供适当的语义标签

## 组合使用

`ConfigProvider` 可以与 `ThemeProvider` 组合使用：

::: code-group

```vue [Vue]
<script setup>
import { 
  IncremarkContent, 
  ConfigProvider, 
  ThemeProvider, 
  zhCN 
} from '@incremark/vue'
</script>

<template>
  <ConfigProvider :locale="zhCN">
    <ThemeProvider theme="dark">
      <IncremarkContent :content="content" />
    </ThemeProvider>
  </ConfigProvider>
</template>
```

```tsx [React]
import { 
  IncremarkContent, 
  ConfigProvider, 
  ThemeProvider, 
  zhCN 
} from '@incremark/react'

<ConfigProvider locale={zhCN}>
  <ThemeProvider theme="dark">
    <IncremarkContent content={content} />
  </ThemeProvider>
</ConfigProvider>
```

```svelte [Svelte]
<script lang="ts">
  import {
    IncremarkContent,
    ConfigProvider,
    ThemeProvider,
    zhCN
  } from '@incremark/svelte'
</script>

<ConfigProvider locale={zhCN}>
  <ThemeProvider theme="dark">
    <IncremarkContent {content} />
  </ThemeProvider>
</ConfigProvider>
```

```tsx [Solid]
import {
  IncremarkContent,
  ConfigProvider,
  ThemeProvider,
  zhCN
} from '@incremark/solid'

<ConfigProvider locale={zhCN}>
  <ThemeProvider theme="dark">
    <IncremarkContent content={content()} />
  </ThemeProvider>
</ConfigProvider>
```

:::

## 动态切换语言

语言可以在运行时动态切换：

::: code-group

```vue [Vue]
<script setup>
import { ref, computed } from 'vue'
import { ConfigProvider, en, zhCN } from '@incremark/vue'

const lang = ref('en')
const locale = computed(() => lang.value === 'zh' ? zhCN : en)

function toggleLocale() {
  lang.value = lang.value === 'en' ? 'zh' : 'en'
}
</script>

<template>
  <button @click="toggleLocale">切换语言</button>
  <ConfigProvider :locale="locale">
    <IncremarkContent :content="content" />
  </ConfigProvider>
</template>
```

```tsx [React]
import { useState, useMemo } from 'react'
import { ConfigProvider, en, zhCN } from '@incremark/react'

function App() {
  const [lang, setLang] = useState('en')
  const locale = useMemo(() => lang === 'zh' ? zhCN : en, [lang])
  
  return (
    <>
      <button onClick={() => setLang(l => l === 'en' ? 'zh' : 'en')}>
        切换语言
      </button>
      <ConfigProvider locale={locale}>
        <IncremarkContent content={content} />
      </ConfigProvider>
    </>
  )
}
```

```svelte [Svelte]
<script lang="ts">
  import { ConfigProvider, en, zhCN } from '@incremark/svelte'

  let lang = $state('en')
  const locale = $derived(lang === 'zh' ? zhCN : en)

  function toggleLocale() {
    lang = lang === 'en' ? 'zh' : 'en'
  }
</script>

<button onclick={toggleLocale}>切换语言</button>
<ConfigProvider locale={locale}>
  <IncremarkContent {content} />
</ConfigProvider>
```

```tsx [Solid]
import { createSignal, Index } from 'solid-js'
import { ConfigProvider, en, zhCN } from '@incremark/solid'

function App() {
  const [lang, setLang] = createSignal('en')
  const locale = () => lang() === 'zh' ? zhCN : en
  const [key, setKey] = createSignal(0)

  function toggleLocale() {
    setLang(l => l === 'en' ? 'zh' : 'en')
    setKey(k => k + 1)
  }

  return (
    <>
      <button onClick={toggleLocale}>切换语言</button>
      <Index each={[key()]}>
        {() => (
          <ConfigProvider locale={locale()}>
            <IncremarkContent content={content()} />
          </ConfigProvider>
        )}
      </Index>
    </>
  )
}
```

:::

## Locale 类型定义

```ts
interface IncremarkLocale {
  /** 代码块相关翻译 */
  code: {
    /** 复制代码按钮文本 */
    copy: string
    /** 复制成功后的提示文本 */
    copied: string
  }
  /** Mermaid 图表相关翻译 */
  mermaid: {
    /** 复制代码按钮文本 */
    copy: string
    /** 复制成功后的提示文本 */
    copied: string
    /** 查看源代码按钮文本 */
    viewSource: string
    /** 预览图表按钮文本 */
    preview: string
  }
}
```

---

---
url: /zh/features/basic-usage.md
---
# 基础用法

**IncremarkContent 组件完整指南**

## 两种输入模式

1. **content 模式**：传入累积的字符串 + isFinished 标志
2. **stream 模式**：传入返回 AsyncGenerator 的函数

## Props 参考

```ts
interface IncremarkContentProps {
  // 输入（二选一）
  content?: string                       // 累积字符串
  stream?: () => AsyncGenerator<string>  // 异步生成器函数

  // 状态
  isFinished?: boolean                   // 流结束标志（content 模式必需）

  // 配置
  incremarkOptions?: UseIncremarkOptions // 解析器 + 打字机配置

  // 自定义渲染
  components?: ComponentMap              // 自定义组件
  customContainers?: Record<string, Component>
  customCodeBlocks?: Record<string, Component>
  codeBlockConfigs?: Record<string, CodeBlockConfig>

  // 样式
  showBlockStatus?: boolean              // 显示 block 状态边框
  pendingClass?: string                  // pending block 的 CSS 类
}
```

### UseIncremarkOptions

```ts
interface UseIncremarkOptions {
  // 解析器选项
  gfm?: boolean              // GFM 支持（表格、任务列表等）
  math?: boolean | MathOptions // 数学公式支持
  htmlTree?: boolean         // HTML 片段解析
  containers?: boolean       // ::: 容器语法

  // 打字机选项
  typewriter?: {
    enabled?: boolean
    charsPerTick?: number | [number, number]
    tickInterval?: number
    effect?: 'none' | 'fade-in' | 'typing'
    cursor?: string
  }
}

interface MathOptions {
  // 启用 TeX 风格的 \(...\) 和 \[...\] 语法
  tex?: boolean
}
```

### 数学公式配置

默认情况下，`math: true` 只支持 `$...$` 和 `$$...$$` 语法。

如果需要支持 TeX/LaTeX 风格的 `\(...\)` 和 `\[...\]` 分隔符，可以开启 **tex** 选项：

```ts
// 启用 TeX 风格分隔符
const options = {
  math: { tex: true }
}
```

这在处理学术论文或某些 AI 工具输出时非常有用。

## 进阶：使用 `useIncremark`

当需要更细粒度控制时：

::: code-group

```vue [Vue]
<script setup>
import { useIncremark, Incremark } from '@incremark/vue'

const { blocks, append, finalize, reset } = useIncremark({ gfm: true })

async function handleStream(stream) {
  reset()
  for await (const chunk of stream) {
    append(chunk)
  }
  finalize()
}
</script>

<template>
  <Incremark :blocks="blocks" />
</template>
```

```tsx [React]
import { useIncremark, Incremark } from '@incremark/react'

function App() {
  const { blocks, append, finalize, reset } = useIncremark({ gfm: true })

  async function handleStream(stream) {
    reset()
    for await (const chunk of stream) {
      append(chunk)
    }
    finalize()
  }

  return <Incremark blocks={blocks} />
}
```

```svelte [Svelte]
<script lang="ts">
  import { useIncremark, Incremark } from '@incremark/svelte'

  const { blocks, append, finalize, reset } = useIncremark({ gfm: true })

  async function handleStream(stream) {
    reset()
    for await (const chunk of stream) {
      append(chunk)
    }
    finalize()
  }
</script>

<Incremark {blocks} />
```

```tsx [Solid]
import { useIncremark, Incremark } from '@incremark/solid'

function App() {
  const { blocks, append, finalize, reset } = useIncremark({ gfm: true })

  async function handleStream(stream) {
    reset()
    for await (const chunk of stream) {
      append(chunk)
    }
    finalize()
  }

  return <Incremark blocks={blocks()} />
}
```

:::

### useIncremark 返回值

| 属性 | 类型 | 说明 |
|---|---|---|
| `blocks` | `Block[]` | 所有块（含稳定 ID） |
| `markdown` | `string` | 已收集的完整 Markdown |
| `append(chunk)` | `Function` | 追加内容 |
| `finalize()` | `Function` | 完成解析 |
| `reset()` | `Function` | 重置状态 |
| `render(content)` | `Function` | 一次性渲染 |
| `isDisplayComplete` | `boolean` | 打字机效果是否完成 |

---

---
url: /zh/guide/quick-start.md
---
# 快速开始

在 5 分钟内完成特定框架的集成并运行。

## 安装

::: code-group

```bash [pnpm]
pnpm add @incremark/vue @incremark/theme
# 或
pnpm add @incremark/react @incremark/theme
# 或
pnpm add @incremark/svelte @incremark/theme
# 或
pnpm add @incremark/solid @incremark/theme
```

```bash [npm]
npm install @incremark/vue @incremark/theme
# 或
npm install @incremark/react @incremark/theme
# 或
npm install @incremark/svelte @incremark/theme
# 或
npm install @incremark/solid @incremark/theme
```

```bash [yarn]
yarn add @incremark/vue @incremark/theme
# 或
yarn add @incremark/react @incremark/theme
# 或
yarn add @incremark/svelte @incremark/theme
# 或
yarn add @incremark/solid @incremark/theme
```

:::

## 基础用法

::: code-group

```vue [Vue]
<script setup>
import { ref } from 'vue'
import { IncremarkContent } from '@incremark/vue'
import '@incremark/theme/styles.css' // [!code hl]

const content = ref('')
const isFinished = ref(false)

async function simulateStream() {
  content.value = ''
  isFinished.value = false

  const text = '# Hello\n\nThis is **Incremark**!'
  for (const chunk of text.match(/[\s\S]{1,5}/g) || []) {
    content.value += chunk
    await new Promise(r => setTimeout(r, 50))
  }
  isFinished.value = true
}
</script>

<template>
  <button @click="simulateStream">Start</button>
  <IncremarkContent :content="content" :is-finished="isFinished" />
</template>
```

```tsx [React]
import { useState } from 'react'
import { IncremarkContent } from '@incremark/react'
import '@incremark/theme/styles.css' // [!code hl]

function App() {
  const [content, setContent] = useState('')
  const [isFinished, setIsFinished] = useState(false)

  async function simulateStream() {
    setContent('')
    setIsFinished(false)

    const text = '# Hello\n\nThis is **Incremark**!'
    const chunks = text.match(/[\s\S]{1,5}/g) || []
    for (const chunk of chunks) {
      setContent(prev => prev + chunk)
      await new Promise(r => setTimeout(r, 50))
    }
    setIsFinished(true)
  }

  return (
    <>
      <button onClick={simulateStream}>Start</button>
      <IncremarkContent content={content} isFinished={isFinished} />
    </>
  )
}
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent } from '@incremark/svelte'
  import '@incremark/theme/styles.css' // [!code hl]

  let content = $state('')
  let isFinished = $state(false)

  async function simulateStream() {
    content = ''
    isFinished = false

    const text = '# Hello\n\nThis is **Incremark**!'
    for (const chunk of text.match(/[\s\S]{1,5}/g) || []) {
      content += chunk
      await new Promise(r => setTimeout(r, 50))
    }
    isFinished = true
  }
</script>

<button onclick={simulateStream}>Start</button>
<IncremarkContent {content} {isFinished} />
```

```tsx [Solid]
import { createSignal } from 'solid-js'
import { IncremarkContent } from '@incremark/solid'
import '@incremark/theme/styles.css' // [!code hl]

function App() {
  const [content, setContent] = createSignal('')
  const [isFinished, setIsFinished] = createSignal(false)

  async function simulateStream() {
    setContent('')
    setIsFinished(false)

    const text = '# Hello\n\nThis is **Incremark**!'
    const chunks = text.match(/[\s\S]{1,5}/g) || []
    for (const chunk of chunks) {
      setContent(prev => prev + chunk)
      await new Promise(r => setTimeout(r, 50))
    }
    setIsFinished(true)
  }

  return (
    <>
      <button onClick={simulateStream}>Start</button>
      <IncremarkContent content={content()} isFinished={isFinished()} />
    </>
  )
}
```

:::

## 使用流模式

```vue
<script setup>
import { IncremarkContent } from '@incremark/vue'

async function* fetchAIStream() {
  const res = await fetch('/api/chat', { method: 'POST' })
  const reader = res.body!.getReader()
  const decoder = new TextDecoder()

  while (true) {
    const { done, value } = await reader.read()
    if (done) break
    yield decoder.decode(value)
  }
}
</script>

<template>
  <IncremarkContent :stream="fetchAIStream" />
</template>
```

## 数学公式 (可选)

如果你需要支持数学公式 (Katex)，请确保也导入了 Katex 的 CSS：

```ts
import 'katex/dist/katex.min.css'
```

---

---
url: /zh/advanced/benchmark.md
---
# 性能测试

本文介绍如何运行 Incremark 的性能测试，对比不同流式 Markdown 解析器的性能表现。

## 测试目的

对比以下解析器在 AI 流式输出场景下的性能：

* **Incremark** - 专为 AI 流式输出的增量解析器，O(n) 时间复杂度
* **Streamdown** - 另一款流式 Markdown 解析器
* **markstream-vue** - 面向 Vue 的流式解析方案
* **marked (ant-design-x)** - 传统全量重解析方案，O(n²) 时间复杂度

## 测试方法

测试模拟 AI 流式输出场景，逐字符解析 Markdown 文本，记录每一步的解析时间。

测试数据位于 `benchmark-compare/test-data/` 目录，包含多种典型场景：

* 纯文本
* 带格式文本（加粗、斜体、代码等）
* 包含代码块的文本
* 混合复杂格式

## 运行测试

### 1. 克隆测试脚本

```bash
# 从项目仓库获取独立测试脚本
cd benchmark-compare
```

### 2. 安装依赖

```bash
pnpm install
```

### 3. 运行测试

```bash
pnpm benchmark
```

## 预期结果

测试完成后会输出各解析器的性能对比结果，包括：

* 总解析时间
* 平均每步解析时间
* 峰值解析时间

## 结果分析

Incremark 的增量解析算法确保：

* **O(n) 时间复杂度** - 每次只解析新增内容
* **稳定的性能表现** - 避免全量重解析的性能峰值
* **更适合流式场景** - 随着文本增长，性能优势更明显

而传统方案（如 marked）每次都重新解析整个文本，时间复杂度为 O(n²)，在长文本流式输出场景下性能会显著下降。

---

---
url: /zh/features/typewriter.md
---
# 打字机效果

## 启用打字机效果

::: code-group

```vue [Vue]
<script setup>
import { ref, computed } from 'vue'
import { IncremarkContent, type UseIncremarkOptions } from '@incremark/vue'

const content = ref('')
const isFinished = ref(false)

const options = computed<UseIncremarkOptions>(() => ({
  typewriter: {
    enabled: true,
    charsPerTick: [1, 3],
    tickInterval: 30,
    effect: 'typing'
  }
}))
</script>

<template>
  <IncremarkContent
    :content="content"
    :is-finished="isFinished"
    :incremark-options="options"
  />
</template>
```

```tsx [React]
import { IncremarkContent, UseIncremarkOptions } from '@incremark/react'

const options: UseIncremarkOptions = {
  typewriter: {
    enabled: true,
    charsPerTick: [1, 3],
    tickInterval: 30,
    effect: 'typing'
  }
}

<IncremarkContent
  content={content}
  isFinished={isFinished}
  incremarkOptions={options}
/>
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent, type UseIncremarkOptions } from '@incremark/svelte'

  let content = $state('')
  let isFinished = $state(false)

  const options: UseIncremarkOptions = {
    typewriter: {
      enabled: true,
      charsPerTick: [1, 3],
      tickInterval: 30,
      effect: 'typing'
    }
  }
</script>

<IncremarkContent {content} {isFinished} incremarkOptions={options} />
```

```tsx [Solid]
import { createSignal } from 'solid-js'
import { IncremarkContent, type UseIncremarkOptions } from '@incremark/solid'

function App() {
  const [content, setContent] = createSignal('')
  const [isFinished, setIsFinished] = createSignal(false)

  const options: UseIncremarkOptions = {
    typewriter: {
      enabled: true,
      charsPerTick: [1, 3],
      tickInterval: 30,
      effect: 'typing'
    }
  }

  return (
    <IncremarkContent
      content={content()}
      isFinished={isFinished()}
      incremarkOptions={options}
    />
  )
}
```

:::

## 配置

| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `enabled` | `boolean` | `false` | 启用打字机 |
| `charsPerTick` | `number \| [min, max]` | `2` | 每次显示的字符数 |
| `tickInterval` | `number` | `50` | 更新间隔 (ms) |
| `effect` | `'none' \| 'fade-in' \| 'typing'` | `'none'` | 动画效果 |
| `cursor` | `string` | `'\|'` | 光标字符 |

## 动画效果说明

* **none**：无动画，直接显示。
* **fade-in**：淡入效果，新字符透明度过渡。
* **typing**：打字机效果，带有光标。

---

---
url: /zh/advanced/extensions.md
---
# 扩展功能

Incremark 的双引擎架构为 `micromark` 和 `marked` 引擎提供了灵活的扩展机制。

## 引擎选择

根据你的扩展需求选择合适的引擎：

| 引擎 | 扩展类型 | 适用场景 |
|------|---------|---------|
| `micromark` | micromark + mdast 扩展 | 丰富的生态，CommonMark 兼容 |
| `marked` | 自定义 Token 转换器 | 极致性能，简单扩展 |

## Micromark 扩展

使用 `micromark` 引擎时，可以利用丰富的现有扩展生态。

### 语法扩展

使用 `micromark` 扩展支持新语法：

```vue
<script setup>
import { ref } from 'vue'
import { IncremarkContent } from '@incremark/vue'
import { gfmTable } from 'micromark-extension-gfm-table'

const content = ref('')
const isFinished = ref(false)

// 注意：extensions 选项仅用于 micromark 引擎
// 需要配合 MicromarkAstBuilder 使用
import { MicromarkAstBuilder } from '@incremark/core/engines/micromark'

const parser = createIncremarkParser({
  astBuilder: MicromarkAstBuilder,
  extensions: [gfmTable()]
})
</script>

<template>
  <IncremarkContent 
    :content="content" 
    :is-finished="isFinished"
    :incremark-options="options" 
  />
</template>
```

### AST 扩展

使用 `mdast-util-from-markdown` 扩展将语法转换为 AST 节点：

```ts
import { gfmTableFromMarkdown } from 'mdast-util-gfm-table'

import { MicromarkAstBuilder } from '@incremark/core/engines/micromark'

const parser = createIncremarkParser({
  astBuilder: MicromarkAstBuilder,
  extensions: [gfmTable()],
  mdastExtensions: [gfmTableFromMarkdown()]
})
```

### 常用扩展包

| 包名 | 描述 |
|-----|------|
| `micromark-extension-gfm` | 完整 GFM 支持 |
| `micromark-extension-math` | 数学公式 |
| `micromark-extension-directive` | 自定义容器 |
| `micromark-extension-frontmatter` | YAML frontmatter |

## Marked 扩展

`marked` 引擎使用自定义扩展系统。Incremark 已经为 `marked` 扩展了以下功能：

* **脚注**: `[^1]` 引用和 `[^1]: content` 定义
* **数学公式**: `$inline$` 和 `$$block$$` 公式
* **自定义容器**: `:::type` 语法
* **内联 HTML**: 结构化 HTML 元素解析

### 自定义 Token 转换器

对于 `marked` 引擎，你可以提供自定义的 Token 转换器：

```ts
import type { BlockTokenTransformer, InlineTokenTransformer } from '@incremark/core'

// 自定义块级转换器
const myBlockTransformer: BlockTokenTransformer = (token, ctx) => {
  if (token.type === 'myCustomBlock') {
    return {
      type: 'paragraph',
      children: [{ type: 'text', value: token.raw }]
    }
  }
  return null
}

// 对于 marked 引擎（默认），使用 customBlockTransformers
const parser = createIncremarkParser({
  // marked 是默认引擎，无需指定 astBuilder
  customBlockTransformers: {
    myCustomBlock: myBlockTransformer
  }
})
```

### 内置转换器

你可以访问和扩展内置转换器：

```ts
import { 
  getBuiltinBlockTransformers, 
  getBuiltinInlineTransformers 
} from '@incremark/core'

// 获取所有内置转换器
const blockTransformers = getBuiltinBlockTransformers()
const inlineTransformers = getBuiltinInlineTransformers()

// 覆盖特定转换器
const customTransformers = {
  ...blockTransformers,
  code: (token, ctx) => {
    // 自定义代码块处理
    return { type: 'code', value: token.text, lang: token.lang }
  }
}
```

## UI 层扩展

除了解析器扩展，Incremark 还提供 UI 层的自定义能力：

### 自定义组件

替换任意节点类型的默认渲染：

```vue
<IncremarkContent 
  :content="content" 
  :is-finished="isFinished"
  :components="{ heading: MyCustomHeading }"
/>
```

### 自定义代码块

为特定语言的代码块使用自定义组件：

```vue
<IncremarkContent 
  :content="content" 
  :is-finished="isFinished"
  :custom-code-blocks="{ echarts: MyEchartsRenderer }"
  :code-block-configs="{ echarts: { takeOver: true } }"
/>
```

### 自定义容器

使用自定义组件渲染 `:::type` 容器：

```vue
<IncremarkContent 
  :content="content" 
  :is-finished="isFinished"
  :custom-containers="{ 
    warning: WarningBox,
    info: InfoBox,
    tip: TipBox 
  }"
/>
```

## 扩展最佳实践

1. **选择合适的引擎**: 复杂语法扩展使用 `micromark`，性能敏感场景使用 `marked`。

2. **利用现有包**: micromark 生态有很多经过充分测试的扩展。

3. **优先 UI 层扩展**: 对于视觉定制，优先使用 UI 层扩展（自定义组件）而非解析器扩展。

4. **充分测试**: 自定义扩展可能影响不同 Markdown 输入的解析行为。

---

---
url: /zh/guide/comparison.md
---
# 方案对比

本文档对流式 Markdown 渲染方案进行深度技术对比：**Incremark**、**ant-design-x** (Ant Design X Markdown) 和 **markstream-vue**。

## 全流程图解

### 1. Incremark (本方案)

**策略：增量解析 + 结构化打字机动画**

```mermaid
graph TD
    Input["流式 Chunk (如 'ng')"] --> Parser["IncremarkParser (增量解析)"]
    subgraph Core ["增量引擎"]
        Parser --> Boundary["稳定边界检测 (检测空行/标题等)"]
        Boundary --> Completed["已完成块 (缓存, 不再解析)"]
        Boundary --> Pending["待处理块 (在此区块内增量更新)"]
    end
    Pending --> Transformer["BlockTransformer (动画管理)"]
    Transformer --> AST["增量追加 AST (TextChunk 追踪)"]
    AST --> Renderer["框架渲染 (React/Vue)"]
    Renderer --> DOM["局部渲染 (组件更新)"]
```

* **关键特点**：仅解析新增或未完成的部分。动画在 AST 节点层操作，已稳定节点不重复遍历。性能复杂度为 **O(N)**。

***

### 2. ant-design-x (Ant Design X)

**策略：正则边界修复 + 全量解析 (Marked)**

```mermaid
graph TD
    Input["流式 Markdown 字符串"] --> Hook["useStreaming (正则拦截)"]
    subgraph Logic ["修复逻辑"]
        Hook --> Regex["STREAM_INCOMPLETE_REGEX (检测断连图片/链接/表格)"]
        Regex --> Buffer["缓冲区 (等待 Token 完整)"]
    end
    Buffer --> Marked["Marked.js (全量解析)"]
    Marked --> HTML["HTML 字符串"]
    HTML --> ReactParser["html-react-parser (React 转换)"]
    ReactParser --> Animation["AnimationText (文本切片动画)"]
    Animation --> DOM["React DOM"]
```

* **关键特点**：通过复杂的正则预判 Markdown 语法截断。每次更新都需将历史全量内容重新解析为 HTML。动画在纯文本层通过字符串切片实现。性能复杂度为 **O(N²)**。

***

### 3. markstream-vue

**策略：全量解析 + 虚拟化/批量渲染 (markdown-it)**

```mermaid
graph TD
    Input["Markdown 字符串"] --> PreProcess["正则边界粗修 (parseMarkdownToStructure)"]
    PreProcess --> MarkdownIt["markdown-it (全量解析)"]
    subgraph Render ["优化渲染层"]
        MarkdownIt --> Batch["批量渲染 (requestIdleCallback)"]
        Batch --> Virtual["虚拟化 (仅渲染视口内节点)"]
    end
    Virtual --> VueDOM["Vue 组件树"]
```

* **关键特点**：虽然采用全量解析，但通过极其精细的渲染层控制（虚拟化、首屏优化、空闲时间批量更新）解决了超长文档的渲染卡顿问题。适用于阅读大型静态文档或历史对话。

***

## 核心原理对比

| 维度 | ant-design-x (epx) | markstream-vue (epx2) | Incremark (core) |
| :--- | :--- | :--- | :--- |
| **解析引擎** | `marked` | `markdown-it` | **双引擎：`marked`（默认）+ `micromark`** |
| **解析策略** | 全量解析 (Full Re-parse) | 全量解析 (Full Re-parse) | **增量解析 (Incremental)** |
| **性能复杂度** | O(N²) | O(N²) | **O(N)** |
| **流式边界处理** | **正则修复** (精准拦截不完整 Token) | **正则粗修** (裁剪末尾危险字符) | **稳定边界检测** (基于状态机的上下文感知) |
| **打字机动画** | 纯文本层 (字符串切片) | 组件层 (`<transition>`) | **AST 节点层** (TextChunk 增量追加) |
| **动画性能** | 随内容增长 CPU 消耗增加 | O(1) 挂载开销 | **恒定 CPU 消耗 (仅处理新增字符)** |
| **大文档优化** | 无 | **强制虚拟化 + 批量渲染** | **稳定 ID + 局部更新** |
| **插件生态** | 有限 | markdown-it 插件 | **micromark + mdast + marked 扩展** |
| **框架支持** | React | Vue | **Vue + React + Svelte (共享核心逻辑)** |

***

## 技术细节深究

### 1. 增量解析 vs 全量解析

当文档长度为 10,000 字时，新推入 10 个字：

* **全量方案 (ant-design-x / markstream-vue)**：解析器需要扫描并分析 10,010 个字符。随着对话增长，解析耗时呈指数级上升。
* **增量方案 (Incremark)**：`IncremarkParser` 识别出前 10,000 字已处于“稳定块”，直接从缓冲区读取已有的 AST，仅对新增的 10 个字符进行有限上下文分析。

### 2. 动画实现层级

* **文本层 (ant-design-x)**：动画器不知道当前字符属于标题还是代码块，只是机械地切分字符串。这在处理高频更新时容易导致结构闪烁。
* **组件层 (markstream-vue)**：动画粒度较粗，通常是整个段落或块级节点的渐入，较难实现丝滑的逐字符打字感。
* **AST 层 (Incremark)**：`BlockTransformer` 感知 AST 结构。它知道哪里是新增的文本节点。通过在 AST 节点内部维护 `TextChunk` 队列，可以实现跨节点的平滑打字效果，同时保证 Markdown 结构的完整性（例如：永远不会在 `**bold**` 动画中间由于结构未闭合而导致渲染崩溃）。

***

## 各自优势与适用场景

### **Ant Design X** (AI 专用组件库)

* **优势**：组件套件及其完备（包含 Bubble, Prompt 等），与 Ant Design 视觉风格高度统一。其正则修复策略在处理极其复杂的截断（如链接中途截断）时表现非常稳健。
* **适用场景**：需要快速搭建基于 Ant Design 的标准 AI 聊天室，且文档长度适中的场景。

### **markstream-vue** (大规模文档专家)

* **优势**：内置了极其强大的虚拟化渲染和批量更新机制。即使解析效率不是最高的，但渲染层足以支撑万级以上节点的列表展示而不掉帧。
* **适用场景**：需要展示超长 AI 响应结果、长篇 PDF 解析结果或需要复杂虚拟化滚动的 Vue 应用。

### **Incremark** (极致流式体验)

* **优势**：
  1. **极低延迟**：增量解析保证了即使在长达数十万 Token 的会话中，每一帧的响应时间依然保持在 1ms 以内。
  2. **高性能动画**：结构化动画方案降低了 90% 以上的无用 DOM 更新。
  3. **开发灵活性**：一套核心 API 同时支持 Vue、React 和 Svelte 等多个框架，且完全兼容 mdast。
* **适用场景**：对实时性要求极高、存在长上下文流式输出、或需要在多个技术栈间复用渲染逻辑的商业级 AI 应用。

***

## 基准测试结果

我们在 38 个真实 markdown 文档上进行了广泛的基准测试（共 6,484 行，128.55 KB）。

> 📊 查看[完整的基准测试数据](/zh/advanced/engines#完整基准测试数据)，包含所有 38 个测试文件的详细结果。

### 总体性能对比（平均值）

| 对比方案 | 平均优势 |
|----------|----------|
| vs Streamdown | 约**快 6.1 倍** |
| vs ant-design-x | 约**快 7.2 倍** |
| vs markstream-vue | 约**快 28.3 倍** |

> ⚠️ 以上是所有测试场景的平均结果。单个文件的性能表现会因内容类型而异。

### 随文档大小扩展的性能表现

文档越大，Incremark 的优势越明显 —— O(n) vs O(n²)：

| 文件 | 行数 | 大小 | Incremark | ant-design-x | 优势倍数 |
|------|------|------|-----------|--------------|----------|
| introduction.md | 34 | 1.57 KB | 5.6 ms | 12.8 ms | **2.3x** |
| comparison.md | 109 | 5.39 KB | 20.5 ms | 85.2 ms | **4.1x** |
| BLOCK\_TRANSFORMER.md | 489 | 9.24 KB | 75.7 ms | 619.9 ms | **8.2x** |
| test-md-01.md | 916 | 17.67 KB | 87.7 ms | 1656.9 ms | **18.9x** 🚀 |

### 理解性能差异

#### 为什么 Incremark 有时比 Streamdown "更慢"

在某些基准测试中，Incremark 看起来比 Streamdown 慢：

| 文件 | Incremark | Streamdown | 原因 |
|------|-----------|------------|------|
| footnotes.md | 1.7 ms | 0.2 ms | Streamdown **不支持脚注** |
| FOOTNOTE\_FIX\_SUMMARY.md | 22.7 ms | 0.5 ms | 同上 — 跳过脚注解析 |

**这是功能差异，不是性能问题：**

* Streamdown 跳过不支持的语法 → 看起来更快
* Incremark 完整解析脚注、数学公式、容器 → 做了更多工作

#### Incremark 的增强功能

Incremark 通过自定义扩展增强了 Marked，这些是 Streamdown 不支持的：

| 功能 | Incremark | Streamdown |
|------|-----------|------------|
| **脚注** | ✅ 完整 GFM 脚注 | ❌ 不支持 |
| **数学公式** | ✅ `$...$` 和 `$$...$$` | ⚠️ 部分支持 |
| **自定义容器** | ✅ `:::tip`、`:::warning` | ❌ 不支持 |
| **内联 HTML 解析** | ✅ 完整 HTML 树 | ⚠️ 基础支持 |

#### Incremark 真正的优势场景

对于标准 markdown（不含脚注），Incremark 持续领先：

| 文件 | 行数 | Incremark | Streamdown | vs Streamdown |
|------|------|-----------|------------|---------------|
| concepts.md | 91 | 12.0 ms | 50.5 ms | **4.2x** |
| complex-html-examples.md | 147 | 9.0 ms | 58.8 ms | **6.6x** |
| OPTIMIZATION\_SUMMARY.md | 391 | 19.1 ms | 208.4 ms | **10.9x** |
| test-md-01.md | 916 | 87.7 ms | 1441.1 ms | **16.4x** |

### 为什么 Incremark 如此出色

1. **增量解析 O(n)**：每次 append 只处理新内容
2. **线性扩展**：优势随文档大小增长
3. **流式优化**：微秒级的 chunk 处理
4. **功能丰富**：支持脚注、数学公式、容器，且不牺牲速度

### 最佳使用场景

✅ **Incremark 最适合：**

* AI 聊天流式输出（Claude、ChatGPT 等）
* 实时 Markdown 编辑器
* 大文档的增量渲染
* 100k+ token 的长对话
* 需要脚注、数学公式或自定义容器的内容

⚠️ **以下场景可考虑其他方案：**

* 一次性静态 Markdown 渲染
* 极小文件（<500 字符）

---

---
url: /zh/advanced/architecture.md
---
# 架构原理

本文档解释 Incremark 的内部架构，帮助你理解库是如何实现高性能流式 Markdown 渲染的。

## 整体架构

```
┌─────────────────────────────────────────────────────────────────┐
│                      IncremarkContent                           │
│  (声明式组件，处理 content/stream 输入)                          │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                       useIncremark                              │
│  (状态管理，响应式封装，打字机协调)                               │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      IncremarkParser                            │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              双引擎 AST 构建器                            │   │
│  │  ┌──────────────────┐    ┌──────────────────┐           │   │
│  │  │  MarkedAstBuilder│    │MicromarkAstBuilder│          │   │
│  │  │  (默认，极速)     │    │ (稳定，严格)      │           │   │
│  │  └──────────────────┘    └──────────────────┘           │   │
│  └─────────────────────────────────────────────────────────┘   │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐       │
│  │    边界       │  │    定义       │  │    脚注       │       │
│  │   检测器      │  │   管理器      │  │   管理器      │       │
│  └───────────────┘  └───────────────┘  └───────────────┘       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                     BlockTransformer                            │
│  (打字机效果，字符级增量渲染)                                     │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐       │
│  │    插件       │  │    Chunk      │  │   TextChunk   │       │
│  │    系统       │  │    动画       │  │    追踪       │       │
│  └───────────────┘  └───────────────┘  └───────────────┘       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                        渲染器                                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │     Vue      │  │    React     │  │    Svelte    │          │
│  │    组件库     │  │    组件库     │  │    组件库    │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
```

## 双引擎架构

Incremark 支持两种解析引擎，通过注入不同的 AstBuilder 实现切换（支持 tree-shaking）：

### MarkedAstBuilder（默认）

`marked` 引擎针对流式性能进行了优化：

* **速度**：极速的词法分析，非常适合实时 AI 聊天
* **扩展**：自定义扩展支持脚注、数学公式、容器、内联 HTML
* **权衡**：CommonMark 兼容性略低

```ts
// 内部实现: packages/core/src/parser/ast/MarkedAstBuildter.ts
class MarkedAstBuilder implements IAstBuilder {
  // 自定义 marked 扩展
  private extensions = [
    createFootnoteDefinitionExtension(),
    createBlockMathExtension(),
    createInlineMathExtension(),
    createContainerExtension(),
    createInlineHtmlExtension()
  ]
}
```

### MicromarkAstBuilder

`micromark` 引擎优先考虑正确性和可扩展性：

* **兼容性**：严格遵循 CommonMark 规范
* **生态**：完整的 micromark/mdast 插件生态
* **权衡**：解析开销略高

```ts
// 内部实现: packages/core/src/parser/ast/MicromarkAstBuilder.ts
class MicromarkAstBuilder implements IAstBuilder {
  // 使用 mdast-util-from-markdown 配合 micromark 扩展
}
```

### 引擎选择

两个引擎产生相同的 mdast 输出，确保渲染一致性：

```ts
// 默认使用 marked（极速模式）
const parser = new IncremarkParser({ gfm: true, math: true })

// 使用 micromark（需要单独导入）
import { MicromarkAstBuilder } from '@incremark/core/engines/micromark'
const parser = new IncremarkParser({
  astBuilder: MicromarkAstBuilder,
  gfm: true,
  math: true
})
```

## 核心组件

### IncremarkParser

管理增量解析流程的核心协调器：

| 组件 | 职责 |
|------|------|
| **BoundaryDetector** | 识别稳定边界（空行、新标题）以提交已完成的块 |
| **AstBuilder** | 使用选定引擎从 markdown 文本构建 mdast 节点 |
| **DefinitionManager** | 跟踪文档中的链接/图片定义 |
| **FootnoteManager** | 管理脚注定义和引用 |

### BlockTransformer

处理打字机动画层：

| 组件 | 职责 |
|------|------|
| **Plugins System** | 可扩展的插件架构，支持自定义行为 |
| **Chunk Animation** | 管理待动画的文本块队列 |
| **TextChunk Tracking** | 追踪哪些字符已经"播放"，实现平滑动画 |

### 渲染器

框架特定的渲染组件：

* **Vue**: `@incremark/vue` - 使用 Vue 3.5 Composition API
* **React**: `@incremark/react` - 使用 React 18 hooks
* **Svelte**: `@incremark/svelte` - 使用 Svelte 5 runes

所有渲染器共享相同的核心逻辑，产生相同的 DOM 输出。

## 数据流

```mermaid
sequenceDiagram
    participant App as 应用
    participant IC as IncremarkContent
    participant UI as useIncremark
    participant P as Parser
    participant BT as BlockTransformer
    participant R as Renderer

    App->>IC: content += chunk
    IC->>UI: append(chunk)
    UI->>P: parse(markdown)
    
    Note over P: 边界检测
    P->>P: 查找稳定边界
    P->>P: 缓存已完成块
    P->>P: 仅重新解析待处理块
    
    P-->>UI: blocks[]
    UI->>BT: transform(blocks)
    
    Note over BT: 动画处理
    BT->>BT: 与前一状态 diff
    BT->>BT: 为新文本创建 TextChunk
    BT->>BT: 加入打字机效果队列
    
    BT-->>UI: animatedBlocks[]
    UI->>R: render(animatedBlocks)
    R->>R: 选择性 DOM 更新
```

## 性能优化

### 1. 增量行解析

仅解析新行；已完成的块被缓存：

```ts
// 简化概念
if (line.isNewlyAdded) {
  parse(line)
} else if (block.isCompleted) {
  return cachedAST[block.id]
}
```

### 2. 稳定块 ID

每个块获得一个稳定的 ID，实现高效的 React/Vue 协调：

```ts
interface Block {
  id: string      // 跨更新保持稳定
  node: RootContent
  status: 'pending' | 'completed'
}
```

### 3. AST 增量追加

新节点被追加到现有树中，无需重建：

```ts
// 不是: root = parse(entireMarkdown)
// 而是:
existingRoot.children.push(...newNodes)
```

### 4. 上下文缓存

解析器状态在 chunk 之间保留，实现高效恢复：

```ts
interface ParserContext {
  inFencedCode: boolean
  inContainer: boolean
  listStack: ListInfo[]
  blockquoteDepth: number
}
```

## 扩展点

Incremark 提供多个扩展点：

| 层级 | 扩展类型 | 示例 |
|------|---------|------|
| **解析器** | micromark 扩展 | 自定义语法 |
| **解析器** | mdast 扩展 | 自定义 AST 节点 |
| **解析器** | marked 转换器 | 自定义 token 处理 |
| **渲染器** | 自定义组件 | 替换标题渲染 |
| **渲染器** | 自定义代码块 | Echarts, Mermaid |
| **渲染器** | 自定义容器 | Warning, Info 框 |

详细文档请参阅[扩展功能](/zh/advanced/extensions)。

---

---
url: /zh/guide/concepts.md
---
# 核心概念

理解 Incremark 的工作原理，有助于更好地构建高性能、无闪烁的 AI 对话应用。

## 增量解析流程

传统的 Markdown 解析器（如 `marked` 或 `markdown-it`）是为静态文档设计的。在流式场景下，它们每接收到一个新的字符，都必须从头重新解析整个文档。

**Incremark** 采用了完全不同的“增量解析”策略：

```mermaid
graph TD
    Stream["Markdown 输入流"] --> Buffer["行缓冲区 (Line Buffer)"]
    Buffer --> Boundary["边界检测 (Boundary Detection)"]
    
    subgraph Engine ["增量引擎"]
        Boundary -- "检测到稳定边界" --> Completed["已完成块 (Completed)"]
        Boundary -- "处于不稳定区域" --> Pending["待处理块 (Pending)"]
    end
    
    Completed --> Cache["AST 缓存 (Mdast)"]
    Pending --> ReParse["局部重新解析 (仅解析当前块)"]
    
    Cache --> FinalAST["完整 AST (Root)"]
    ReParse --> FinalAST
    
    FinalAST --> Transformer["BlockTransformer (动画处理)"]
```

## Block 生命周期

在 Incremark 中，每一个顶级元素（标题、段落、代码块等）都是一个独立的 **Block**。它们经历了从“不确定”到“稳定”的生命周期：

| 状态 | 说明 | 处理策略 |
| :--- | :--- | :--- |
| **Pending** | 正在接收中，内容和类型随时可能改变 | 每次有新内容输入时，仅针对该 Block 所在的文本片段进行微型解析。 |
| **Completed** | 已确认完成，后续输入不会再影响该块 | **持久化缓存**。除非流被重置，否则不再参与解析、不再重新渲染。 |

> \[!TIP]
> **为什么需要 Pending 状态？**
> 在 Markdown 中，前缀决定了类型。例如输入 `#` 时，它可能是个标题，也可能只是文本。只有当接收到空格或换行时，其类型才真正确定。

## 边界检测规则

Incremark 使用启发式规则来判断一个 Block 何时可以从 `Pending` 转换为 `Completed`：

### 1. 简单块边界

* **空行**：段落的自然结束。
* **新标题/分隔线**：新块的出现意味着前一个非容器块已结束。

### 2. 围栏块边界 (Fenced Blocks)

* **代码块 (\`\`\`)**：必须检测到匹配的结束围栏。在结束围栏出现前，整个代码块都处于 `Pending` 状态。
* **自定义容器 (:::)**：同上，支持嵌套检测。

### 3. 嵌套块边界 (Nested Blocks)

* **列表与引用**：解析器会持续跟踪当前的缩进级别和引用深度。当新的一行缩进回退或引用标记消失时，判定前块结束。

## 上下文跟踪 (Context)

为了在流式过程中准确识别边界，解析器维护了一个轻量级的状态机：

```ts
interface BlockContext {
  inFencedCode: boolean;     // 正在处理代码块
  inContainer: boolean;      // 正在处理自定义容器
  listStack: ListInfo[];     // 追踪嵌套列表状态
  blockquoteDepth: number;   // 追踪引用嵌套深度
}
```

## 性能分析

得益于增量机制，Incremark 的性能表现与文档总长度几乎无关，而仅与当前更新的 Chunk 大小线性相关。

| 维度 | 传统全量解析 | Incremark 增量解析 |
| :--- | :--- | :--- |
| **单次处理复杂度** | O(N) | **O(K)** |
| **总解析复杂度** | O(N²) | **O(N)** |
| **内存开销** | 高 (反复创建全量对象) | **低 (增量复用 AST 节点)** |
| **UI 响应性** | 随字数增加产生肉眼可见的卡顿 | **始终保持 60fps 丝滑效果** |

*注：N 为文档总长度，K 为单次 Chunk 长度。*

## 打字机效果 (BlockTransformer)

在解析出 AST 之后，`BlockTransformer` 充当了渲染之前的过滤层。它负责将解析出的“瞬间结果”转化为“渐进过程”：

1. **节点追踪**：它记录了哪些字符已经“播放”过。
2. **TextChunk 包装**：将新增的文本节点包装为 `TextChunk`，由渲染层实现淡入动画。
3. **智能跳过**：如果用户要求立即显示，或者是非文本节点（如图片），它可以策略性地跳过动画。

---

---
url: /zh/features/footnotes.md
---
# 脚注

Incremark 开箱即支持 GFM 脚注。

## 用法

在配置中启用 `gfm` 选项。

```markdown
这是一个脚注引用[^1]。

[^1]: 这是脚注定义。
```

## 配置

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent } from '@incremark/vue'
</script>

<template>
  <IncremarkContent
    :content="content"
    :incremark-options="{ gfm: true }"
  />
</template>
```

```tsx [React]
import { IncremarkContent } from '@incremark/react'

<IncremarkContent
  content={content}
  incremarkOptions={{ gfm: true }}
/>
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent } from '@incremark/svelte'
</script>

<IncremarkContent {content} incremarkOptions={{ gfm: true }} />
```

:::

## 渲染

脚注会自动收集并渲染在内容底部。您可以使用 CSS 自定义外观，或通过覆盖 `footnoteDefinition` 组件来自定义。

---

---
url: /zh/features/auto-scroll.md
---
# 自动滚动

## 使用 AutoScrollContainer

::: code-group

```vue [Vue]
<script setup>
import { ref } from 'vue'
import { IncremarkContent, AutoScrollContainer } from '@incremark/vue'

const content = ref('')
const isFinished = ref(false)
const scrollRef = ref()
</script>

<template>
  <AutoScrollContainer ref="scrollRef" :enabled="true" class="h-[500px]">
    <IncremarkContent :content="content" :is-finished="isFinished" />
  </AutoScrollContainer>
</template>
```

```tsx [React]
import { useRef } from 'react'
import { IncremarkContent, AutoScrollContainer } from '@incremark/react'

function App() {
  const scrollRef = useRef(null)

  return (
    <AutoScrollContainer ref={scrollRef} enabled className="h-[500px]">
      <IncremarkContent content={content} isFinished={isFinished} />
    </AutoScrollContainer>
  )
}
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent, AutoScrollContainer } from '@incremark/svelte'

  let content = $state('')
  let isFinished = $state(false)
</script>

<AutoScrollContainer enabled class="h-[500px]">
  <IncremarkContent {content} {isFinished} />
</AutoScrollContainer>
```

```tsx [Solid]
import { createSignal } from 'solid-js'
import { IncremarkContent, AutoScrollContainer } from '@incremark/solid'

function App() {
  const [content, setContent] = createSignal('')
  const [isFinished, setIsFinished] = createSignal(false)

  return (
    <AutoScrollContainer enabled class="h-[500px]">
      <IncremarkContent content={content()} isFinished={isFinished()} />
    </AutoScrollContainer>
  )
}
```

:::

## Props

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `enabled` | `boolean` | `true` |启用自动滚动 |
| `threshold` | `number` | `50` | 底部阈值（像素） |
| `behavior` | `ScrollBehavior` | `'instant'` | 滚动行为 |

## 暴露的方法

| 方法 | 说明 |
|---|---|
| `scrollToBottom()` | 强制滚动到底部 |
| `isUserScrolledUp()` | 用户是否手动向上滚动 |

## 行为说明

* 内容更新时自动滚动到底部。
* 用户向上滚动时暂停自动滚动。
* 用户滚动回底部时恢复自动滚动。

---

---
url: /zh/features/custom-codeblocks.md
---
# 自定义代码块

## 概述

Incremark 为代码块自定义提供了分层架构：

1. **customCodeBlocks**: 语言特定的自定义组件（最高优先级）
2. **内置 Mermaid**: 自动的 Mermaid 图表支持
3. **components\['code']**: 自定义默认代码渲染
4. **默认**: 使用 Shiki 的内置语法高亮

## 自定义代码块渲染

适用于需要特殊渲染的场景，如 echarts、自定义图表等。

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent } from '@incremark/vue'
import EchartsBlock from './EchartsBlock.vue'
import PlantUMLBlock from './PlantUMLBlock.vue'

const customCodeBlocks = {
  echarts: EchartsBlock,
  plantuml: PlantUMLBlock
}

// 配置：是否在 pending 状态就开始渲染
const codeBlockConfigs = {
  echarts: { takeOver: true }  // 即使在 pending 状态也渲染
}
</script>

<template>
  <IncremarkContent
    :content="content"
    :custom-code-blocks="customCodeBlocks"
    :code-block-configs="codeBlockConfigs"
  />
</template>
```

```tsx [React]
import { IncremarkContent } from '@incremark/react'

function EchartsBlock({ codeStr, lang, completed, takeOver }) {
  // codeStr 是代码内容
  // lang 是语言标识符
  // completed 表示代码块是否完成
  return <div className="echarts">{codeStr}</div>
}

const customCodeBlocks = {
  echarts: EchartsBlock
}

<IncremarkContent
  content={content}
  customCodeBlocks={customCodeBlocks}
/>
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent } from '@incremark/svelte'
  import EchartsBlock from './EchartsBlock.svelte'

  const customCodeBlocks = {
    echarts: EchartsBlock
  }
</script>

<IncremarkContent {content} {customCodeBlocks} />
```

```tsx [Solid]
import { IncremarkContent } from '@incremark/solid'

function EchartsBlock(props: {
  codeStr: string
  lang: string
  completed: boolean
  takeOver: boolean
}) {
  return <div class="echarts">{props.codeStr}</div>
}

const customCodeBlocks = {
  echarts: EchartsBlock
}

<IncremarkContent content={content()} customCodeBlocks={customCodeBlocks} />
```

:::

## 自定义代码块 Props

创建自定义代码块组件时，你的组件将接收以下 props：

| Prop | 类型 | 说明 |
|---|---|---|
| `codeStr` | `string` | 代码内容 |
| `lang` | `string` | 语言标识符 |
| `completed` | `boolean` | 代码块是否完成 |
| `takeOver` | `boolean` | 是否启用 takeOver 模式 |

## codeBlockConfigs

| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `takeOver` | `boolean` | `false` | 是否在 pending 状态接管渲染 |

## 内置 Mermaid 支持

::: tip
Mermaid 图表开箱即用！无需任何配置。
:::

Incremark 自动渲染 Mermaid 图表，具备以下特性：

* 流式输入时的防抖渲染
* 预览/源码切换
* 复制功能
* 默认深色主题

```markdown
\`\`\`mermaid
graph TD
    A[开始] --> B{能用吗?}
    B -->|是| C[太棒了!]
    B -->|否| D[调试]
    D --> A
\`\`\`
```

如果你想覆盖内置的 Mermaid 渲染，使用 `customCodeBlocks`：

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent } from '@incremark/vue'
import MyMermaidBlock from './MyMermaidBlock.vue'

const customCodeBlocks = {
  mermaid: MyMermaidBlock  // 覆盖内置 Mermaid
}
</script>

<template>
  <IncremarkContent
    :content="content"
    :custom-code-blocks="customCodeBlocks"
  />
</template>
```

:::

## 与 components\['code'] 的对比

| 特性 | customCodeBlocks | components\['code'] |
|---|---|---|
| 作用范围 | 特定语言 | 所有代码块（作为回退） |
| 优先级 | 最高 | 低于 customCodeBlocks 和 Mermaid |
| 使用场景 | 特殊渲染（echarts、图表） | 自定义语法高亮主题 |
| Props | `codeStr`, `lang`, `completed`, `takeOver` | `node`, `theme`, `fallbackTheme`, `disableHighlight` |

更多关于 `components['code']` 的详情请参见[自定义组件](/zh/features/custom-components)。

---

---
url: /zh/features/custom-containers.md
---
# 自定义容器

## Markdown 语法

```markdown
::: warning
这是一个警告
:::

::: info 标题
这是一个信息框
:::
```

## 定义容器组件

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent } from '@incremark/vue'
import WarningContainer from './WarningContainer.vue'
import InfoContainer from './InfoContainer.vue'
-
const customContainers = {
  warning: WarningContainer,
  info: InfoContainer
}
</script>

<template>
  <IncremarkContent
    :content="content"
    :incremark-options="{ containers: true }"
    :custom-containers="customContainers"
  />
</template>
```

```tsx [React]
import { IncremarkContent } from '@incremark/react'

function WarningContainer({ node, children }) {
  return (
    <div className="warning-box">
      <div className="warning-title">{node.title || 'Warning'}</div>
      <div className="warning-content">{children}</div>
    </div>
  )
}

const customContainers = {
  warning: WarningContainer
}

<IncremarkContent
  content={content}
  incremarkOptions={{ containers: true }}
  customContainers={customContainers}
/>
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent } from '@incremark/svelte'
  import WarningContainer from './WarningContainer.svelte'

  const customContainers = {
    warning: WarningContainer
  }
</script>

<IncremarkContent
  {content}
  incremarkOptions={{ containers: true }}
  {customContainers}
/>
```

```tsx [Solid]
import { IncremarkContent } from '@incremark/solid'

function WarningContainer(props: { node: any; children: any }) {
  return (
    <div class="warning-box">
      <div class="warning-title">{props.node.title || 'Warning'}</div>
      <div class="warning-content">{props.children}</div>
    </div>
  )
}

const customContainers = {
  warning: WarningContainer
}

<IncremarkContent
  content={content()}
  incremarkOptions={{ containers: true }}
  customContainers={customContainers}
/>
```

:::

## 容器组件 Props

| 属性 | 类型 | 说明 |
|---|---|---|
| `node` | `ContainerNode` | 容器节点 |
| `node.name` | `string` | 容器名称 (warning, info 等) |
| `node.title` | `string?` | 容器标题 |
| `children` | - | 容器内容 |

---

---
url: /zh/examples/custom-stream.md
---
# 自定义流集成

解析原始的标准 `Response` 流。

## 示例

```ts
import { IncremarkContent } from '@incremark/react'

function App() {
  const [stream, setStream] = useState(null)

  function start() {
    async function* fetchStream() {
      const response = await fetch('/api/stream')
      const reader = response.body.getReader()
      const decoder = new TextDecoder()

      while (true) {
        const { done, value } = await reader.read()
        if (done) break
        yield decoder.decode(value, { stream: true })
      }
    }
    
    setStream(() => fetchStream)
  }

  return (
    <>
      <button onClick={start}>开始</button>
      <IncremarkContent stream={stream} />
    </>
  )
}
```

---

---
url: /zh/features/custom-components.md
---
# 自定义组件

## 自定义节点渲染

::: code-group

```vue [Vue]
<script setup>
import { h } from 'vue'
import { IncremarkContent } from '@incremark/vue'

const CustomHeading = {
  props: ['node'],
  setup(props) {
    const level = props.node.depth
    return () => h(`h${level}`, { class: 'my-heading' }, props.node.children)
  }
}

const components = {
  heading: CustomHeading
}
</script>

<template>
  <IncremarkContent :content="content" :components="components" />
</template>
```

```tsx [React]
import { IncremarkContent } from '@incremark/react'

function CustomHeading({ node, children }) {
  const Tag = `h${node.depth}` as keyof JSX.IntrinsicElements
  return <Tag className="my-heading">{children}</Tag>
}

const components = {
  heading: CustomHeading
}

<IncremarkContent content={content} components={components} />
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent } from '@incremark/svelte'
  import CustomHeading from './CustomHeading.svelte'

  const components = {
    heading: CustomHeading
  }
</script>

<IncremarkContent {content} {components} />
```

```tsx [Solid]
import { IncremarkContent } from '@incremark/solid'
import CustomHeading from './CustomHeading'

const components = {
  heading: CustomHeading
}

<IncremarkContent content={content()} components={components} />
```

:::

## 组件类型

| 类型 | 节点 |
|---|---|
| `heading` | 标题 h1-h6 |
| `paragraph` | 段落 |
| `code` | 代码块（仅默认渲染） |
| `list` | 列表 |
| `listItem` | 列表项 |
| `table` | 表格 |
| `blockquote` | 引用 |
| `thematicBreak` | 分隔线 |
| `image` | 图片 |
| `link` | 链接 |
| `inlineCode` | 行内代码 |

## 代码组件行为

::: tip 重要提示
当自定义 `code` 组件时，它只会替换**默认的代码块渲染**。内置的 Mermaid 支持和 `customCodeBlocks` 逻辑会被保留。
:::

代码块渲染遵循以下优先级：

1. **customCodeBlocks**: 语言特定的自定义组件（如 `echarts`、`mermaid`）
2. **内置 Mermaid**: 自动的 Mermaid 图表渲染
3. **components\['code']**: 自定义的默认代码块（如果提供）
4. **默认**: 使用 Shiki 的内置语法高亮

这意味着：

* 如果你设置 `components: { code: MyCodeBlock }`，它只影响普通代码块
* Mermaid 图表仍然会使用内置的 Mermaid 渲染器
* `customCodeBlocks` 配置具有更高的优先级

::: code-group

```vue [Vue]
<script setup>
import { IncremarkContent } from '@incremark/vue'
import MyCodeBlock from './MyCodeBlock.vue'

// 这只会替换默认的代码渲染
// Mermaid 和 customCodeBlocks 不受影响
const components = {
  code: MyCodeBlock
}
</script>

<template>
  <IncremarkContent :content="content" :components="components" />
</template>
```

```tsx [React]
import { IncremarkContent } from '@incremark/react'

function MyCodeBlock({ node }) {
  return (
    <pre className="my-code">
      <code>{node.value}</code>
    </pre>
  )
}

const components = {
  code: MyCodeBlock
}

<IncremarkContent content={content} components={components} />
```

```svelte [Svelte]
<script lang="ts">
  import { IncremarkContent } from '@incremark/svelte'
  import MyCodeBlock from './MyCodeBlock.svelte'

  const components = {
    code: MyCodeBlock
  }
</script>

<IncremarkContent {content} {components} />
```

:::

### 自定义代码组件 Props

创建自定义代码组件时，你的组件将接收以下 props：

| Prop | 类型 | 说明 |
|---|---|---|
| `node` | `Code` | 来自 mdast 的代码节点 |
| `theme` | `string` | Shiki 主题名称 |
| `fallbackTheme` | `string` | 加载失败时的回退主题 |
| `disableHighlight` | `boolean` | 是否禁用语法高亮 |

`node` 对象包含：

* `node.value`: 代码内容字符串
* `node.lang`: 语言标识符（如 `'typescript'`、`'python'`）
* `node.meta`: 语言标识符后的可选元数据