### Run React Example

Source: https://github.com/marwanbelike/incremark/blob/main/README.en.md

Execute the React example application.

```bash
# Run React example
pnpm example:react
```

--------------------------------

### Run Vue Example

Source: https://github.com/marwanbelike/incremark/blob/main/README.en.md

Execute the Vue example application.

```bash
# Run Vue example
pnpm example:vue
```

--------------------------------

### Installation

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/getting-started.md

Install Incremark core, framework-specific packages, and the optional theme.

```bash
pnpm add @incremark/core @incremark/vue @incremark/theme
npm install @incremark/core @incremark/vue @incremark/theme
yarn add @incremark/core @incremark/vue @incremark/theme
```

```bash
pnpm add @incremark/core @incremark/react @incremark/theme
```

```bash
pnpm add @incremark/core @incremark/svelte @incremark/theme
```

--------------------------------

### Install @incremark/devtools

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/devtools.md

Install the package using pnpm.

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

--------------------------------

### Install Project Dependencies

Source: https://github.com/marwanbelike/incremark/blob/main/README.en.md

Install all project dependencies using pnpm.

```bash
# Install dependencies
pnpm install
```

--------------------------------

### Install @incremark/react

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/react.md

Install the React integration package using pnpm.

```bash
pnpm add @incremark/react
```

--------------------------------

### Start Documentation Server

Source: https://github.com/marwanbelike/incremark/blob/main/README.en.md

Build and serve the project documentation.

```bash
# Start documentation
pnpm docs
```

--------------------------------

### Vue Quick Start with Typewriter Effect

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/typewriter.md

Integrate the typewriter effect in a Vue application by passing typewriter configuration to useIncremark. This example shows basic setup and control buttons.

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

const { blocks, append, finalize, reset, typewriter } = useIncremark({
  gfm: true,
  typewriter: {
    enabled: true,
    charsPerTick: [1, 3],  // Random 1-3 characters per tick
    tickInterval: 30,       // 30ms interval
    effect: 'typing',       // 'none' | 'fade-in' | 'typing'
    cursor: '|'             // Cursor character
  }
})
</script>

<template>
  <div :class="['content', `effect-${typewriter.effect.value}`]">
    <!-- blocks already includes typewriter effect! -->
    <Incremark :blocks="blocks" />
  </div>
  
  <!-- Control buttons -->
  <button v-if="typewriter.isProcessing.value" @click="typewriter.skip">
    Skip
  </button>
  <button v-if="typewriter.isPaused.value" @click="typewriter.resume">
    Resume
  </button>
</template>
```

--------------------------------

### Install @incremark/core

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/core.md

Install the core Incremark library using pnpm.

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

--------------------------------

### Install @incremark/svelte

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/svelte.md

Install the core and Svelte packages for Incremark.

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

--------------------------------

### Run Development Server

Source: https://github.com/marwanbelike/incremark/blob/main/README.en.md

Start the development server for the project.

```bash
# Start development
pnpm dev
```

--------------------------------

### Install Incremark Core, Svelte, and Theme

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/getting-started.md

Install the necessary Incremark packages for Svelte.

```bash
pnpm add @incremark/core @incremark/svelte @incremark/theme
```

--------------------------------

### Install Math Formula Extensions

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/extensions.md

Install the necessary packages for math formula support: `micromark-extension-math`, `mdast-util-math`, and `katex` for rendering.

```bash
pnpm add micromark-extension-math mdast-util-math katex
```

--------------------------------

### Install @incremark/theme

Source: https://github.com/marwanbelike/incremark/blob/main/packages/theme/README.en.md

Install the Incremark theme package using pnpm.

```bash
pnpm add @incremark/theme
```

--------------------------------

### Install Incremark Core, React, and Theme

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/getting-started.md

Install the necessary Incremark packages for React.js.

```bash
pnpm add @incremark/core @incremark/react @incremark/theme
```

--------------------------------

### Svelte Quick Start with Typewriter Effect

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/typewriter.md

Set up the typewriter effect in a Svelte component by configuring the useIncremark hook. This example includes the script and template for integration.

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

  const { blocks, append, finalize, reset, typewriter } = useIncremark({
    gfm: true,
    typewriter: {
      enabled: true,
      charsPerTick: [1, 3],
      tickInterval: 30,
      effect: 'typing',
      cursor: '|'
    }
  })
</script>

<div class="content effect-{$typewriter.effect}">
  <!-- blocks already includes typewriter effect! -->
  <Incremark {blocks} />
  
  {#if $typewriter.isProcessing}
    <button on:click={() => typewriter.skip()}>Skip</button>
  {/if}
  {#if $typewriter.isPaused}
    <button on:click={() => typewriter.resume()}>Resume</button>
  {/if}
</div>
```

--------------------------------

### Install @incremark/vue

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/vue.md

Install the Vue 3 integration package using pnpm.

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

--------------------------------

### Custom Container Syntax Examples

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/extensions.md

Demonstrates the syntax for custom containers, including basic usage and containers with titles.

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

:::info{title="Tip"}
Info box with title
:::
```

--------------------------------

### Run Incremark Benchmark

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/benchmark.md

Clone the repository, install dependencies using pnpm, and then run the benchmark command.

```bash
git clone https://github.com/kingshuaishuai/incremark.git
cd incremark
pnpm install
pnpm benchmark
```

--------------------------------

### Install Directive Extensions

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/extensions.md

Install the necessary packages for custom directive support: `micromark-extension-directive` and `mdast-util-directive`.

```bash
pnpm add micromark-extension-directive mdast-util-directive
```

--------------------------------

### Math Formula Syntax Examples

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/extensions.md

Demonstrates the syntax for inline and block math formulas using KaTeX.

```markdown
Inline formula: $E = mc^2$

Block formula:
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$
```

--------------------------------

### Custom Tip Container Example

Source: https://github.com/marwanbelike/incremark/blob/main/examples/react/src/locales/sample-en.md

Illustrates a custom 'tip' container, ideal for sharing helpful tips or best practices.

```markdown
:::tip
This is a **tip** container. Great for sharing useful tips and best practices!
:::
```

--------------------------------

### MDAST AST Structure Example

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/concepts.md

Illustrates the basic structure of the Markdown Abstract Syntax Tree (MDAST) generated by Incremark, starting with a 'root' node.

```typescript
interface Root {
  type: 'root'
  children: RootContent[]
}

// Block-level nodes
type RootContent = 
  | Heading 
  | Paragraph 
  | Code 
  | List 
  | Blockquote 
  | Table 
  | ThematicBreak
  | ...
```

--------------------------------

### Install Incremark Packages

Source: https://github.com/marwanbelike/incremark/blob/main/docs/index.md

Install the core Incremark library along with framework-specific integrations for Vue, React, or Svelte.

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

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

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

--------------------------------

### IncremarkHtmlElement Component Setup

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/vue.md

Provides an example of how to import and configure the IncremarkHtmlElement component for rendering HTML fragments within your Vue application.

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

const customComponents = {
  htmlElement: IncremarkHtmlElement
}
</script>
```

--------------------------------

### Complete Incremark Svelte Example

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/svelte.md

A comprehensive example demonstrating Incremark integration in Svelte, including typewriter effects, devtools, auto-scrolling, theming, and simulating an AI chat response.

```svelte
<script lang="ts">
  import { useIncremark, useDevTools, Incremark, AutoScrollContainer, ThemeProvider } from '@incremark/svelte'
  import '@incremark/svelte/style.css'

  const incremark = useIncremark({ 
    gfm: true,
    typewriter: {
      effect: 'fade-in',
      charsPerTick: [1, 3]
    }
  })
  const { blocks, append, finalize, reset, markdown, typewriter } = incremark

  useDevTools(incremark)

  let isStreaming = $state(false)

  async function simulateAI() {
    reset()
    isStreaming = true
    
    const response = await fetch('/api/chat', { method: 'POST' })
    const reader = response.body!.getReader()
    const decoder = new TextDecoder()
    
    while (true) {
      const { done, value } = await reader.read()
      if (done) break
      append(decoder.decode(value))
    }
    
    finalize()
    isStreaming = false
  }
</script>

<ThemeProvider theme="default">
  <div class="app effect-{$typewriter.effect}">
    <header>
      <button on:click={simulateAI} disabled={isStreaming}>
        {isStreaming ? 'Generating...' : 'Start Chat'}
      </button>
      <span>{$markdown.length} characters</span>
      
      {#if $typewriter.isProcessing}
        <button on:click={() => typewriter.skip()}>Skip</button>
      {/if}
    </header>
    
    <AutoScrollContainer class="content">
      <Incremark {incremark} />
    </AutoScrollContainer>
  </div>
</ThemeProvider>
```

--------------------------------

### Install Incremark React Integration

Source: https://github.com/marwanbelike/incremark/blob/main/README.en.md

Install the core Incremark parser and the React integration package using pnpm.

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

--------------------------------

### useBlockTransformer Example

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/react.md

An example demonstrating how to use useIncremark and useBlockTransformer together in a React component to implement a typewriter effect with adjustable speed and interval.

```tsx
import { useMemo, useState, useEffect } from 'react'
import { useIncremark, useBlockTransformer, Incremark, defaultPlugins } from '@incremark/react'

function App() {
  const { completedBlocks, append, finalize, reset: resetParser } = useIncremark()
  
  const [typewriterSpeed, setTypewriterSpeed] = useState(2)
  const [typewriterInterval, setTypewriterInterval] = useState(50)

  const sourceBlocks = useMemo(() => 
    completedBlocks.map(block => ({
      id: block.id,
      node: block.node,
      status: block.status
    })),
    [completedBlocks]
  )

  const { displayBlocks, isProcessing, skip, setOptions } = useBlockTransformer(sourceBlocks, {
    charsPerTick: typewriterSpeed,
    tickInterval: typewriterInterval,
    plugins: defaultPlugins
  })

  useEffect(() => {
    setOptions({ charsPerTick: typewriterSpeed, tickInterval: typewriterInterval })
  }, [typewriterSpeed, typewriterInterval, setOptions])

  const renderBlocks = useMemo(() => 
    displayBlocks.map(db => ({
      ...db,
      stableId: db.id,
      node: db.displayNode,
      status: db.isDisplayComplete ? 'completed' : 'pending'
    })),
    [displayBlocks]
  )

  return (
    <div>
      <Incremark blocks={renderBlocks} />
      {isProcessing && <button onClick={skip}>Skip</button>}
    </div>
  )
}
```

--------------------------------

### Install @incremark/svelte

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/svelte.md

Add the Svelte integration package to your project using pnpm.

```bash
pnpm add @incremark/svelte
```

--------------------------------

### Custom Warning Container Example

Source: https://github.com/marwanbelike/incremark/blob/main/examples/react/src/locales/sample-en.md

Demonstrates a custom 'warning' container. These are useful for highlighting important information or cautions.

```markdown
:::warning
This is a **warning** container. Use it to highlight important warnings or cautions to users.
:::
```

--------------------------------

### Install Incremark Core, Vue, and Theme

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/getting-started.md

Install the necessary Incremark packages for Vue.js using your preferred package manager.

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

```bash
npm install @incremark/core @incremark/vue @incremark/theme
```

```bash
yarn add @incremark/core @incremark/vue @incremark/theme
```

--------------------------------

### Install @incremark/core Package

Source: https://github.com/marwanbelike/incremark/blob/main/README.md

Use npm to install the core Incremark package. This is the primary package for the Markdown parser.

```bash
npm install @incremark/core
```

--------------------------------

### Install Incremark Vue Integration

Source: https://github.com/marwanbelike/incremark/blob/main/README.en.md

Install the core Incremark parser and the Vue integration package using pnpm.

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

--------------------------------

### Quick Start with Incremental Parsing

Source: https://github.com/marwanbelike/incremark/blob/main/packages/core/README.en.md

Initialize the parser with GFM enabled and simulate streaming input. Use getCompletedBlocks() and getAst() to retrieve parsing results.

```typescript
import { createIncremarkParser } from '@incremark/core'

const parser = createIncremarkParser({ gfm: true })

// Simulate streaming input
parser.append('# Hello\n')
parser.append('\nWorld')
parser.finalize()

// Get results
console.log(parser.getCompletedBlocks())
console.log(parser.getAst())
```

--------------------------------

### Complete Incremark Vue Example

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/vue.md

A comprehensive example demonstrating Incremark integration in Vue, including typewriter effects, auto-scroll, devtools, streaming API responses, and theming.

```vue
<script setup>
import { ref } from 'vue'
import { useIncremark, useDevTools, Incremark, AutoScrollContainer, ThemeProvider } from '@incremark/vue'
import '@incremark/theme/styles.css'

const incremark = useIncremark({
  gfm: true,
  typewriter: {
    effect: 'fade-in',
    charsPerTick: [1, 3]
  }
})
const { blocks, append, finalize, reset, markdown, typewriter } = incremark

useDevTools(incremark)

const isStreaming = ref(false)

async function simulateAI() {
  reset()
  isStreaming.value = true
  
  const response = await fetch('/api/chat', { method: 'POST' })
  const reader = response.body.getReader()
  const decoder = new TextDecoder()
  
  while (true) {
    const { done, value } = await reader.read()
    if (done) break
    append(decoder.decode(value))
  }
  
  finalize()
  isStreaming.value = false
}
</script>

<template>
  <ThemeProvider theme="default">
    <div :class="['app', `effect-${typewriter.effect.value}`]">
      <header>
        <button @click="simulateAI" :disabled="isStreaming">
          {{ isStreaming ? 'Generating...' : 'Start Chat' }}
        </button>
        <span>{{ markdown.length }} characters</span>
        
        <button v-if="typewriter.isProcessing.value" @click="typewriter.skip">
          Skip
        </button>
      </header>
      
      <AutoScrollContainer class="content">
        <Incremark :incremark="incremark" />
      </AutoScrollContainer>
    </div>
  </ThemeProvider>
</template>
```

--------------------------------

### Custom Info Container with Title Example

Source: https://github.com/marwanbelike/incremark/blob/main/examples/react/src/locales/sample-en.md

Shows a custom 'info' container with a specified title. This allows for more context-specific information display.

```markdown
:::info{title="Information"}
This is an **info** container with a custom title. Perfect for providing additional context or explanations.
:::
```

--------------------------------

### Multi-paragraph Custom Info Container Example

Source: https://github.com/marwanbelike/incremark/blob/main/examples/react/src/locales/sample-en.md

Demonstrates a multi-paragraph custom 'info' container, showing that it can include various Markdown elements like lists and inline code.

```markdown
:::info{title="Multi-paragraph Example"}
This is the first paragraph in the container.

This is the second paragraph. You can include:

- Lists
- **Bold text**
- *Italic text*
- Even `inline code`

All of these can be in the same container!
:::
```

--------------------------------

### Custom Code Component Example

Source: https://github.com/marwanbelike/incremark/blob/main/packages/vue/README.en.md

Example of using a custom component for code blocks within the Incremark component.

```vue
<script setup>
import { useIncremark, Incremark } from '@incremark/vue'
import MyCode from './MyCode.vue'

const { blocks } = useIncremark()
</script>

<template>
  <Incremark 
    :blocks="blocks" 
    :components="{ code: MyCode }"
  />
</template>
```

--------------------------------

### Complete Incremark Chat App Example

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/react.md

A comprehensive example demonstrating a chat application using Incremark with features like typewriter effects, streaming responses, dev tools, and theming. It includes state management for streaming and UI updates.

```tsx
import { useState, useCallback } from 'react'
import { useIncremark, useDevTools, Incremark, AutoScrollContainer, ThemeProvider } from '@incremark/react'
import '@incremark/theme/styles.css'

function ChatApp() {
  const incremark = useIncremark({
    gfm: true,
    typewriter: {
      effect: 'fade-in',
      charsPerTick: [1, 3]
    }
  })
  const { blocks, append, finalize, reset, markdown, typewriter } = incremark
  
  useDevTools(incremark)
  
  const [isStreaming, setIsStreaming] = useState(false)

  const handleChat = useCallback(async () => {
    reset()
    setIsStreaming(true)
    
    const response = await fetch('/api/chat', { method: 'POST' })
    const reader = response.body!.getReader()
    const decoder = new TextDecoder()
    
    while (true) {
      const { done, value } = await reader.read()
      if (done) break
      append(decoder.decode(value))
    }
    
    finalize()
    setIsStreaming(false)
  }, [append, finalize, reset])

  return (
    <ThemeProvider theme="default">
      <div className={`app effect-${typewriter.effect}`}>
        <header>
          <button onClick={handleChat} disabled={isStreaming}>
            {isStreaming ? 'Generating...' : 'Start Chat'}
          </button>
          <span>{markdown.length} characters</span>
          
          {typewriter.isProcessing && (
            <button onClick={typewriter.skip}>Skip</button>
          )}
        </header>
        
        <AutoScrollContainer className="content">
          <Incremark incremark={incremark} />
        </AutoScrollContainer>
      </div>
    </ThemeProvider>
  )
}

```

--------------------------------

### React Application Migration (v0.1.x)

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/migration-guide.md

Example of a React application using Incremark v0.1.x, demonstrating the previous approach with `useBlockTransformer` and separate style imports.

```tsx
import { useIncremark, useBlockTransformer, Incremark, defaultPlugins } from '@incremark/react'
import '@incremark/react/styles.css'

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

  const sourceBlocks = useMemo(() =>
    completedBlocks.map(b => ({ id: b.id, node: b.node, status: b.status })),
    [completedBlocks]
  )

  const { displayBlocks, isProcessing, skip } = useBlockTransformer(sourceBlocks, {
    charsPerTick: 2,
    tickInterval: 50,
    plugins: defaultPlugins
  })

  const renderBlocks = useMemo(() =>
    displayBlocks.map(db => ({
      ...db,
      stableId: db.id,
      node: db.displayNode,
      status: db.isDisplayComplete ? 'completed' : 'pending'
    })),
    [displayBlocks]
  )

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

--------------------------------

### Is Blockquote Start Function

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/core.md

Detects if a given line of text marks the beginning of a Markdown blockquote.

```typescript
function isBlockquoteStart(line: string): boolean
```

--------------------------------

### Add Math Formula Support in Vue

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/vue.md

Integrate math formula rendering by installing `micromark-extension-math` and `mdast-util-math`, then configuring `useIncremark` with the necessary extensions and CSS.

```bash
pnpm add micromark-extension-math mdast-util-math katex
```

```vue
<script setup>
import { useIncremark } from '@incremark/vue'
import { math } from 'micromark-extension-math'
import { mathFromMarkdown } from 'mdast-util-math'
import 'katex/dist/katex.min.css'

const { blocks } = useIncremark({
  extensions: [math()],
  mdastExtensions: [mathFromMarkdown()],
  typewriter: { effect: 'fade-in' }
})
</script>
```

--------------------------------

### Full Re-parse Strategy Example

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/compared.md

Illustrates the full re-parse approach where each new chunk triggers a complete re-parsing of all accumulated content. This is characteristic of libraries like ant-design-x and markstream-vue.

```text
Chunk 1: "# Hello"        → Parse entire content
Chunk 2: "# Hello\nWorld" → Parse entire content again
Chunk 3: "# Hello\nWorld\n\n- item" → Parse entire content again
```

--------------------------------

### Markdown with Footnotes

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/migration-guide.md

Example of Markdown syntax for creating footnotes using `[^label]` for references and `[^label]: content` for definitions.

```markdown
这是一段文字[^1]，还有另一段[^2]。

[^1]: 这是第一个脚注
[^2]: 这是第二个脚注
```

--------------------------------

### Vue Application Migration (v0.1.x)

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/migration-guide.md

Example of a Vue application using Incremark v0.1.x, showing the structure before migration, including the older style import path.

```vue
<script setup>
import { useIncremark, useBlockTransformer, Incremark, defaultPlugins } from '@incremark/vue'
</script>

<style>
@import '@incremark/vue/style.css';
</style>

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

--------------------------------

### Is List Item Start Function

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/core.md

Detects if a given line of text marks the beginning of a Markdown list item.

```typescript
function isListItemStart(line: string): boolean
```

--------------------------------

### Install Incremark Core, Vue, and Theme Packages

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/migration-guide.md

Use pnpm to add the necessary Incremark packages for Vue applications, including the core, Vue integration, and theme.

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

--------------------------------

### Svelte Integration with Incremark

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/getting-started.md

Integrate Incremark into a Svelte application. This example shows how to set up the Incremark parser, simulate streaming data, and display the results.

```svelte
<script lang="ts">
  import { useIncremark, Incremark } from '@incremark/svelte'
  import '@incremark/svelte/style.css'

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

  async function simulateStream() {
    reset()
    
    const text = '# Hello\n\nThis is **Incremark**!'
    const chunks = text.match(/.{1,5}/g) || []
    
    for (const chunk of chunks) {
      append(chunk)
      await new Promise(r => setTimeout(r, 50))
    }
    
    finalize()
  }
</script>

<button on:click={simulateStream}>Start</button>
<!-- Recommended: Pass incremark object -->
<Incremark {incremark} />
```

--------------------------------

### Markdown with Reference-Style Image and Link Definitions

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/migration-guide.md

Example of Markdown syntax for reference-style images and links, using `![alt text][id]` and `[id]: url "title"` for definitions.

```markdown
![图片][id]

[id]: https://example.com/image.png "图片标题"
```

--------------------------------

### React Integration with Incremark

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/getting-started.md

Integrate Incremark into a React application. This example demonstrates initializing the Incremark parser, simulating streaming, and rendering the output.

```tsx
import { useIncremark, Incremark } from '@incremark/react'
import '@incremark/theme/styles.css'

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

  async function simulateStream() {
    reset()
    
    const text = '# Hello\n\nThis is **Incremark**!'
    const chunks = text.match(/.{1,5}/g) || []
    
    for (const chunk of chunks) {
      append(chunk)
      await new Promise(r => setTimeout(r, 50))
    }
    
    finalize()
  }

  return (
    <>
      <button onClick={simulateStream}>Start</button>
      {/* Recommended: Pass incremark object */}
      <Incremark incremark={incremark} />
    </>
  )
}
```

--------------------------------

### Incremark Theming in Svelte

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/svelte.md

Shows how to apply a theme to Incremark components using the ThemeProvider. This example imports a dark theme and applies it to the Incremark component.

```svelte
<script lang="ts">
  import { useIncremark, Incremark, ThemeProvider } from '@incremark/svelte'
  import { darkTheme } from '@incremark/theme'
  
  const incremark = useIncremark()
</script>

<ThemeProvider theme="dark">
  <Incremark {incremark} />
</ThemeProvider>

```

--------------------------------

### GFM Task List Example

Source: https://github.com/marwanbelike/incremark/blob/main/examples/react/src/locales/sample-en.md

Shows a GitHub Flavored Markdown (GFM) task list. Incremark supports these for tracking progress or to-do items.

```markdown
- [x] Core parser
- [x] Vue 3 integration
- [x] React integration
- [x] Svelte 5 integration
- [x] Mermaid charts
- [x] LaTeX formulas
- [x] Custom containers
- [x] Custom code blocks
- [x] Typewriter effect
- [x] Theme system
```

--------------------------------

### Incremark with HTML Fragments in Svelte

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/svelte.md

Illustrates Incremark's capability to render HTML fragments directly within Markdown content. This example shows the basic setup required to enable this feature.

```svelte
<script lang="ts">
  import { useIncremark, Incremark } from '@incremark/svelte'
  
  const incremark = useIncremark()
  // Markdown with HTML:
  // <div class="custom">Hello</div>
</script>

<Incremark {incremark} />

```

--------------------------------

### Build Project

Source: https://github.com/marwanbelike/incremark/blob/main/README.en.md

Compile and package the project for distribution.

```bash
# Build
pnpm build
```

--------------------------------

### Incremental Parsing Strategy Example

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/compared.md

Demonstrates Incremark's incremental parsing strategy where completed blocks are cached and only the pending portion of new content is processed. This leads to better performance in streaming scenarios.

```text
Chunk 1: "# Hello"     → Parse → Block 1 (heading) ✓ Done
Chunk 2: "\n\nWorld"   → Parse → Block 2 (paragraph) ← Only this part
Chunk 3: "\n\n- item"  → Parse → Block 3 (list) ← Only this part
```

--------------------------------

### Theme Configuration and Application

Source: https://github.com/marwanbelike/incremark/blob/main/packages/theme/README.en.md

Demonstrates how to import and apply preset or custom themes to a DOM element using the `applyTheme` function.

```APIDOC
## applyTheme(element, config)

### Description
Applies a theme configuration to a specified DOM element. This function can use preset themes or a custom theme object.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **element** (HTMLElement) - Required - The DOM element to apply the theme to.
- **config** (ThemeConfig | themes) - Required - The theme configuration object or a preset theme.

### Request Example
```javascript
import { applyTheme, themes, type ThemeConfig } from '@incremark/theme'

const container = document.querySelector('.incremark')
if (container) {
  // Apply a preset theme
  applyTheme(container as HTMLElement, themes.dark)

  // Apply a custom theme
  const customTheme: ThemeConfig = {
    fontFamily: 'Georgia, serif',
    color: '#2c3e50',
    pendingBorderColor: '#e74c3c',
    codeBackground: '#1e1e1e'
  }
  applyTheme(container as HTMLElement, customTheme)
}
```

### Response
#### Success Response (200)
- None (The function modifies the DOM directly).

#### Response Example
- N/A
```

--------------------------------

### Import All Plugins

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/core.md

Import all available plugins, including those for code blocks, mermaid, and math which also display as whole.

```typescript
// All plugins: code blocks, mermaid, math also display as whole
import { allPlugins } from '@incremark/core'
```

--------------------------------

### Run Tests

Source: https://github.com/marwanbelike/incremark/blob/main/README.en.md

Execute the project's test suite.

```bash
# Run tests
pnpm test
```

--------------------------------

### Example Echarts Code Block Configuration

Source: https://github.com/marwanbelike/incremark/blob/main/examples/react/src/locales/sample-en.md

This is an example of a markdown code block with the 'echarts' language, containing JSON configuration for an Echarts chart.

```echarts
{
  "title": {
    "text": "Example Chart"
  },
  "xAxis": {
    "type": "category",
    "data": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
  },
  "yAxis": {
    "type": "value"
  },
  "series": [{
    "data": [120, 200, 150, 80, 70, 110, 130],
    "type": "bar"
  }]
}
```

--------------------------------

### Detect Fence Start Function

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/core.md

Detects the start of a code block fence in a given line of text. Returns the fence character, its length, and indentation, or null if no fence is detected.

```typescript
function detectFenceStart(line: string): { char: string; length: number; indent: number } | null
```

--------------------------------

### Custom Vue Container Component Example

Source: https://github.com/marwanbelike/incremark/blob/main/examples/vue/src/locales/sample-en.md

Create a custom container component in Vue that accepts 'name' and 'options' props and uses a slot for content. This example shows a 'warning' container structure.

```vue
<!-- CustomWarningContainer.vue -->
<script setup lang="ts">
defineProps({
  name: String,
  options: Object
})
</script>

<template>
  <div class="custom-warning-container">
    <div class="custom-warning-header">
      <span class="custom-warning-icon">⚠️</span>
      <span class="custom-warning-title">
        {{ options?.title || 'Warning' }}
      </span>
    </div>
    <div class="custom-warning-content">
      <slot />
    </div>
  </div>
</template>
```

--------------------------------

### Import Default Plugins

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/core.md

Import the default set of plugins, where images and breaks display immediately.

```typescript
// Default plugins: images and breaks display immediately, others participate in typewriter
import { defaultPlugins } from '@incremark/core'
```

--------------------------------

### Basic Incremark Usage in Svelte

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/svelte.md

Demonstrates the fundamental setup for Incremark in a Svelte component. Includes importing necessary functions and CSS, initializing Incremark with options, and rendering the Incremark component. It also shows how to handle streamed content.

```svelte
<script lang="ts">
  import { useIncremark, useDevTools, Incremark } from '@incremark/svelte'
  import '@incremark/svelte/style.css'

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

  useDevTools(incremark)

  async function handleStream(stream: ReadableStream) {
    reset()
    const reader = stream.getReader()
    const decoder = new TextDecoder()
    
    while (true) {
      const { done, value } = await reader.read()
      if (done) break
      append(decoder.decode(value))
    }
    
    finalize()
  }
</script>

<!-- Recommended: Pass incremark object -->
<Incremark {incremark} />

```

--------------------------------

### Using Plugins with BlockTransformer

Source: https://github.com/marwanbelike/incremark/blob/main/packages/vue/README.md

Demonstrates how to use default plugins or create custom plugins for the BlockTransformer in Incremark Vue.

```APIDOC
## Plugin System

BlockTransformer supports plugins to handle special types of blocks:

```ts
import {
  defaultPlugins,
  codeBlockPlugin,
  imagePlugin,
  mermaidPlugin,
  mathPlugin,
  thematicBreakPlugin,
  createPlugin
} from '@incremark/vue'

// Use default plugin set
const { displayBlocks } = useBlockTransformer(sourceBlocks, {
  plugins: defaultPlugins
})

// Or customize plugins
const myPlugin = createPlugin({
  name: 'my-plugin',
  match: (node) => node.type === 'myType',
  transform: (node) => ({ displayNode: node, isComplete: true })
})
```

**Built-in Plugins:**

| Plugin | Description |
|------|------|
| `codeBlockPlugin` | Display code blocks as a whole |
| `imagePlugin` | Display images as a whole |
| `mermaidPlugin` | Display Mermaid diagrams as a whole |
| `mathPlugin` | Display mathematical formulas as a whole |
| `thematicBreakPlugin` | Display thematic breaks as a whole |
```

--------------------------------

### Get Completed Blocks

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/core.md

Retrieve all blocks that have been completed by the parser.

```typescript
getCompletedBlocks(): ParsedBlock[]
```

--------------------------------

### Get Parser Buffer

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/core.md

Retrieve the current content buffer of the IncremarkParser.

```typescript
getBuffer(): string
```

--------------------------------

### Get Parser AST

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/core.md

Retrieve the current Abstract Syntax Tree (AST) generated by the parser.

```typescript
getAst(): Root
```

--------------------------------

### Enable DevTools for Vanilla JS

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/devtools.md

Use `createIncremarkParser` and `mountDevTools` to integrate developer tools in a vanilla JavaScript application.

```ts
import { createIncremarkParser } from '@incremark/core'
import { mountDevTools } from '@incremark/devtools'

const parser = createIncremarkParser({
  onChange: mountDevTools()
})
```

--------------------------------

### Mount DevTools with Options

Source: https://github.com/marwanbelike/incremark/blob/main/packages/devtools/README.en.md

Create and mount DevTools with custom options for initial state, position, and theme. The `mountDevTools` function returns an `onChange` callback.

```typescript
const callback = mountDevTools({
  open: false,
  position: 'bottom-right',
  theme: 'dark'
})

parser.setOnChange(callback)
```

--------------------------------

### AutoScrollContainer Component Usage

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/vue.md

Illustrates the usage of AutoScrollContainer for streaming content, with examples of enabling auto-scroll and setting a threshold.

```vue
<AutoScrollContainer 
  ref="scrollRef" 
  :enabled="true"
  :threshold="50"
  behavior="instant"
>
  <Incremark :blocks="blocks" />
</AutoScrollContainer>
```

--------------------------------

### ant-design-x Pipeline Overview

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/compared.md

Illustrates the data flow and components within the ant-design-x streaming Markdown rendering pipeline. It uses a `useTyping` hook for character-by-character input and a `useStreaming` hook to manage incomplete tokens before full parsing.

```mermaid
graph TD
    A[User Input (Streaming Markdown)] --> B(useTyping Hook);
    B --> C{Outputs text chunks with fade-in markers};
    C --> D(useStreaming Hook);
    D --> E{Regex detects incomplete tokens};
    D --> F{Caches incomplete parts, outputs only complete MD};
    D --> G{Incomplete tokens can be replaced with placeholder components};
    G --> H(Parser (marked.js));
    H --> I(Renderer (html-react-parser));
    I --> J(React DOM);
    F --> H
```

--------------------------------

### Initialize Typewriter Effect in Vue

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/typewriter.md

Start the typewriter effect disabled and then enable it. You can also update its options dynamically.

```vue
<script setup>
const { typewriter } = useIncremark({
  typewriter: { enabled: false }  // Start disabled
})

// Toggle enabled state
typewriter.enabled.value = true

// Update options
typewriter.setOptions({
  charsPerTick: [2, 5],
  tickInterval: 20,
  effect: 'fade-in'
})
</script>
```

--------------------------------

### Example ECharts Code Block Data

Source: https://github.com/marwanbelike/incremark/blob/main/examples/svelte/src/locales/sample-en.md

A JSON configuration for an ECharts chart, intended to be rendered by a custom code block component.

```echarts
{
  "title": {
    "text": "Example Chart"
  },
  "xAxis": {
    "type": "category",
    "data": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
  },
  "yAxis": {
    "type": "value"
  },
  "series": [{
    "data": [120, 200, 150, 80, 70, 110, 130],
    "type": "bar"
  }]
}

```

--------------------------------

### Basic Svelte Usage with Incremark

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/svelte.md

Set up the Incremark store and render markdown content in a Svelte component. Ensure the CSS is imported for basic styling.

```svelte
<script lang="ts">
  import { useIncremark, Incremark } from '@incremark/svelte'
  import '@incremark/svelte/style.css'

  const incremark = useIncremark({
    gfm: true
  })
  const { blocks, append, finalize, reset, markdown } = incremark
</script>

<div>
  <p>Received {$markdown.length} characters</p>
  <!-- Recommended: Pass incremark object -->
  <Incremark {incremark} />
</div>
```

--------------------------------

### parser.reset

Source: https://github.com/marwanbelike/incremark/blob/main/packages/core/README.en.md

Resets the parser's internal state, clearing the buffer and any parsed blocks. This is useful for starting a new parsing session.

```APIDOC
## parser.reset()

### Description
Reset state.
```

--------------------------------

### useIncremark(options)

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/getting-started.md

Hook to initialize Incremark parser. Returns state and control functions.

```APIDOC
## `useIncremark(options)`

Returns:

| Property | Type | Description |
|----------|------|-------------|
| `markdown` | `string` | Collected complete Markdown |
| `blocks` | `Block[]` | All blocks (with stable IDs, includes typewriter effect if enabled) |
| `completedBlocks` | `Block[]` | Completed blocks |
| `pendingBlocks` | `Block[]` | Pending blocks |
| `isFinalized` | `boolean` | Whether parsing is finalized |
| `append(chunk)` | `Function` | Append content |
| `finalize()` | `Function` | Complete parsing |
| `reset()` | `Function` | Reset state |
| `abort()` | `Function` | Abort parsing |
| `typewriter` | `TypewriterControls` | Typewriter controls (if enabled) |
```

--------------------------------

### Create BlockTransformer Instance

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/core.md

Instantiate the BlockTransformer with optional configuration options.

```typescript
new BlockTransformer(options?: TransformerOptions)
```

--------------------------------

### Initialize Typewriter Effect in React

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/typewriter.md

Initialize the typewriter effect in React, starting disabled. You can then toggle its enabled state and update options.

```tsx
const { typewriter } = useIncremark({
  typewriter: { enabled: false }
})

// Toggle enabled state
typewriter.setEnabled(true)

// Update options
typewriter.setOptions({
  charsPerTick: [2, 5],
  tickInterval: 20,
  effect: 'fade-in'
})
```

--------------------------------

### useIncremark Configuration Options

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/svelte.md

Configure the Incremark parser and enable/customize the typewriter effect with these options.

```typescript
interface UseIncremarkOptions {
  // Parser options
  gfm?: boolean              // Enable GFM
  containers?: boolean       // Enable ::: containers
  extensions?: Extension[]   // micromark extensions
  mdastExtensions?: Extension[]  // mdast extensions
  
  // Typewriter options (pass to enable)
  typewriter?: {
    enabled?: boolean              // Enable/disable (default: true)
    charsPerTick?: number | [number, number]  // Chars per tick (default: [1, 3])
    tickInterval?: number          // Interval in ms (default: 30)
    effect?: 'none' | 'fade-in' | 'typing'  // Animation effect
    cursor?: string                // Cursor character (default: '|')
    pauseOnHidden?: boolean        // Pause when hidden (default: true)
  }
}
```

--------------------------------

### Set and Get Definitions Context

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/svelte.md

Demonstrates how to use `setDefinitionsContext` in a parent component to manage definitions and footnotes, and `getDefinitionsContext` in a child component to access them.

```typescript
<script lang="ts">
  import { setDefinitionsContext, getDefinitionsContext } from '@incremark/svelte'

  // In parent component
  const { setDefinations, setFootnoteDefinitions, setFootnoteReferenceOrder } = setDefinitionsContext()

  // In child component
  const { definitions, footnoteDefinitions, footnoteReferenceOrder } = getDefinitionsContext()
</script>
```

--------------------------------

### Incremark with Theming - Vue

Source: https://github.com/marwanbelike/incremark/blob/main/docs/api/vue.md

Apply themes to Incremark content using the `ThemeProvider` component. This example demonstrates applying the `darkTheme` by wrapping the `Incremark` component.

```vue
import { useIncremark, Incremark, ThemeProvider } from '@incremark/vue'
import { darkTheme } from '@incremark/theme'

const incremark = useIncremark()
</script>

<template>
  <ThemeProvider theme="dark">
    <Incremark :incremark="incremark" />
  </ThemeProvider>
</template>
```

--------------------------------

### Enable DevTools for React

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/devtools.md

Import and use `useIncremark` and `useDevTools` to enable developer tools in a React application.

```tsx
import { useIncremark, useDevTools } from '@incremark/react'

function App() {
  const incremark = useIncremark()
  useDevTools(incremark)
  // ...
}
```

--------------------------------

### Configure DevTools Options

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/devtools.md

Customize the appearance and behavior of the developer tools by passing an options object to `useDevTools`. Options include initial open state, position, and theme.

```ts
useDevTools(incremark, {
  open: false,           // Initially open
  position: 'bottom-right',  // Position
  theme: 'dark'          // Theme
})
```

--------------------------------

### Enable DevTools for Vue

Source: https://github.com/marwanbelike/incremark/blob/main/docs/guide/devtools.md

Import and use `useIncremark` and `useDevTools` to enable developer tools in a Vue application.

```ts
import { useIncremark, useDevTools } from '@incremark/vue'

const incremark = useIncremark()
useDevTools(incremark)
```