# @humanspeak/svelte-markdown — full reference

> Concatenated dump of every doc page under https://markdown.svelte.page/docs.
> Each section is bounded by an HTML comment with the source URL,
> so agents can extract individual pages or cite a specific section.

---

<!-- Source: https://markdown.svelte.page/docs/advanced/agent-output -->

# Rendering AI Agent Output

> Render streaming HTML and markdown from AI coding agents with @humanspeak/svelte-markdown, including XSS-safe defaults and custom HTML tag routing.

**Source:** [https://markdown.svelte.page/docs/advanced/agent-output](https://markdown.svelte.page/docs/advanced/agent-output)

---

Modern AI coding agents — Claude Code, Codex, ChatGPT, and agentic workflows — increasingly emit HTML alongside markdown to produce richer output: design mockups, dashboards, code review explainers, interactive artifacts, throwaway editors, status reports. `@humanspeak/svelte-markdown` is built to render this kind of mixed output safely and incrementally.

For background on why HTML has become a common agent output format, see [Thariq's post on the unreasonable effectiveness of HTML](https://x.com/trq212/status/2052809885763747935).

## Why This Package

Four properties make rendering agent output particularly demanding, and the defaults here handle each one:

1. **Agents stream their output.** You need to render a partial response as chunks arrive, not after the whole message is done.
2. **Agents mix markdown and HTML freely.** A single response can include headings, fenced code, tables, SVG, custom elements, and inline `<a>` tags side by side.
3. **Agents can produce dangerous markup.** A prompt-injected response might contain `javascript:` URLs, inline event handlers, or `<iframe srcdoc="...">`. You need defaults that block those without rejecting the whole response.
4. **Agents emit semantic tags you may want to customize.** `<thinking>`, `<tool-call>`, `<artifact>`, or your own design-system tags should route to your own components — not be rendered raw.

## What Works Out of the Box

### Mixed markdown and HTML

`SvelteMarkdown` accepts the agent's output verbatim — no second renderer, no preprocessing. Markdown is parsed by Marked; raw HTML is parsed by HTMLParser2 (not `innerHTML`) and routed through the same renderer pipeline.

```svelte
<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const agentResponse = `## Architecture overview

The system has three layers:

<div class="grid grid-cols-3 gap-4">
    <div><strong>API</strong><br/>Hono + D1</div>
    <div><strong>Worker</strong><br/>Queue consumer</div>
    <div><strong>UI</strong><br/>Svelte 5</div>
</div>

See <a href="#data-flow">data flow</a> below.`
</script>

<SvelteMarkdown source={agentResponse} />
```

### XSS-safe defaults

Defaults are applied **in the Parser** before tokens reach any renderer or snippet, so custom renderers cannot bypass them.

- **URL protocol allowlist** — `href`, `src`, `action`, `formaction`, `cite`, `data`, and `poster` are restricted to `http:`, `https:`, `mailto:`, `tel:`, and relative URLs. `javascript:`, `vbscript:`, `data:`, and `blob:` are blocked, including mixed-case and leading-whitespace variants.
- **Event handler stripping** — all `on*` attributes (`onclick`, `onerror`, `onload`, etc.) are removed.
- **`srcdoc` stripping** — prevents iframe HTML injection.
- **No `<script>` or `<style>` renderers** — both fall through to `UnsupportedHTML`, which renders them as visible escaped text rather than executing or applying them.

See [Security](/docs/advanced/security) for the full list of defaults and known gaps.

### Streaming-aware sanitization

When `streaming` is enabled, each token is sanitized as it is emitted. A partial `<a href="javascript:` arriving mid-stream is sanitized before it reaches the DOM; half-open tags buffer until the parser sees enough to emit a well-formed token, so progressive HTML renders without flicker.

```svelte
<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import type { StreamingChunk } from '@humanspeak/svelte-markdown'

    let markdown: { writeChunk: (chunk: StreamingChunk) => void } | undefined

    async function streamFromAgent(response: Response) {
        const reader = response.body!.getReader()
        const decoder = new TextDecoder()
        while (true) {
            const { done, value } = await reader.read()
            if (done) break
            markdown?.writeChunk(decoder.decode(value, { stream: true }))
        }
    }
</script>

<SvelteMarkdown bind:this={markdown} source="" streaming />
```

See [LLM Streaming](/docs/advanced/llm-streaming) for the full API (offset chunks, `resetStream`, websocket patterns, SDK examples for Anthropic and OpenAI).

### Custom HTML tag routing

Agents often emit semantic markup that should map to a component rather than render literally. The HTML renderer map accepts any tag name, so you can route `<thinking>`, `<tool-call>`, `<artifact>`, or your own design-system tags to your own Svelte components.

```svelte
<script lang="ts">
    import SvelteMarkdown, { Html } from '@humanspeak/svelte-markdown'
    import Thinking from '$lib/components/agent/Thinking.svelte'
    import ToolCall from '$lib/components/agent/ToolCall.svelte'

    const renderers = {
        html: {
            ...Html,
            thinking: Thinking,
            'tool-call': ToolCall
        }
    }
</script>

<SvelteMarkdown source={agentResponse} {renderers} />
```

Tags without a registered renderer fall through to `UnsupportedHTML` (escaped text). See [Custom Renderers](/docs/renderers/custom-renderers).

## Common Use Cases

### Streaming agent responses

The most common case: render a chat-style agent response token-by-token. Bind the component instance, call `writeChunk()` as chunks arrive, and the rendered markdown updates instantly with sanitization applied per token.

```svelte
<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import Anthropic from '@anthropic-ai/sdk'

    let markdown

    async function ask(prompt) {
        const client = new Anthropic()
        const stream = client.messages.stream({
            model: 'claude-sonnet-4-20250514',
            max_tokens: 4096,
            messages: [{ role: 'user', content: prompt }]
        })

        markdown?.resetStream('')

        for await (const event of stream) {
            if (
                event.type === 'content_block_delta' &&
                event.delta.type === 'text_delta'
            ) {
                markdown?.writeChunk(event.delta.text)
            }
        }
    }
</script>

<SvelteMarkdown bind:this={markdown} source="" streaming={true} />
```

### Rich HTML artifacts (designs, dashboards, reports)

When an agent produces a one-shot HTML document — a design exploration, a code-review explainer, a status report — you can render the whole response as a single source. No streaming needed; the same defaults apply.

```svelte
<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    let { artifact } = $props()
</script>

<SvelteMarkdown source={artifact.html} />
```

For PR explainers in particular, ask the agent to emit annotated diffs and severity-coded findings — both render cleanly with the built-in HTML renderers (`<table>`, `<pre>`, `<code>`, `<details>`, etc.) plus inline `style="..."` for visual emphasis.

### Throwaway editors with copy-back

A common agent-output pattern is a single-file editor for one piece of data — drag-rank tickets, edit feature flags, tune a system prompt side-by-side — that ends with a "copy as JSON" or "copy as prompt" button. The agent emits the editor as a self-contained HTML artifact; this package renders it and the user pastes the export back into their next prompt.

These artifacts often need real interactivity. Inline `<script>` is rendered as escaped text by default (not executed), so for an interactive editor you have two options:

1. **Trust the agent's HTML** (only if the agent runs locally / on your infrastructure) — disable sanitization with the [`unsanitizedAttributes`](/docs/advanced/security#disabling-sanitization) passthrough and add a `<script>` renderer to your `renderers.html` map.
2. **Sandbox the artifact in an `<iframe>`** — render the agent's HTML inside an `<iframe srcdoc>` you control, where script execution is isolated from the parent page.

Option 2 is generally safer.

### Mixed text + structured output

Many agents emit a markdown summary followed by structured HTML — a table of metrics, a flowchart SVG, a card grid. This package handles the transition between markdown and HTML automatically; no mode switch needed.

## Custom Semantic Tags

If your agent emits non-standard tags (because you instructed it to in the system prompt, or because the model has been fine-tuned to), provide renderers for them:

```svelte
<script lang="ts">
    import SvelteMarkdown, { Html } from '@humanspeak/svelte-markdown'

    let renderers = {
        html: {
            ...Html,
            // <thinking>...</thinking> → collapsed by default
            thinking: ThinkingBlock,
            // <citation source="...">...</citation> → numbered link
            citation: Citation,
            // <artifact type="..." id="...">...</artifact> → boxed panel
            artifact: ArtifactPanel
        }
    }
</script>
```

Each renderer receives `{ attributes, children }` as props — the parsed HTML attributes and a snippet for the children. See [HTML Renderers](/docs/renderers/html-renderers) for the full props contract.

## Security Considerations for Agent Output

The defaults are designed for the common case of trusted agent output (output from an agent you invoked, with prompts you control). For untrusted input — anything that may include user-supplied or prompt-injected content — layer additional protection on top:

- **Lock down HTML further.** Use `excludeHtmlOnly(['iframe', 'form', 'embed'])` if you do not want those tags at all.
- **Combine with DOMPurify.** Built-in sanitization handles markdown-native vectors (e.g. `[Click](javascript:...)`); DOMPurify handles HTML-level threats. See [Security: External Sanitization](/docs/advanced/security#external-sanitization).
- **Use CSP headers.** A strict Content-Security-Policy at the response level is your final line of defense.

For the full picture — including known gaps the defaults do not cover (CSS not sanitized, `iframe`/`form`/`embed` rendered by default, less common URL attributes) — see [Security](/docs/advanced/security).

## Performance

Streaming render times stay well under the 16.7ms frame budget even at 100 characters per second — see [LLM Streaming: Performance](/docs/advanced/llm-streaming#performance-characteristics) for measured numbers. Token caching also kicks in automatically for any completed responses in a chat history, so re-renders of earlier messages are effectively free.

## Try It Live

The [Agent Output example](/examples/agent-output) renders a simulated streaming agent response with both clean and malicious payloads side by side, so you can see sanitization apply in real time.

## Related

- [Security](/docs/advanced/security) — full sanitization defaults and known gaps
- [LLM Streaming](/docs/advanced/llm-streaming) — full streaming API (SSE, websocket offsets, SDK examples)
- [Custom Renderers](/docs/renderers/custom-renderers) — override any renderer with your own component
- [HTML Renderers](/docs/renderers/html-renderers) — every HTML tag renderer
- [Allow/Deny Filtering](/docs/advanced/allow-deny) — restrict which tags render

<!-- Source: https://markdown.svelte.page/docs/advanced/allow-deny -->

# Allow/Deny Filtering

> Control which markdown elements and HTML tags render in @humanspeak/svelte-markdown with allow-list and deny-list helpers for safer output in apps.

**Source:** [https://markdown.svelte.page/docs/advanced/allow-deny](https://markdown.svelte.page/docs/advanced/allow-deny)

---

`@humanspeak/svelte-markdown` provides a set of utility functions for controlling which elements are rendered. You can allowlist specific elements (blocking everything else), denylist specific elements (allowing everything else), or block all elements of a category.

There are two separate sets of functions: one for **HTML tag renderers** and one for **markdown renderers**.

## HTML Tag Filtering

These functions return `HtmlRenderers` objects that you pass to `renderers.html`.

### `allowHtmlOnly(allowed)`

Creates an HTML renderer map where only the specified tags use their default components. All other tags are replaced with `UnsupportedHTML` (which renders nothing).

```svelte
<script>
    import SvelteMarkdown, { allowHtmlOnly } from '@humanspeak/svelte-markdown'

    // Only allow these safe inline HTML tags
    const safeHtml = allowHtmlOnly(['strong', 'em', 'a', 'code', 'br'])
</script>

<SvelteMarkdown source={markdown} renderers={{ html: safeHtml }} />
```

You can also provide custom components for specific tags using tuple syntax:

```typescript
import { allowHtmlOnly } from '@humanspeak/svelte-markdown'
import CustomDiv from './CustomDiv.svelte'

// Allow <a> with its default renderer, and <div> with a custom component
const html = allowHtmlOnly(['a', ['div', CustomDiv]])
```

**Signature:**

```typescript
function allowHtmlOnly(
    allowed: Array<HtmlKey | [HtmlKey, Component | null]>
): HtmlRenderers
```

### `excludeHtmlOnly(excluded, overrides?)`

Creates an HTML renderer map where the specified tags are blocked (set to `UnsupportedHTML`). All other tags use their default components.

```svelte
<script>
    import SvelteMarkdown, { excludeHtmlOnly } from '@humanspeak/svelte-markdown'

    // Block potentially dangerous tags, allow everything else
    const filteredHtml = excludeHtmlOnly(['iframe', 'form', 'input', 'script', 'embed'])
</script>

<SvelteMarkdown source={markdown} renderers={{ html: filteredHtml }} />
```

You can optionally override non-excluded tags with custom components:

```typescript
import { excludeHtmlOnly } from '@humanspeak/svelte-markdown'
import CustomA from './CustomA.svelte'

// Block iframe, override <a> with custom component
const html = excludeHtmlOnly(['iframe'], [['a', CustomA]])
```

Exclusions take precedence over overrides. If a tag appears in both the exclusion list and the overrides, it will be blocked.

**Signature:**

```typescript
function excludeHtmlOnly(
    excluded: HtmlKey[],
    overrides?: Array<[HtmlKey, Component | null]>
): HtmlRenderers
```

### `buildUnsupportedHTML()`

Creates an HTML renderer map where every tag is set to `UnsupportedHTML`. This blocks all raw HTML rendering.

```svelte
<script>
    import SvelteMarkdown, { buildUnsupportedHTML } from '@humanspeak/svelte-markdown'

    // Disable all raw HTML in markdown
    const noHtml = buildUnsupportedHTML()
</script>

<SvelteMarkdown source={markdown} renderers={{ html: noHtml }} />
```

**Signature:**

```typescript
function buildUnsupportedHTML(): HtmlRenderers
```

## Markdown Renderer Filtering

These functions return partial `Renderers` objects (excluding the `html` key) that you spread into or merge with the `renderers` prop.

### `allowRenderersOnly(allowed)`

Creates a renderer map where only the specified markdown renderers use their default components. All other renderers are set to `Unsupported` (which renders nothing).

```svelte
<script>
    import SvelteMarkdown, { allowRenderersOnly } from '@humanspeak/svelte-markdown'

    // Only allow paragraphs, text, links, and emphasis
    const minimal = allowRenderersOnly(['paragraph', 'text', 'link', 'em', 'strong'])
</script>

<SvelteMarkdown source={markdown} renderers={minimal} />
```

You can provide custom components using tuple syntax:

```typescript
import { allowRenderersOnly } from '@humanspeak/svelte-markdown'
import CustomParagraph from './CustomParagraph.svelte'

const renderers = allowRenderersOnly([
    ['paragraph', CustomParagraph],
    'text',
    'link'
])
```

**Signature:**

```typescript
function allowRenderersOnly(
    allowed: Array<RendererKey | [RendererKey, RendererComponent]>
): Omit<Renderers, 'html'>
```

### `excludeRenderersOnly(excluded, overrides?)`

Creates a renderer map where the specified keys are set to `Unsupported`. All other keys use their defaults.

```svelte
<script>
    import SvelteMarkdown, { excludeRenderersOnly } from '@humanspeak/svelte-markdown'

    // Disable images and code blocks
    const renderers = excludeRenderersOnly(['image', 'code'])
</script>

<SvelteMarkdown source={markdown} renderers={renderers} />
```

With custom overrides on non-excluded keys:

```typescript
import { excludeRenderersOnly } from '@humanspeak/svelte-markdown'
import CustomHeading from './CustomHeading.svelte'

// Exclude images, override headings with a custom component
const renderers = excludeRenderersOnly(
    ['image'],
    [['heading', CustomHeading]]
)
```

**Signature:**

```typescript
function excludeRenderersOnly(
    excluded: RendererKey[],
    overrides?: Array<[RendererKey, RendererComponent]>
): Omit<Renderers, 'html'>
```

### `buildUnsupportedRenderers()`

Creates a renderer map where every markdown renderer is set to `Unsupported`. This blocks all markdown rendering (but does not affect HTML tag renderers).

```typescript
import { buildUnsupportedRenderers } from '@humanspeak/svelte-markdown'

const renderers = {
    ...buildUnsupportedRenderers(),
    // Re-enable only paragraph and text
    paragraph: defaultRenderers.paragraph,
    text: defaultRenderers.text
}
```

**Signature:**

```typescript
function buildUnsupportedRenderers(): Omit<Renderers, 'html'>
```

## Combining HTML and Markdown Filtering

You can combine both HTML and markdown filtering in a single configuration:

```svelte
<script>
    import SvelteMarkdown, {
        allowHtmlOnly,
        excludeRenderersOnly
    } from '@humanspeak/svelte-markdown'

    const renderers = {
        // Disable image and code renderers
        ...excludeRenderersOnly(['image', 'code']),
        // Only allow safe HTML tags
        html: allowHtmlOnly(['strong', 'em', 'a'])
    }
</script>

<SvelteMarkdown source={markdown} {renderers} />
```

## Available Keys

Use the exported key arrays to see all valid keys:

```typescript
import { rendererKeys, htmlRendererKeys } from '@humanspeak/svelte-markdown'

console.log(rendererKeys)
// ['heading', 'paragraph', 'text', 'image', 'link', ...]

console.log(htmlRendererKeys)
// ['a', 'abbr', 'address', 'article', 'aside', ...]
```

## Related

- [HTML Renderers](/docs/renderers/html-renderers) -- all 69+ HTML tag renderers
- [Markdown Renderers](/docs/renderers/markdown-renderers) -- all 24 markdown renderers
- [Security](/docs/advanced/security) -- security considerations for filtering
- [HTML Filtering Examples](/docs/examples/html-filtering) -- runnable examples

<!-- Source: https://markdown.svelte.page/docs/advanced/headless-parser -->

# Headless Parser

> Use IncrementalParser without the Svelte component, powering headless agents, non-Svelte consumers, server pipelines, and streaming token updates.

**Source:** [https://markdown.svelte.page/docs/advanced/headless-parser](https://markdown.svelte.page/docs/advanced/headless-parser)

---

`@humanspeak/svelte-markdown` exports the streaming engine that powers `streaming={true}` as a standalone class: `IncrementalParser`. The same instance is used internally by the Svelte component, so the diffing behavior and token shape are identical — the export is for cases where the Svelte component itself is the wrong layer.

Reach for `IncrementalParser` when:

- You're rendering markdown outside Svelte — a custom DOM library, a CLI, a React island in the same app — and want the streaming-aware token diff without re-implementing it.
- You need the parsed tokens on the **server** before the page reaches the client (e.g. precomputing token arrays for analytics, building a search index of LLM output, gating content via policy before HTML is generated).
- You're writing a higher-level abstraction over `@humanspeak/svelte-markdown` and want to reuse the diff index without owning the renderer.
- You're running benchmarks or property tests that need direct token access.

For typical Svelte apps, [``](/docs/advanced/llm-streaming) is what you want — it wraps `IncrementalParser` and handles rendering for you.

## Basic Usage

```typescript
import { IncrementalParser } from '@humanspeak/svelte-markdown'

const parser = new IncrementalParser({ gfm: true })

// First update — all tokens are "new"
const r1 = parser.update('# Hello')
// r1.tokens   → [{ type: 'heading', depth: 1, text: 'Hello', ... }]
// r1.divergeAt → 0

// Second update — heading unchanged, paragraph appended
const r2 = parser.update('# Hello\n\nWorld')
// r2.tokens   → [headingToken, paragraphToken]
// r2.divergeAt → 1   (token at index 0 is reference-equal to the previous one)
```

The parser holds the previous parse internally and diffs against it on every `update()`, so consumers don't need to track the prior state themselves.

## API

### `new IncrementalParser(options)`

Constructor. Takes `SvelteMarkdownOptions` — the same options accepted by the Svelte component's `options` prop.

```typescript
import { IncrementalParser, type SvelteMarkdownOptions } from '@humanspeak/svelte-markdown'

const options: SvelteMarkdownOptions = {
    gfm: true,       // GitHub-Flavored Markdown (tables, strikethrough, task lists)
    breaks: false,   // Convert single newlines into <br>
    pedantic: false
}

const parser = new IncrementalParser(options)
```

The full set of options matches Marked's [`MarkedOptions`](https://marked.js.org/using_advanced#options), including extension hooks (`walkTokens`, `tokenizer`). When any custom tokenizer or extension is registered, the internal tail-window optimization is disabled (each `update()` becomes a full re-parse), since user-provided tokenizers can mutate tokens in ways the diff can't detect.

### `parser.update(source)`

Parses the full source string and returns the diff against the previous parse.

```typescript
const result = parser.update(currentSource)
```

Always pass the **full accumulated source** — not just the delta. Append-only streaming (typical LLM use case) is the optimized path, but the parser correctly handles arbitrary edits (insertions, replacements, full rewrites) too.

### `IncrementalUpdateResult`

```typescript
interface IncrementalUpdateResult {
    /** The full new token array */
    tokens: Token[]
    /** Index of the first token that differs from the previous parse */
    divergeAt: number
}
```

`divergeAt` is the actionable field: every token at index `< divergeAt` is reference-equal to the corresponding token from the previous `update()` call, so a consumer can skip re-rendering them. On the first call (or after a structural change that invalidates the prefix), `divergeAt` is `0`.

## Streaming Pattern

The common loop for LLM output:

```typescript
import { IncrementalParser } from '@humanspeak/svelte-markdown'

const parser = new IncrementalParser({ gfm: true })
let source = ''

async function consumeStream(response: Response) {
    const reader = response.body!.getReader()
    const decoder = new TextDecoder()

    while (true) {
        const { done, value } = await reader.read()
        if (done) break

        source += decoder.decode(value, { stream: true })
        const { tokens, divergeAt } = parser.update(source)

        // Render only what changed. The first `divergeAt` tokens
        // are reference-equal to the previous frame, so a virtual
        // DOM or manual reconciler can short-circuit them.
        renderFrom(tokens, divergeAt)
    }
}
```

Per-update cost stays well under the 60fps budget on typical LLM streams (median ~3 ms on the [caching-performance harness](/examples/caching-performance)), regardless of total document size, because the tail-window optimization re-parses only the suffix beyond the last stable token boundary.

## Reconciling With Sanitization

`IncrementalParser` returns tokens with sanitization **not yet applied** — `href` allow-listing, `on*` stripping, and other guards run inside the Svelte component layer. If you're using the headless parser to render to a non-Svelte target, you'll want to apply the same defenses before mounting the result.

The defaults are exported as plain functions so you can plug them in:

```typescript
import {
    defaultSanitizeUrl,
    defaultSanitizeAttributes
} from '@humanspeak/svelte-markdown'

// Apply per token after parsing, before handing off to your renderer.
for (const token of tokens) {
    if (token.type === 'link' || token.type === 'image') {
        token.href = defaultSanitizeUrl(token.href, {
            type: token.type,
            tag: token.type === 'image' ? 'img' : 'a'
        })
    }
    // Walk html tokens, etc.
}
```

See [Security](/docs/advanced/security) for the full sanitizer contract, including the context-aware override pattern.

## Caveats

- **Sanitization is your responsibility.** As above — the headless parser hands you raw Marked tokens.
- **Tail-window optimization is disabled when extensions are registered.** If you pass `walkTokens`, `tokenizer`, or block/inline extensions, every `update()` becomes a full re-parse. Per-update cost stays bounded, but the constant factor goes up.
- **Reference-syntax-aware reparse.** When the source contains markdown reference links (`[text][ref]`) or reference definitions (`[ref]: url`), the parser falls back to a full re-parse, since later definitions can retroactively change earlier inline children without changing their `raw` strings.
- **Not thread-safe.** One `IncrementalParser` instance per stream. Don't share instances across concurrent inputs.

## Related

- [LLM Streaming](/docs/advanced/llm-streaming) — the Svelte component wrapper around this parser, with `writeChunk()` / `resetStream()` ergonomics.
- [Token Caching](/docs/advanced/token-caching) — the LRU cache layer used by the parser. Exported as `TokenCache` and `MemoryCache` for direct use.
- [Security](/docs/advanced/security) — sanitization contract you'll want to layer on top when rendering to a non-Svelte target.
- [Types & Exports](/docs/api/types) — full type reference for `IncrementalUpdateResult`, `Token`, `SvelteMarkdownOptions`.

<!-- Source: https://markdown.svelte.page/docs/advanced/llm-streaming -->

# LLM Streaming

> Render AI chat responses in real time with @humanspeak/svelte-markdown, using token-by-token streaming for ChatGPT-style Svelte app interfaces.

**Source:** [https://markdown.svelte.page/docs/advanced/llm-streaming](https://markdown.svelte.page/docs/advanced/llm-streaming)

---

`@humanspeak/svelte-markdown` handles real-time streaming from Large Language Models (LLMs) like ChatGPT, Claude, Gemini, and other AI assistants out of the box. As tokens arrive via Server-Sent Events (SSE) or WebSocket connections, you can write them directly to the component instance with `writeChunk()` and the rendered markdown updates instantly.

This is also the path for rendering streaming agent output that mixes markdown with rich HTML (designs, dashboards, interactive artifacts). Built-in sanitization runs per token as it is emitted, so a partial `<script>` or `<a href="javascript:...">` arriving mid-stream is sanitized before render. Half-open tags buffer until the parser sees enough to emit a well-formed token, so progressive HTML renders without flicker.

## How It Works

LLM APIs stream responses token-by-token. Each token is a small chunk of text -- sometimes a word, sometimes a partial word, sometimes punctuation or whitespace. The typical integration pattern is:

1. The LLM API sends tokens via Server-Sent Events (SSE) or a streaming HTTP response.
2. Your application accumulates tokens into a growing markdown string, either manually or through `writeChunk()`.
3. `SvelteMarkdown` re-parses and re-renders the full source on each update.
4. Svelte's fine-grained reactivity ensures only the changed DOM nodes are updated.

The component works reactively by default. For best streaming performance, pass `streaming={true}` to enable smart token diffing -- the component re-parses the full source for correctness but only updates DOM nodes for tokens that actually changed, keeping per-update cost under 2ms regardless of document size.

**Note:** `streaming` is automatically disabled when async extensions (e.g., Mermaid) are used, since async `walkTokens` callbacks are incompatible with the synchronous diffing path. A console warning is logged in this case.

## Basic Usage

### Preferred: imperative chunk writes

```svelte
<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import type { StreamingChunk } from '@humanspeak/svelte-markdown'

    let markdown:
        | {
              writeChunk: (chunk: StreamingChunk) => void
              resetStream: (nextSource?: string) => void
          }
        | undefined

    async function streamFromAPI() {
        const response = await fetch('/api/chat', { method: 'POST', body: '...' })
        if (!response.body) throw new Error('No response body')
        const reader = response.body.getReader()
        const decoder = new TextDecoder()

        markdown?.resetStream('')

        while (true) {
            const { done, value } = await reader.read()
            if (done) break
            markdown?.writeChunk(decoder.decode(value, { stream: true }))
        }
    }
</script>

<SvelteMarkdown bind:this={markdown} source="" streaming={true} />
```

`writeChunk()` accepts:

- `string` for append mode
- `{ value, offset }` for websocket-style offset patches

The first successful write locks the stream into one mode until `resetStream()` or a `source` prop reset. If an offset patch skips ahead, missing positions are padded with spaces.

### With websocket-style offset chunks

```typescript
markdown?.writeChunk({ value: 'Hel', offset: 0 })
markdown?.writeChunk({ value: 'lo', offset: 3 })
markdown?.writeChunk({ value: ' world', offset: 5 })
```

Offset chunks use overwrite semantics, not insert semantics. Each patch writes `value` starting at `offset`, preserves any trailing content after the overwritten span, and pads skipped gaps with spaces.

This means out-of-order websocket delivery is fine:

```typescript
markdown?.writeChunk({ value: ' world', offset: 5 })
markdown?.writeChunk({ value: 'Hello', offset: 0 })
```

There is no delete or truncate behavior in offset mode, and offsets must be non-negative safe integers.

Like append mode, the first successful write locks the stream shape until `resetStream()` or a `source` prop reset.

### SDK Examples

Choose between **chunked** mode (imperative `writeChunk()` API) and **concat** mode (reactive `source += chunk` pattern):

<div class="not-prose mb-6 flex flex-wrap items-center gap-3">
    <button
        onclick={() => (mode = 'chunked')}
        class="inline-flex items-center gap-2 rounded-lg px-4 py-2 text-sm font-medium transition-colors {mode === 'chunked' ? 'bg-brand-600 text-white' : 'border-border bg-card text-muted-foreground hover:text-foreground border'}"
    >
        Chunked (writeChunk)
    </button>
    <button
        onclick={() => (mode = 'concat')}
        class="inline-flex items-center gap-2 rounded-lg px-4 py-2 text-sm font-medium transition-colors {mode === 'concat' ? 'bg-brand-600 text-white' : 'border-border bg-card text-muted-foreground hover:text-foreground border'}"
    >
        Concat (source +=)
    </button>
</div>

### With the Anthropic SDK (Claude)

{#if mode === 'chunked'}

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import Anthropic from '@anthropic-ai/sdk'

    let markdown

    async function streamResponse(prompt) {
        const client = new Anthropic()

        const stream = client.messages.stream({
            model: 'claude-sonnet-4-20250514',
            max_tokens: 1024,
            messages: [{ role: 'user', content: prompt }]
        })

        markdown?.resetStream('')

        for await (const event of stream) {
            if (
                event.type === 'content_block_delta' &&
                event.delta.type === 'text_delta'
            ) {
                markdown?.writeChunk(event.delta.text)
            }
        }
    }
</script>

<SvelteMarkdown bind:this={markdown} source="" streaming={true} />
```

{:else}

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import Anthropic from '@anthropic-ai/sdk'

    let source = $state('')

    async function streamResponse(prompt) {
        const client = new Anthropic()

        const stream = client.messages.stream({
            model: 'claude-sonnet-4-20250514',
            max_tokens: 1024,
            messages: [{ role: 'user', content: prompt }]
        })

        for await (const event of stream) {
            if (
                event.type === 'content_block_delta' &&
                event.delta.type === 'text_delta'
            ) {
                source += event.delta.text
            }
        }
    }
</script>

<SvelteMarkdown {source} streaming={true} />
```

{/if}

### With the OpenAI SDK (ChatGPT)

{#if mode === 'chunked'}

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import OpenAI from 'openai'

    let markdown

    async function streamResponse(prompt) {
        const client = new OpenAI()

        const stream = await client.chat.completions.create({
            model: 'gpt-4o',
            messages: [{ role: 'user', content: prompt }],
            stream: true
        })

        markdown?.resetStream('')

        for await (const chunk of stream) {
            const delta = chunk.choices[0]?.delta?.content
            if (delta) {
                markdown?.writeChunk(delta)
            }
        }
    }
</script>

<SvelteMarkdown bind:this={markdown} source="" streaming={true} />
```

{:else}

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import OpenAI from 'openai'

    let source = $state('')

    async function streamResponse(prompt) {
        const client = new OpenAI()

        const stream = await client.chat.completions.create({
            model: 'gpt-4o',
            messages: [{ role: 'user', content: prompt }],
            stream: true
        })

        for await (const chunk of stream) {
            const delta = chunk.choices[0]?.delta?.content
            if (delta) {
                source += delta
            }
        }
    }
</script>

<SvelteMarkdown {source} streaming={true} />
```

{/if}

### With fetch and Server-Sent Events

{#if mode === 'chunked'}

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    let markdown

    async function streamFromAPI(prompt) {
        const response = await fetch('/api/chat', {
            method: 'POST',
            body: JSON.stringify({ prompt }),
            headers: { 'Content-Type': 'application/json' }
        })

        if (!response.ok) throw new Error(`HTTP ${response.status}`)

        const reader = response.body.getReader()
        const decoder = new TextDecoder()

        markdown?.resetStream('')

        try {
            while (true) {
                const { done, value } = await reader.read()
                if (done) break
                markdown?.writeChunk(decoder.decode(value, { stream: true }))
            }
        } finally {
            reader.releaseLock()
        }
    }
</script>

<SvelteMarkdown bind:this={markdown} source="" streaming={true} />
```

{:else}

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    let source = $state('')

    async function streamFromAPI(prompt) {
        const response = await fetch('/api/chat', {
            method: 'POST',
            body: JSON.stringify({ prompt }),
            headers: { 'Content-Type': 'application/json' }
        })

        if (!response.ok) throw new Error(`HTTP ${response.status}`)

        const reader = response.body.getReader()
        const decoder = new TextDecoder()

        try {
            while (true) {
                const { done, value } = await reader.read()
                if (done) break
                source += decoder.decode(value, { stream: true })
            }
        } finally {
            reader.releaseLock()
        }
    }
</script>

<SvelteMarkdown {source} streaming={true} />
```

{/if}

## Performance Characteristics

We measured render performance across different streaming speeds and chunking strategies using the [interactive streaming demo](/examples/llm-streaming):

| Streaming Speed | Chunk Mode | Avg Render | Peak Render | Dropped Frames |
|-----------------|------------|:----------:|:-----------:|:--------------:|
| 30 words/sec | Word | ~3ms | ~11ms | 0 |
| 100 chars/sec | Character | ~4ms | ~21ms | 0 |
| 50 words/sec | Word | ~3ms | ~12ms | 0 |

All render times stay well under the 16.7ms frame budget (60fps), meaning the browser has time to paint every frame without jank. Even at 100 characters per second in character mode (a worst-case scenario far beyond real LLM speeds), average render time remains under 5ms.

### How Render Time Scales

Render time grows linearly with document length because the full markdown source is re-parsed on each update. For a typical LLM response (~2,000 characters), the overhead is negligible:

- **0-500 chars:** &lt;1ms per render
- **500-1,000 chars:** ~2-3ms per render
- **1,000-2,000 chars:** ~5-7ms per render
- **2,000+ chars:** ~7-10ms per render

For very long documents (10,000+ characters), consider the optimization strategies below.

## Best Practices

### 1. Prefer Word-Level Chunking

If you control the chunking strategy (e.g., in a custom SSE endpoint), emit tokens at word boundaries rather than individual characters. This reduces the total number of re-renders while producing the same visual result:

```javascript
// Server-side: buffer tokens and emit at word boundaries
let buffer = ''
for await (const token of llmStream) {
    buffer += token
    if (buffer.endsWith(' ') || buffer.endsWith('\n')) {
        controller.enqueue(encoder.encode(buffer))
        buffer = ''
    }
}
if (buffer) controller.enqueue(encoder.encode(buffer))
```

### 2. Use Token Caching for Chat History

When displaying a conversation with multiple messages, previously completed messages are re-rendered on every update. Enable [token caching](/docs/advanced/token-caching) so that completed messages skip re-parsing:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    let messages = $state([])
</script>

{#each messages as message}
    <!-- Completed messages hit the token cache automatically -->
    <SvelteMarkdown source={message.content} />
{/each}
```

### 3. Debounce for Extremely Fast Streams

If your LLM stream is unusually fast (100+ tokens/second) and you notice frame drops, you can batch updates using `requestAnimationFrame`:

```javascript
let pending = ''
let rafScheduled = false

function onToken(token) {
    pending += token
    if (!rafScheduled) {
        rafScheduled = true
        requestAnimationFrame(() => {
            source += pending
            pending = ''
            rafScheduled = false
        })
    }
}
```

This coalesces multiple tokens into a single render per frame, reducing total renders from ~100/sec to ~60/sec while maintaining smooth visual output.

## Estimating Streaming Costs

When building production LLM streaming UIs, understanding token costs is as important as render performance. Each streamed token has a price that varies by model, provider, and whether it's an input or output token. [ModelPricing.ai](https://modelpricing.ai) provides a pricing estimation API that covers all major LLM providers -- useful for displaying real-time cost tracking alongside your streamed responses, setting usage budgets, or building cost-aware model selection into your application.

## Try It Live

Experiment with different streaming speeds, jitter, chunk modes, and websocket-style offset patch simulation in the [interactive LLM streaming demo](/examples/llm-streaming).

## Related

- [Security](/docs/advanced/security) -- XSS defaults applied per token during streaming
- [Token Caching](/docs/advanced/token-caching) -- cache parsed tokens for instant re-renders
- [Getting Started](/docs/getting-started) -- installation and basic usage
- [SvelteMarkdown API](/docs/api/svelte-markdown) -- full prop reference
- [ModelPricing.ai](https://modelpricing.ai) -- LLM pricing estimation API for cost tracking

<!-- Source: https://markdown.svelte.page/docs/advanced/marked-extensions -->

# Marked Extensions

> Use built-in and third-party marked extensions with @humanspeak/svelte-markdown for KaTeX math, custom tokens, syntax tools, and async rendering.

**Source:** [https://markdown.svelte.page/docs/advanced/marked-extensions](https://markdown.svelte.page/docs/advanced/marked-extensions)

---

`@humanspeak/svelte-markdown` ships first-class extensions for KaTeX, Mermaid, GitHub-style alerts, and footnotes from the `@humanspeak/svelte-markdown/extensions` subpath. Any third-party [marked extension](https://marked.js.org/using_advanced#extensions) that adds custom token types also works — pass it via the `extensions` prop and provide renderers for the custom token types as **component renderers** or **snippet overrides**.

## How It Works

Marked extensions define custom token types, each with a `name` property (e.g., `inlineKatex`, `blockKatex`, `alert`). When you pass extensions via the `extensions` prop, SvelteMarkdown:

1. **Registers** the extension's tokenizers internally so the lexer produces the custom tokens
2. **Extracts** the token type `name`s from the extensions array
3. **Makes** those names available as both **component renderer keys** (`renderers={{ inlineKatex: ... }}`) and **snippet override names** (`{#snippet inlineKatex(props)}`)

Each snippet or component receives the token's own properties as props. For example, the built-in `markedKatex` produces tokens with `text` and `displayMode`, so your renderer gets `{ text: string, displayMode: boolean }`.

### Dynamic Extension Objects

SvelteMarkdown includes extension identity in its internal parser cache. If you replace an extension object, tokenizer object, or tokenizer function, the parser treats that as a new parsing configuration and re-parses the source.

That matters when an extension factory closes over reactive state:

```svelte
<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import type { MarkedExtension } from 'marked'

    let displayFormat = $state<'decimal' | 'percent'>('decimal')

    const makeDisplayExtension = (format: 'decimal' | 'percent'): MarkedExtension => ({
        extensions: [
            {
                name: 'displayValue',
                level: 'inline',
                tokenizer(src) {
                    const match = /^\((\d+)\)/.exec(src)
                    if (!match) return

                    return {
                        type: 'displayValue',
                        raw: match[0],
                        text: match[1],
                        displayFormat: format
                    }
                }
            }
        ]
    })

    const extensions = $derived([makeDisplayExtension(displayFormat)])
</script>

<SvelteMarkdown source="(42)" {extensions}>
    {#snippet displayValue(props)}
        <span data-format={props.displayFormat}>{props.text}</span>
    {/snippet}
</SvelteMarkdown>
```

When `displayFormat` changes from `decimal` to `percent`, the new extension object invalidates the cached parse even though the markdown source is unchanged. The updated token props then flow into your renderer or snippet without requiring a manual cache key or workaround.

### Finding Token Type Names

To discover the snippet/renderer names for any extension, check the `name` field in its `extensions` array:

```javascript
// Built-in markedKatex → tokens named "inlineKatex" and "blockKatex"
// → {#snippet inlineKatex(props)} and {#snippet blockKatex(props)}
// → or renderers={{ inlineKatex: ..., blockKatex: ... }}

// A custom alert extension → token named "alert"
// → {#snippet alert(props)}
// → or renderers={{ alert: AlertComponent }}
```

You can also inspect the tokens at runtime using the `parsed` callback:

```svelte
<SvelteMarkdown {source} {extensions} parsed={(tokens) => console.log(tokens)} />
```

## Step-by-Step: KaTeX Math Rendering

The package includes built-in `markedKatex` and `KatexRenderer` helpers exported from `@humanspeak/svelte-markdown/extensions`. The default delimiter set mirrors KaTeX's own [`auto-render`](https://katex.org/docs/autorender.html) extension:

| Delimiter pair | Level | `displayMode` |
| --- | --- | --- |
| `\(...\)` | inline | `false` |
| `\[...\]` (own-line) | block | `true` |
| `$$...$$` (own-line) | block | `true` |
| `\begin{equation}...\end{equation}` and other AMS environments | block | `true` |

Single-dollar inline (`$x^2$`) is **off** by default — KaTeX itself excludes it from auto-render to avoid currency-string clashes like `$5,000`. Pass `{ singleDollarInline: true }` to enable it; it uses a whitespace-bounded rule so currency strings still won't match.

### 1. Install KaTeX

`katex` is an optional peer dependency — install it yourself:

```bash
npm install katex
```

### 2. Wire Up with Component Renderers

Pass the extension via the `extensions` prop and map token types to `KatexRenderer`:

```svelte
<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import type { RendererComponent, Renderers } from '@humanspeak/svelte-markdown'
    import { markedKatex, KatexRenderer } from '@humanspeak/svelte-markdown/extensions'

    interface KatexRenderers extends Renderers {
        inlineKatex: RendererComponent
        blockKatex: RendererComponent
    }

    const renderers: Partial<KatexRenderers> = {
        inlineKatex: KatexRenderer,
        blockKatex: KatexRenderer
    }
</script>

<SvelteMarkdown
    source={markdown}
    extensions={[markedKatex()]}
    {renderers}
/>
```

`KatexRenderer` hardcodes `throwOnError: false` so a single malformed expression renders as a tinted error span instead of throwing. If you need stricter behavior, supply your own component for the `inlineKatex` / `blockKatex` keys.

### 3. Alternative: Snippet Overrides

Instead of component renderers, you can use snippet overrides for inline rendering:

```svelte
<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import { markedKatex } from '@humanspeak/svelte-markdown/extensions'
    import katex from 'katex'
</script>

<svelte:head>
    <link
        rel="stylesheet"
        href="https://cdn.jsdelivr.net/npm/katex@0.16.45/dist/katex.min.css"
        crossorigin="anonymous"
    />
</svelte:head>

<SvelteMarkdown
    source={markdown}
    extensions={[markedKatex()]}
>
    {#snippet inlineKatex(props)}
        {@html katex.renderToString(props.text, { throwOnError: false, displayMode: false })}
    {/snippet}
    {#snippet blockKatex(props)}
        {@html katex.renderToString(props.text, { throwOnError: false, displayMode: true })}
    {/snippet}
</SvelteMarkdown>
```

### 4. Include KaTeX CSS

KaTeX requires its stylesheet for proper math formatting:

```svelte
<svelte:head>
    <link
        rel="stylesheet"
        href="https://cdn.jsdelivr.net/npm/katex@0.16.45/dist/katex.min.css"
        crossorigin="anonymous"
    />
</svelte:head>
```

### Complete Example

Putting it all together with component renderers:

```svelte
<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import type { RendererComponent, Renderers } from '@humanspeak/svelte-markdown'
    import { markedKatex, KatexRenderer } from '@humanspeak/svelte-markdown/extensions'

    interface KatexRenderers extends Renderers {
        inlineKatex: RendererComponent
        blockKatex: RendererComponent
    }

    const renderers: Partial<KatexRenderers> = {
        inlineKatex: KatexRenderer,
        blockKatex: KatexRenderer
    }

    const source = `
# Euler's Identity

The equation \\(e^{i\\pi} + 1 = 0\\) is considered the most beautiful in mathematics.

\\[
e^{i\\pi} + 1 = 0
\\]
`
</script>

<svelte:head>
    <link
        rel="stylesheet"
        href="https://cdn.jsdelivr.net/npm/katex@0.16.45/dist/katex.min.css"
        crossorigin="anonymous"
    />
</svelte:head>

<SvelteMarkdown
    {source}
    extensions={[markedKatex()]}
    {renderers}
/>
```

## Step-by-Step: Mermaid Diagrams

Unlike KaTeX (synchronous rendering via `katex.renderToString()`), **Mermaid is async and browser-only** — it requires the DOM and uses `await mermaid.render()`. The package provides built-in `markedMermaid` and `MermaidRenderer` helpers so you don't need to write boilerplate.

### 1. Install Mermaid

Mermaid is an optional peer dependency — install it yourself:

```bash
npm install mermaid
```

### 2. Wire Up with Built-in Helpers

The package exports `markedMermaid()` (a zero-dep tokenizer for ` ```mermaid ` code blocks) and `MermaidRenderer` (a Svelte component that lazy-loads mermaid and renders SVG diagrams with dark mode support):

```svelte
<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import type { RendererComponent, Renderers } from '@humanspeak/svelte-markdown'
    import { markedMermaid, MermaidRenderer } from '@humanspeak/svelte-markdown/extensions'

    const markdown = `
\`\`\`mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
\`\`\`
`

    interface MermaidRenderers extends Renderers {
        mermaid: RendererComponent
    }

    const renderers: Partial<MermaidRenderers> = {
        mermaid: MermaidRenderer
    }
</script>

<SvelteMarkdown
    source={markdown}
    extensions={[markedMermaid()]}
    {renderers}
/>
```

The built-in `MermaidRenderer` handles:
- **Dynamic import**: `import('mermaid')` in `onMount` ensures it only loads in the browser
- **Async rendering**: `mermaid.render()` returns a promise with the SVG string
- **Loading/error states**: Handles the async lifecycle gracefully
- **Unique IDs**: `crypto.randomUUID()` prevents collisions when multiple diagrams render
- **Theme reactivity**: A `MutationObserver` watches the `<html>` class for dark/light changes and re-renders with the correct Mermaid theme via per-diagram directives

### Snippet Overrides for Async Extensions

You can also use snippet overrides to wrap `MermaidRenderer` with custom markup — extra classes, wrapper divs, or surrounding content:

```svelte
<SvelteMarkdown source={markdown} extensions={[markedMermaid()]}>
    {#snippet mermaid(props)}
        <div class="my-diagram-wrapper">
            <MermaidRenderer text={props.text} />
        </div>
    {/snippet}
</SvelteMarkdown>
```

Since snippets run synchronously during render, they delegate the async work to `MermaidRenderer` rather than calling `mermaid.render()` directly. This pattern works for any async extension — keep the async logic in a component and use the snippet for layout customization.

## General Pattern

The same pattern works for any marked extension:

1. **Install** the extension package (or the optional peer for built-ins like `katex` / `mermaid`)
2. **Discover** the token type names — check the extension's `extensions[].name` fields, or use the `parsed` callback to inspect tokens
3. **Pass** the extension via the `extensions` prop
4. **Render** the custom tokens — either map the token type name(s) to Svelte components via `renderers`, or use inline `{#snippet tokenName(props)}` overrides
5. **Include** any required CSS or external resources

The token type `name` is the key that connects everything: it's what the extension calls the token, what you use as the `renderers` key, and what you use as the snippet name.

## Extension Ecosystem

The [marked ecosystem](https://marked.js.org/using_advanced#extensions) includes extensions for:

- **Math**: `markedKatex` (built-in), `marked-mathjax`
- **Alerts/Admonitions**: `markedAlert` (built-in), custom GFM-style alerts
- **Diagrams**: `markedMermaid` (built-in), wrappers around PlantUML, etc.
- **Syntax highlighting**: `marked-highlight`
- **Custom containers**: `marked-custom-heading-id`, `markedFootnote` (built-in)

Any extension that adds custom token types can be integrated using the pattern above.

## Related

- [KaTeX Interactive Demo](/examples/marked-extensions) -- try KaTeX math rendering live with both component and snippet approaches
- [Mermaid Interactive Demo](/examples/mermaid) -- try async Mermaid diagram rendering with a custom marked extension
- [Custom Renderers](/docs/renderers/custom-renderers) -- override built-in markdown renderers
- [Types & Exports](/docs/api/types) -- `RendererComponent`, `Renderers` type definitions

<!-- Source: https://markdown.svelte.page/docs/advanced/security -->

# Security

> Review security guidance for @humanspeak/svelte-markdown, including XSS protection, URL and attribute sanitization, HTML filtering, and safe usage.

**Source:** [https://markdown.svelte.page/docs/advanced/security](https://markdown.svelte.page/docs/advanced/security)

---

`@humanspeak/svelte-markdown` renders markdown content into HTML. When processing user-generated markdown, it is important to understand the security implications and how to protect against cross-site scripting (XSS) and other injection attacks.

## Built-in URL and Attribute Sanitization

The library includes **built-in sanitization** that runs in the Parser before tokens reach any renderer component or snippet. This means custom renderers and Svelte 5 snippets cannot bypass it.

### URL Sanitization

By default, all `href` values on markdown links and images are validated against a protocol allowlist. Only safe protocols are permitted:

- `http:` and `https:`
- `mailto:` and `tel:`
- Relative URLs (`/path`, `#anchor`, `?query`, `./relative`)

Dangerous protocols like `javascript:`, `data:`, `vbscript:`, and `blob:` are blocked automatically.

```markdown
<!-- This link will have its href stripped -->
[Click me](javascript:alert('XSS'))

<!-- This link renders normally -->
[Click me](https://example.com)
```

### HTML Attribute Sanitization

For raw HTML within markdown, the default sanitizer:

1. **Strips all event handler attributes** (`onclick`, `onerror`, `onload`, etc.)
2. **Validates URL-bearing attributes** (`href`, `src`, `action`, `formaction`, `cite`, `data`, `poster`) against the same protocol allowlist

```html
<!-- onclick is stripped, javascript: href is blocked -->
<a href="javascript:alert('XSS')" onclick="alert('XSS')">Click</a>

<!-- Safe attributes are preserved -->
<a href="https://example.com" class="link">Click</a>
```

### Context-Aware Overrides

Both sanitization functions receive a context object with the token `type` and HTML `tag` name, so you can implement per-element policies:

```svelte
<script>
    import SvelteMarkdown, { defaultSanitizeUrl } from '@humanspeak/svelte-markdown'

    const markdown = '![diagram](data:image/png;base64,iVBORw0KGgo...) and [external](javascript:alert(1))'

    // Allow data: URIs only on images, block everywhere else
    function customSanitizeUrl(url, { type, tag }) {
        if (tag === 'img' && url.startsWith('data:image/')) return url
        return defaultSanitizeUrl(url, { type, tag })
    }
</script>

<SvelteMarkdown source={markdown} sanitizeUrl={customSanitizeUrl} />
```

### Custom Attribute Sanitization

Override `sanitizeAttributes` to apply per-tag attribute rules:

```svelte
<script>
    import SvelteMarkdown, {
        defaultSanitizeAttributes,
        defaultSanitizeUrl
    } from '@humanspeak/svelte-markdown'

    const markdown = '<iframe src="https://example.com" onload="alert(1)"></iframe>'

    // Block all attributes on iframes, use defaults for everything else
    function customSanitizeAttributes(attributes, context, sanitizeUrl) {
        if (context.tag === 'iframe') return {}
        return defaultSanitizeAttributes(attributes, context, sanitizeUrl)
    }
</script>

<SvelteMarkdown
    source={markdown}
    sanitizeAttributes={customSanitizeAttributes}
/>
```

### Disabling Sanitization

If you fully trust your markdown source and need to allow all URLs and attributes, use the passthrough functions:

```svelte
<script>
    import SvelteMarkdown, {
        unsanitizedUrl,
        unsanitizedAttributes
    } from '@humanspeak/svelte-markdown'

    // Only use passthrough sanitizers when the source is fully trusted
    // (e.g. your own CMS, never user input).
    const trustedContent = '# Internal doc\n\n<iframe src="/internal/dashboard"></iframe>'
</script>

<SvelteMarkdown
    source={trustedContent}
    sanitizeUrl={unsanitizedUrl}
    sanitizeAttributes={unsanitizedAttributes}
/>
```

> **Warning:** Only disable sanitization for content you fully control. Never use passthrough functions with user-generated input.

### Sanitization API Reference

| Export | Type | Description |
|--------|------|-------------|
| `defaultSanitizeUrl` | `SanitizeUrlFn` | Protocol allowlist (http, https, mailto, tel, relative) |
| `defaultSanitizeAttributes` | `SanitizeAttributesFn` | Strips `on*` handlers, validates URL attributes |
| `unsanitizedUrl` | `SanitizeUrlFn` | Passthrough -- allows all URLs |
| `unsanitizedAttributes` | `SanitizeAttributesFn` | Passthrough -- allows all attributes |
| `SanitizeUrlFn` | Type | `(url: string, context: SanitizeContext) => string` |
| `SanitizeAttributesFn` | Type | `(attributes: Record<string, string>, context: SanitizeContext, sanitizeUrl: SanitizeUrlFn) => Record<string, string>` |
| `SanitizeContext` | Type | `{ type: string, tag: string }` |

## Known Gaps (Not Handled by Defaults)

The built-in sanitizer covers URL protocols and event handlers, but some classes of risk pass through and need either custom sanitizers or HTML tag filtering:

- **Inline `style="..."` attributes are not sanitized.** They pass through unchanged (only `on*` and `srcdoc` are stripped). Modern browsers do not execute JavaScript via CSS, but visual hijacking (`display: none`) and exfiltration via background-image URLs are possible.
- **`<iframe>`, `<form>`, and `<embed>` are rendered by default.** With `on*` and `srcdoc` stripped and `src`/`action` protocol-restricted, the worst exploits are blocked, but an iframe to an arbitrary `http(s)` URL is still possible. Use `excludeHtmlOnly(['iframe', 'form', 'embed'])` to remove them.
- **`srcset` and other less common URL attributes are not sanitized.** Only `href`, `src`, `action`, `formaction`, `cite`, `data`, and `poster` flow through `sanitizeUrl`. Provide a custom `sanitizeAttributes` if you need broader coverage.
- **No bundled DOM sanitizer.** By design, the package does not ship DOMPurify or equivalent. For fully untrusted input, layer one on top of the defaults below.

For trusted sources like your own AI agent output, the built-in defaults are typically sufficient. For arbitrary user-generated markdown, combine the defaults with HTML tag filtering and/or external sanitization.

## Blocking HTML in Markdown

For additional defense, you can block HTML tags entirely using the [allow/deny filtering](/docs/advanced/allow-deny) utilities. This is complementary to URL/attribute sanitization.

### Block All HTML

```svelte
<script>
    import SvelteMarkdown, { buildUnsupportedHTML } from '@humanspeak/svelte-markdown'

    let userInput = $state('# User content\n\n<script>alert(1)</' + 'script>')

    const renderers = {
        html: buildUnsupportedHTML()
    }
</script>

<SvelteMarkdown source={userInput} {renderers} />
```

This replaces every HTML tag renderer with `UnsupportedHTML`, which renders nothing. Markdown syntax (headings, lists, emphasis, etc.) still works normally.

### Allow Only Safe Tags

```svelte
<script>
    import SvelteMarkdown, { allowHtmlOnly } from '@humanspeak/svelte-markdown'

    let userInput = $state('Hello <strong>world</strong> <iframe src="https://example.com"></iframe>')

    const safeHtml = allowHtmlOnly([
        'strong', 'em', 'a', 'code', 'pre',
        'ul', 'ol', 'li', 'p', 'br', 'hr',
        'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
        'blockquote', 'table', 'thead', 'tbody',
        'tr', 'th', 'td'
    ])
</script>

<SvelteMarkdown source={userInput} renderers={{ html: safeHtml }} />
```

### Block Specific Dangerous Tags

```svelte
<script>
    import SvelteMarkdown, { excludeHtmlOnly } from '@humanspeak/svelte-markdown'

    let userInput = $state('Click <a href="https://example.com">here</a> <iframe src="x"></iframe>')

    const filteredHtml = excludeHtmlOnly([
        'iframe', 'embed', 'form', 'input',
        'textarea', 'select', 'button',
        'canvas', 'dialog'
    ])
</script>

<SvelteMarkdown source={userInput} renderers={{ html: filteredHtml }} />
```

## Restricting Markdown Elements

You can also restrict which markdown elements are rendered:

```svelte
<script>
    import SvelteMarkdown, {
        allowRenderersOnly,
        buildUnsupportedHTML
    } from '@humanspeak/svelte-markdown'

    let userInput = $state('# Heading\n\n**Bold** and *italic* with a [link](https://example.com).')

    // Only allow basic text formatting
    const renderers = {
        ...allowRenderersOnly([
            'paragraph', 'text', 'strong', 'em',
            'link', 'list', 'listitem', 'br'
        ]),
        html: buildUnsupportedHTML()
    }
</script>

<SvelteMarkdown source={userInput} {renderers} />
```

## External Sanitization

For applications that require additional protection, you can sanitize the markdown source before passing it to `SvelteMarkdown`. Note that input-level sanitizers like DOMPurify operate on HTML, not Markdown syntax -- they will not catch Markdown-native injection vectors like `[Click](javascript:alert('XSS'))`. The built-in URL sanitization handles this automatically.

### Using DOMPurify (Combined with Built-in Sanitization)

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import DOMPurify from 'dompurify'

    let rawInput = $state('')

    // DOMPurify handles HTML-level threats
    // Built-in sanitization handles Markdown-native threats
    const sanitized = $derived(
        DOMPurify.sanitize(rawInput, { ALLOWED_TAGS: [] })
    )
</script>

<SvelteMarkdown source={sanitized} />
```

### Using the `parsed` Callback

You can inspect and filter tokens after parsing:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    let userInput = $state('Plain markdown is safe, but <div>raw HTML</div> may not be.')

    function handleParsed(tokens) {
        // Inspect tokens for suspicious content
        const htmlTokens = tokens.filter(t => t.type === 'html')
        if (htmlTokens.length > 0) {
            console.warn('HTML detected in markdown input:', htmlTokens)
        }
    }
</script>

<SvelteMarkdown source={userInput} parsed={handleParsed} />
```

## Security Recommendations

### For user-generated content:

1. **Use the built-in sanitization** (enabled by default). This blocks dangerous URL protocols and event handler attributes.
2. **Block all HTML** using `buildUnsupportedHTML()` for the strictest protection.
3. If you need some HTML, use `allowHtmlOnly()` with a strict allowlist of safe tags.
4. Consider combining with DOMPurify for defense-in-depth.

### For trusted content (CMS, documentation, etc.):

1. The default sanitization is generally sufficient for trusted sources.
2. Use `excludeHtmlOnly()` to block specific tags you do not want (e.g., `iframe`, `form`).

### General best practices:

1. **Validate input on the server.** Client-side filtering adds defense-in-depth but should not be your only protection.
2. **Use Content Security Policy (CSP) headers.** Restrict inline scripts and other dangerous behaviors at the browser level.
3. **Keep dependencies updated.** Regularly update `@humanspeak/svelte-markdown`, Marked, and HTMLParser2 to get security fixes.
4. **Audit your custom renderers.** If you create custom renderers, make sure they do not use `{@html}` with untrusted content.

## What About ``) rather than executing or applying them. HTMLParser2 processes HTML structurally and does not execute scripts on its own.

This means dangerous content is visible but inert. For untrusted input you should still block or sanitize HTML — escaped script text in a document is rarely the user experience you want.

## Related

- [Allow/Deny Filtering](/docs/advanced/allow-deny) -- detailed filtering function documentation
- [HTML Renderers](/docs/renderers/html-renderers) -- all HTML tag renderers
- [HTML Filtering Examples](/docs/examples/html-filtering) -- practical filtering examples

<!-- Source: https://markdown.svelte.page/docs/advanced/token-caching -->

# Token Caching

> Use built-in LRU token caching in @humanspeak/svelte-markdown to speed repeat renders, tune TTL and cache size, and inspect parse performance.

**Source:** [https://markdown.svelte.page/docs/advanced/token-caching](https://markdown.svelte.page/docs/advanced/token-caching)

---

`@humanspeak/svelte-markdown` includes a built-in LRU (Least Recently Used) token cache that dramatically improves performance for repeated renders of the same markdown content. When you pass a string to the `source` prop, the parsed tokens are automatically cached and reused on subsequent renders.

Under the hood, the caching layer is powered by [`@humanspeak/memory-cache`](https://www.npmjs.com/package/@humanspeak/memory-cache) -- a generic in-memory cache with TTL expiration and LRU eviction. `TokenCache` extends the `MemoryCache` class from that package, adding markdown-specific convenience methods on top. You get all the battle-tested caching primitives (size limits, TTL, LRU eviction) for free.

## Performance Characteristics

| Operation | Time |
|-----------|------|
| Cache hit (cached content) | &lt; 1ms |
| Cache miss (fresh parse) | 50-200ms (depends on document size) |
| Hash computation (10KB doc) | ~0.05ms |
| Hash computation (100KB doc) | ~0.5ms |
| Memory usage (50 cached docs) | ~5MB |

This means cached re-renders are **50-200x faster** than fresh parsing.

## How It Works

1. When `SvelteMarkdown` receives a string `source`, it generates a cache key from the source content and parser options using a fast FNV-1a hash.
2. It checks the global `tokenCache` singleton for a cached entry.
3. On a cache hit, the cached tokens are returned immediately without parsing.
4. On a cache miss, the markdown is parsed via Marked's lexer, and the resulting tokens are stored in the cache.
5. When the cache reaches its `maxSize`, the least recently used entry is evicted.
6. Entries automatically expire after the configured TTL (time-to-live).

Pre-parsed token arrays passed to `source` bypass the cache entirely.

## Default Configuration

The global `tokenCache` singleton is created with these defaults:

| Setting | Default | Description |
|---------|---------|-------------|
| `maxSize` | `50` | Maximum number of cached documents |
| `ttl` | `300000` (5 minutes) | Time-to-live in milliseconds |

## Using the Global Cache

The global singleton is shared across all `SvelteMarkdown` instances in your application:

```typescript
import { tokenCache } from '@humanspeak/svelte-markdown'

// Check how many documents are cached
console.log(tokenCache.size)

// Clear all cached tokens
tokenCache.clearAllTokens()

// Check if specific content is cached
const isCached = tokenCache.hasTokens(markdownString, { gfm: true })

// Manually retrieve cached tokens
const tokens = tokenCache.getTokens(markdownString, { gfm: true })

// Manually cache tokens
tokenCache.setTokens(markdownString, { gfm: true }, parsedTokens)

// Remove a specific cached entry
tokenCache.deleteTokens(markdownString, { gfm: true })
```

## Creating a Custom TokenCache

If you need different cache settings (e.g., for a high-traffic application or memory-constrained environment), you can create your own `TokenCache` instance:

```typescript
import { TokenCache } from '@humanspeak/svelte-markdown'

const customCache = new TokenCache({
    maxSize: 200,          // Cache more documents
    ttl: 15 * 60 * 1000   // 15-minute TTL
})
```

## TokenCache API

`TokenCache` extends `MemoryCache<Token[] | TokensList>` and adds markdown-specific convenience methods.

### Constructor

```typescript
new TokenCache(options?: { maxSize?: number; ttl?: number })
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `maxSize` | `number` | `50` | Maximum number of cached documents |
| `ttl` | `number` | `300000` | Time-to-live in milliseconds |

### Methods

#### `getTokens(source, options)`

Retrieve cached tokens for the given source and options. Returns `undefined` if not cached or expired.

```typescript
const tokens = cache.getTokens(markdown, options)
```

#### `setTokens(source, options, tokens)`

Store parsed tokens in the cache. If the cache is full, the least recently used entry is evicted.

```typescript
cache.setTokens(markdown, options, tokens)
```

#### `hasTokens(source, options)`

Check whether tokens are cached without retrieving them.

```typescript
if (cache.hasTokens(markdown, options)) {
    console.log('Cache hit')
}
```

#### `deleteTokens(source, options)`

Remove a specific cached entry. Returns `true` if the entry was removed, `false` if not found.

```typescript
cache.deleteTokens(markdown, options)
```

#### `clearAllTokens()`

Remove all entries from the cache.

```typescript
cache.clearAllTokens()
```

### Inherited from MemoryCache

`TokenCache` inherits all methods from [`MemoryCache`](https://www.npmjs.com/package/@humanspeak/memory-cache) (`@humanspeak/memory-cache`), including:

- `get(key)` -- retrieve by raw key
- `set(key, value)` -- store by raw key
- `has(key)` -- check existence by raw key
- `delete(key)` -- remove by raw key
- `clear()` -- remove all entries
- `size` -- number of cached entries

## Cache Key Generation

Cache keys are generated by hashing both the source content and the parser options:

```
key = hash(source) + ":" + hash(JSON.stringify(options))
```

This ensures that the same markdown parsed with different options (e.g., `gfm: true` vs `gfm: false`) produces separate cache entries.

The hash function uses FNV-1a, a fast non-cryptographic hash algorithm optimized for speed and good distribution. It operates in a single pass through the string.

## When Caching Is Bypassed

Caching is automatically bypassed in these cases:

- **Pre-parsed tokens**: When `source` is an array of `Token[]`, no parsing or caching occurs.
- **Empty string**: When `source` is `''`, an empty array is returned directly.

## Best Practices

1. **Let the default cache work for you.** In most applications, the global singleton with its default settings is sufficient.

2. **Increase `maxSize` for content-heavy apps.** If your application renders many unique markdown documents, increase the cache size to reduce re-parsing.

3. **Reduce TTL for dynamic content.** If your markdown content changes frequently, use a shorter TTL to avoid serving stale cached tokens.

4. **Use `clearAllTokens()` when content updates.** If you know the source content has changed (e.g., after a CMS update), clear the cache to force re-parsing.

5. **Pre-parse tokens for static content.** For content that never changes, parse it once and pass the tokens directly to avoid cache overhead entirely.

## Related

- [SvelteMarkdown Component](/docs/api/svelte-markdown) -- main component documentation
- [Types & Exports](/docs/api/types) -- `TokenCache`, `MemoryCache`, `tokenCache` exports

<!-- Source: https://markdown.svelte.page/docs/advanced/tree-shaking -->

# Tree Shaking

> Keep @humanspeak/svelte-markdown bundles lean with subpath imports, optional peer dependencies, and bundler practices for KaTeX and Mermaid.

**Source:** [https://markdown.svelte.page/docs/advanced/tree-shaking](https://markdown.svelte.page/docs/advanced/tree-shaking)

---

`@humanspeak/svelte-markdown` is designed so the core markdown component does not force optional extension payloads into your app. The easiest way to keep that true in your own bundle is to import the narrowest entrypoint that matches what you actually render.

## Recommended Imports

For plain markdown, import only the component:

```svelte
<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown/SvelteMarkdown'
</script>

<SvelteMarkdown source={markdown} />
```

Use the root package when you need helpers, types, sanitizer utilities, or renderer maps from the public API:

```svelte
<script lang="ts">
    import SvelteMarkdown, { allowHtmlOnly } from '@humanspeak/svelte-markdown'

    const html = allowHtmlOnly(['strong', 'em', 'a', 'code'])
</script>

<SvelteMarkdown source={markdown} renderers={{ html }} />
```

For extensions, prefer the extension family subpath:

```svelte
<script lang="ts">
    import { markedKatex, KatexRenderer } from '@humanspeak/svelte-markdown/extensions/katex'
    import { markedMermaid, MermaidRenderer } from '@humanspeak/svelte-markdown/extensions/mermaid'
</script>
```

The compatibility barrel still works:

```ts
import { markedKatex, KatexRenderer } from '@humanspeak/svelte-markdown/extensions'
```

Use it when convenience matters more than a visibly narrow import. For bundle-sensitive code, the family subpaths make your intent clearer to both people and bundlers.

## Optional Peer Payloads

The extension tokenizers are small parser helpers. The renderer components are where heavy optional peers enter.

| Import | Pulls heavy peer into initial bundle? | Notes |
|--------|---------------------------------------|-------|
| `@humanspeak/svelte-markdown/SvelteMarkdown` | No | Core component only. |
| `markedKatex` from `/extensions/katex` | No | Tokenizes math; does not import `katex`. |
| `KatexRenderer` from `/extensions/katex` | Yes, `katex` | Uses `katex.renderToString()` synchronously. |
| `markedMermaid` from `/extensions/mermaid` | No | Tokenizes Mermaid fences; does not import `mermaid`. |
| `MermaidRenderer` from `/extensions/mermaid` | No initial `mermaid` chunk | Dynamically imports Mermaid in the browser. |

This means you can parse math or diagrams without paying for the renderer until you actually import the renderer path. If you provide your own renderer or snippet, your imports decide what ships.

## Environment Best Practices

### SvelteKit and Vite

Use ESM imports and leave dependency pre-bundling to Vite. Avoid importing every extension from the compatibility barrel in shared modules if a route only needs one family.

```svelte
<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown/SvelteMarkdown'
    import { markedKatex, KatexRenderer } from '@humanspeak/svelte-markdown/extensions/katex'

    const extensions = [markedKatex()]
    const renderers = {
        inlineKatex: KatexRenderer,
        blockKatex: KatexRenderer
    }
</script>
```

If only one route needs KaTeX or Mermaid, import those renderers in that route or route-level component instead of a shared app shell.

### SSR

`KatexRenderer` is synchronous and works during SSR. `MermaidRenderer` is browser-only internally: it waits for mount, then dynamically imports Mermaid and renders the diagram. That keeps Mermaid out of the server render path and out of the initial client graph.

For server-rendered pages that must avoid any client-side Mermaid work, use `markedMermaid()` with a custom placeholder renderer or snippet and hydrate a diagram component only where needed.

### Custom Renderers and Snippets

Tree shaking follows your imports. If a snippet imports `katex`, the page that owns the snippet pays for KaTeX:

```svelte
<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown/SvelteMarkdown'
    import { markedKatex } from '@humanspeak/svelte-markdown/extensions/katex'
    import katex from 'katex'
</script>

<SvelteMarkdown source={markdown} extensions={[markedKatex()]}>
    {#snippet inlineKatex(props)}
        {@html katex.renderToString(props.text, { throwOnError: false })}
    {/snippet}
</SvelteMarkdown>
```

That is fine when the route needs math. Keep that import out of routes that do not.

### Lazy Route Loading

For apps with a documentation or content area, put markdown features behind route-level imports. A marketing page that renders plain markdown does not need to share the same module that imports math, diagrams, footnotes, and alerts.

```ts
// Good: math route owns its math renderer import.
import { markedKatex, KatexRenderer } from '@humanspeak/svelte-markdown/extensions/katex'

// Avoid in app-wide modules unless every page needs every extension.
import {
    AlertRenderer,
    FootnoteRef,
    FootnoteSection,
    KatexRenderer,
    MermaidRenderer
} from '@humanspeak/svelte-markdown/extensions'
```

## Checking Your Bundle

For Vite apps, inspect the production bundle after a build:

```bash
npm run build
```

For the most reliable report, add a Rollup visualizer plugin to your app build and confirm:

- Plain markdown routes do not include KaTeX or Mermaid.
- KaTeX appears only where `KatexRenderer`, `katex`, or a math snippet imports it.
- Mermaid appears behind a dynamic chunk when using `MermaidRenderer`.

As a quick heuristic, you can also search generated client assets for distinctive library strings. These text checks may need adjustment for your minifier or build output:

```bash
grep -R "KaTeX" .svelte-kit/output/client/_app
grep -R "mermaid" .svelte-kit/output/client/_app
```

The package also has an internal verification script:

```bash
pnpm test:tree-shaking
```

That script builds small consumer entries and checks that the published subpaths behave as expected.

## Related Pages

- [Marked Extensions](/docs/advanced/marked-extensions) -- KaTeX, Mermaid, alerts, footnotes, and custom extension setup
- [Token Caching](/docs/advanced/token-caching) -- parser cache behavior and extension identity
- [SvelteMarkdown API](/docs/api/svelte-markdown) -- component props and public imports

<!-- Source: https://markdown.svelte.page/docs/api/svelte-markdown -->

# SvelteMarkdown Component

> Use the SvelteMarkdown component API: props, renderers, snippets, extensions, parsed callbacks, inline mode, token input, and TypeScript types.

**Source:** [https://markdown.svelte.page/docs/api/svelte-markdown](https://markdown.svelte.page/docs/api/svelte-markdown)

---

The `SvelteMarkdown` component is the main entry point for rendering markdown content. It accepts a markdown string (or pre-parsed tokens), parses it, and renders the result through a composable system of Svelte renderer components.

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
</script>

<SvelteMarkdown source="# Hello World" />
```

## Props

### `source`

- **Type:** `string | Token[]`
- **Default:** `[]`

The markdown content to render. Can be either a raw markdown string or an array of pre-parsed [Marked tokens](https://marked.js.org/using_pro#lexer).

When a string is provided, it is parsed using Marked's lexer (with built-in token caching for performance). When pre-parsed tokens are provided, parsing is skipped entirely.

When using the imperative streaming API (`bind:this` + `writeChunk()`), `source` must be a string. Token-array sources remain read-only.

```svelte
<!-- String source -->
<SvelteMarkdown source="**Bold** and *italic*" />

<!-- Pre-parsed tokens -->
<SvelteMarkdown source={myTokens} />
```

### `renderers`

- **Type:** `Partial<Renderers>`
- **Default:** `{}`

An object mapping renderer keys to custom Svelte components. Any keys you provide will override the corresponding default renderer. Keys you omit will use the built-in defaults.

The `renderers` object supports two categories of keys:

1. **Markdown renderer keys** (e.g., `heading`, `paragraph`, `link`, `code`) -- see [Markdown Renderers](/docs/renderers/markdown-renderers)
2. **`html`** -- an object mapping HTML tag names to components -- see [HTML Renderers](/docs/renderers/html-renderers)

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import CustomHeading from './CustomHeading.svelte'
    import CustomLink from './CustomLink.svelte'

    const source = '# Title\n\n[Click here](https://example.com)'
</script>

<SvelteMarkdown
    {source}
    renderers={{
        heading: CustomHeading,
        link: CustomLink
    }}
/>
```

To override HTML tag renderers within markdown, use the nested `html` key:

```svelte
<SvelteMarkdown
    {source}
    renderers={{
        html: {
            div: CustomDiv,
            span: CustomSpan
        }
    }}
/>
```

When you provide a partial `html` object, it is merged with the defaults -- your overrides replace only the tags you specify, and all other HTML tags continue using their built-in renderers.

### `options`

- **Type:** `Partial<SvelteMarkdownOptions>`
- **Default:** `{}`

Configuration options for the markdown parser. These are merged with the default options.

```svelte
<SvelteMarkdown
    source={markdown}
    options={{
        headerIds: true,
        headerPrefix: 'section-',
        gfm: true,
        breaks: true
    }}
/>
```

#### Available Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `headerIds` | `boolean` | `true` | Generate `id` attributes on heading elements using [github-slugger](https://github.com/Flet/github-slugger) |
| `headerPrefix` | `string` | `''` | String to prepend to generated heading IDs |
| `gfm` | `boolean` | `true` | Enable [GitHub Flavored Markdown](https://github.github.com/gfm/) (tables, strikethrough, task lists, etc.) |
| `breaks` | `boolean` | `false` | Convert single newlines in paragraphs to `<br>` elements |

The options object also passes through Marked's own configuration properties such as `async`, `pedantic`, `silent`, `tokenizer`, and `walkTokens`.

### `isInline`

- **Type:** `boolean`
- **Default:** `false`

When set to `true`, the markdown is parsed as inline content. This means block-level elements like headings, paragraphs, lists, and blockquotes are not produced. Only inline elements such as bold, italic, links, code spans, and images are rendered.

This is useful when you want to embed markdown within a `<span>` or other inline HTML context.

```svelte
<p>
    Status: <SvelteMarkdown source="**Active** since *2024*" isInline={true} />
</p>
```

### `streaming`

- **Type:** `boolean`
- **Default:** `false`

Enables optimized rendering for LLM streaming scenarios. When `true`, the component diffs parsed tokens against the previous result and only updates changed DOM nodes, keeping render cost proportional to the change rather than the full document size.

```svelte
<SvelteMarkdown {source} streaming={true} />
```

`streaming` also enables the component instance methods described below.

**Note:** `streaming` is automatically disabled when async extensions are used. A console warning is logged in this case.

See [LLM Streaming](/docs/advanced/llm-streaming) for usage patterns and performance data.

## Instance Methods

When you bind the component instance, `SvelteMarkdown` exposes imperative helpers for streaming writers:

### `writeChunk(chunk)`

- **Type:** `(chunk: StreamingChunk) => void`

Accepts either a string append chunk or an offset patch object:

```svelte
<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import type { StreamingChunk } from '@humanspeak/svelte-markdown'

    let markdown:
        | {
              writeChunk: (chunk: StreamingChunk) => void
              resetStream: (nextSource?: string) => void
          }
        | undefined

    function onChunk(chunk: StreamingChunk) {
        markdown?.writeChunk(chunk)
    }
</script>

<SvelteMarkdown bind:this={markdown} source="" streaming={true} />
```

Rules:

- String chunks append to the internal buffer.
- Object chunks use `{ value, offset }` overwrite semantics, not insert semantics.
- Offset writes preserve trailing content after the overwritten span.
- If `offset` skips ahead, the gap is padded with spaces.
- Offset mode does not support delete or truncate semantics.
- The first successful write locks the stream into append mode or offset mode until reset.
- Offset chunks require a non-negative safe integer `offset`.
- Calls are ignored with a warning when `streaming={false}`, async extensions are active, or `source` is a token array.

### `resetStream(nextSource?)`

- **Type:** `(nextSource?: string) => void`

Clears the internal streaming buffer and resets mode locking. Pass a string to seed the next stream:

```typescript
markdown?.resetStream()
markdown?.resetStream('# Seed')
```

Changing the `source` prop also resets the imperative buffer and becomes the new baseline.

### `parsed`

- **Type:** `(tokens: Token[] | TokensList) => void`
- **Default:** `() => {}`

A callback function that is invoked with the parsed token array whenever the source is parsed. This is useful for inspecting the token tree, building a table of contents, or performing other analysis on the parsed output.

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    let headings = $state([])

    function handleParsed(tokens) {
        headings = tokens
            .filter(t => t.type === 'heading')
            .map(t => ({ depth: t.depth, text: t.text }))
    }
</script>

<SvelteMarkdown source={markdown} parsed={handleParsed} />

<nav>
    {#each headings as h}
        <a href="#{h.text}">{h.text} (h{h.depth})</a>
    {/each}
</nav>
```

The callback fires reactively via a Svelte `$effect` -- it will be called again whenever the tokens change (e.g., when `source` changes).

## Default Options

The full set of default options applied when no `options` prop is provided:

```typescript
const defaultOptions: SvelteMarkdownOptions = {
    async: false,
    breaks: false,
    gfm: true,
    pedantic: false,
    renderer: null,
    silent: false,
    tokenizer: null,
    walkTokens: null,
    headerIds: true,
    headerPrefix: ''
}
```

## Token Caching

When you pass a string to `source`, the component automatically caches parsed tokens using an internal LRU cache. On subsequent renders with the same source and options, the cached tokens are returned in under 1ms instead of re-parsing (which can take 50-200ms for large documents).

The cache is a global singleton (`tokenCache`) shared across all `SvelteMarkdown` instances. It defaults to 50 entries with a 5-minute TTL. See [Token Caching](/docs/advanced/token-caching) for advanced configuration.

When you pass pre-parsed tokens to `source`, caching is bypassed entirely.

## Renderer Merging

The component merges your custom renderers with the defaults:

```typescript
// Internal behavior
const combinedRenderers = {
    ...defaultRenderers,
    ...renderers,
    html: renderers.html
        ? { ...defaultRenderers.html, ...renderers.html }
        : defaultRenderers.html
}
```

This means:
- Top-level renderer keys you provide replace the defaults
- Top-level renderer keys you omit use the built-in components
- For `html`, your overrides are merged with the default HTML renderer map

## Complete Example

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import CustomHeading from './CustomHeading.svelte'
    import CustomCode from './CustomCode.svelte'

    let source = $state('# Hello\n\n```js\nconsole.log("hi")\n```')
    let tokens = $state([])
</script>

<SvelteMarkdown
    {source}
    renderers={{
        heading: CustomHeading,
        code: CustomCode
    }}
    options={{
        headerIds: true,
        headerPrefix: 'doc-',
        gfm: true
    }}
    parsed={(t) => tokens = t}
/>

<p>Parsed {tokens.length} tokens</p>
```

## Related

- [Types & Exports](/docs/api/types) -- all exported types, functions, and constants
- [Markdown Renderers](/docs/renderers/markdown-renderers) -- list of all 24 renderer keys
- [Custom Renderers](/docs/renderers/custom-renderers) -- guide to building custom components
- [Token Caching](/docs/advanced/token-caching) -- cache configuration and performance

<!-- Source: https://markdown.svelte.page/docs/api/types -->

# Types & Exports

> Explore exported types, functions, constants, cache classes, renderer keys, and utility helpers from @humanspeak/svelte-markdown for Svelte 5.

**Source:** [https://markdown.svelte.page/docs/api/types](https://markdown.svelte.page/docs/api/types)

---

This page documents every named export from `@humanspeak/svelte-markdown`. The package provides a default export (the component) plus types, utility functions, constants, and cache classes.

## Default Export

### `SvelteMarkdown`

The main component. See [SvelteMarkdown Component](/docs/api/svelte-markdown) for full documentation.

```typescript
import SvelteMarkdown from '@humanspeak/svelte-markdown'
```

## Types

### `SvelteMarkdownProps<T>`

The props interface for the `SvelteMarkdown` component.

```typescript
type SvelteMarkdownProps<T extends Renderers = Renderers> = {
    source: Token[] | string
    renderers?: Partial<T>
    options?: Partial<SvelteMarkdownOptions>
    extensions?: MarkedExtension[]
    isInline?: boolean
    streaming?: boolean
    parsed?: (tokens: Token[] | TokensList) => void
}
```

### `StreamingOffsetChunk`

Offset patch payload for imperative streaming writes.

```typescript
interface StreamingOffsetChunk {
    value: string
    offset: number
}
```

### `StreamingChunk`

Union accepted by `writeChunk()`.

```typescript
type StreamingChunk = string | StreamingOffsetChunk
```

### `SvelteMarkdownOptions`

Configuration options for the markdown parser. Extends Marked's `MarkedOptions` with additional properties.

```typescript
interface SvelteMarkdownOptions extends MarkedOptions {
    headerIds?: boolean
    headerPrefix?: string
}
```

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `headerIds` | `boolean` | `true` | Generate `id` attributes on heading elements |
| `headerPrefix` | `string` | `''` | Prefix prepended to generated heading IDs |
| `gfm` | `boolean` | `true` | Enable GitHub Flavored Markdown |
| `breaks` | `boolean` | `false` | Convert newlines to `<br>` |

Plus all properties from Marked's `MarkedOptions` (e.g., `async`, `pedantic`, `silent`, `tokenizer`, `walkTokens`).

### `Renderers`

A type mapping every markdown renderer key to a `RendererComponent`. Includes the special `html` key that maps to `HtmlRenderers`.

```typescript
type Renderers = {
    html: HtmlRenderers

    // Raw text
    rawtext: RendererComponent
    escape: RendererComponent

    // Block elements
    heading: RendererComponent
    paragraph: RendererComponent
    blockquote: RendererComponent
    code: RendererComponent
    list: RendererComponent
    listitem: RendererComponent
    hr: RendererComponent

    // Table elements
    table: RendererComponent
    tablehead: RendererComponent
    tablebody: RendererComponent
    tablerow: RendererComponent
    tablecell: RendererComponent

    // Inline elements
    text: RendererComponent
    link: RendererComponent
    image: RendererComponent
    em: RendererComponent
    strong: RendererComponent
    codespan: RendererComponent
    br: RendererComponent
    del: RendererComponent

    // List variations
    orderedlistitem: RendererComponent
    unorderedlistitem: RendererComponent
}
```

### `HtmlRenderers`

A string-keyed record mapping HTML tag names to Svelte components (or `null`).

```typescript
interface HtmlRenderers {
    [key: string]: Component<any, any, any> | null
}
```

### `RendererComponent`

The type for any individual renderer -- a Svelte component, `undefined`, or `null`.

```typescript
type RendererComponent = Component<any, any, any> | undefined | null
```

### `Token`

Re-exported from [Marked](https://marked.js.org/). Represents a single parsed markdown token.

```typescript
import type { Token } from '@humanspeak/svelte-markdown'
```

### `TokensList`

Re-exported from Marked. An array of tokens with additional metadata (e.g., `links`).

```typescript
import type { TokensList } from '@humanspeak/svelte-markdown'
```

## Constants

### `defaultRenderers`

The default renderer map used by `SvelteMarkdown` when no `renderers` prop is provided. This is the complete `Renderers` object with all 24 markdown renderers and the `html` map.

```typescript
import { defaultRenderers } from '@humanspeak/svelte-markdown'

// Inspect the default heading renderer
console.log(defaultRenderers.heading)

// Use as a base for partial overrides
const myRenderers = {
    ...defaultRenderers,
    heading: MyCustomHeading
}
```

### `rendererKeys`

An array of all valid markdown renderer key names (excluding `html`). Useful for iteration or validation.

```typescript
import { rendererKeys } from '@humanspeak/svelte-markdown'

console.log(rendererKeys)
// ['heading', 'paragraph', 'text', 'image', 'link', 'em', 'escape',
//  'strong', 'codespan', 'del', 'table', 'tablehead', 'tablebody',
//  'tablerow', 'tablecell', 'list', 'orderedlistitem',
//  'unorderedlistitem', 'listitem', 'hr', 'blockquote', 'code',
//  'br', 'rawtext']
```

### `htmlRendererKeys`

An array of all valid HTML renderer tag names.

```typescript
import { htmlRendererKeys } from '@humanspeak/svelte-markdown'

console.log(htmlRendererKeys)
// ['a', 'abbr', 'address', 'article', 'aside', 'audio', 'b', ...]
```

## Components

### `Html`

The default HTML renderer map object. Maps HTML tag names to their corresponding Svelte components.

```typescript
import { Html } from '@humanspeak/svelte-markdown'

// Access the default <div> renderer
const DivRenderer = Html.div
```

### `UnsupportedHTML`

A component that renders nothing. Used as a placeholder when an HTML tag is blocked via allow/deny filtering.

```typescript
import { UnsupportedHTML } from '@humanspeak/svelte-markdown'
```

### `Unsupported`

A component that renders nothing. Used as a placeholder when a markdown renderer is blocked via allow/deny filtering.

```typescript
import { Unsupported } from '@humanspeak/svelte-markdown'
```

## HTML Filtering Functions

These functions produce `HtmlRenderers` objects for controlling which HTML tags are rendered. See [Allow/Deny](/docs/advanced/allow-deny) for detailed usage.

### `allowHtmlOnly(allowed)`

Returns an `HtmlRenderers` map where only the specified tags use their default (or custom) components. All other tags are set to `UnsupportedHTML`.

```typescript
import { allowHtmlOnly } from '@humanspeak/svelte-markdown'

// Only allow <strong>, <em>, and <a>
const html = allowHtmlOnly(['strong', 'em', 'a'])

// Allow <div> with a custom component
const html = allowHtmlOnly([['div', MyDiv], 'a'])
```

**Signature:**

```typescript
function allowHtmlOnly(
    allowed: Array<HtmlKey | [HtmlKey, Component | null]>
): HtmlRenderers
```

### `excludeHtmlOnly(excluded, overrides?)`

Returns an `HtmlRenderers` map where the specified tags are set to `UnsupportedHTML`. All other tags use their defaults (or optional custom overrides).

```typescript
import { excludeHtmlOnly } from '@humanspeak/svelte-markdown'

// Block <iframe> and <script>
const html = excludeHtmlOnly(['iframe'])

// Block <iframe>, override <a> with custom component
const html = excludeHtmlOnly(['iframe'], [['a', CustomA]])
```

**Signature:**

```typescript
function excludeHtmlOnly(
    excluded: HtmlKey[],
    overrides?: Array<[HtmlKey, Component | null]>
): HtmlRenderers
```

### `buildUnsupportedHTML()`

Returns an `HtmlRenderers` map where every HTML tag is set to `UnsupportedHTML`. Useful as a starting point when you want to disable all HTML rendering.

```typescript
import { buildUnsupportedHTML } from '@humanspeak/svelte-markdown'

const html = buildUnsupportedHTML()
```

## Renderer Filtering Functions

These functions produce partial `Renderers` objects (excluding `html`) for controlling which markdown elements are rendered. See [Allow/Deny](/docs/advanced/allow-deny) for detailed usage.

### `allowRenderersOnly(allowed)`

Returns a renderer map where only the specified keys use their default (or custom) components. All other keys are set to `Unsupported`.

```typescript
import { allowRenderersOnly } from '@humanspeak/svelte-markdown'

// Only allow paragraphs and links
const renderers = allowRenderersOnly(['paragraph', 'link'])

// Allow paragraph with a custom component
const renderers = allowRenderersOnly([['paragraph', MyParagraph]])
```

**Signature:**

```typescript
function allowRenderersOnly(
    allowed: Array<RendererKey | [RendererKey, RendererComponent]>
): Omit<Renderers, 'html'>
```

### `excludeRenderersOnly(excluded, overrides?)`

Returns a renderer map where the specified keys are set to `Unsupported`. All other keys use their defaults (or optional overrides).

```typescript
import { excludeRenderersOnly } from '@humanspeak/svelte-markdown'

// Disable images and code blocks
const renderers = excludeRenderersOnly(['image', 'code'])
```

**Signature:**

```typescript
function excludeRenderersOnly(
    excluded: RendererKey[],
    overrides?: Array<[RendererKey, RendererComponent]>
): Omit<Renderers, 'html'>
```

### `buildUnsupportedRenderers()`

Returns a renderer map where every markdown renderer key is set to `Unsupported`.

```typescript
import { buildUnsupportedRenderers } from '@humanspeak/svelte-markdown'

const renderers = buildUnsupportedRenderers()
```

## Cache Utilities

### `MemoryCache`

A generic in-memory cache class with TTL expiration and LRU eviction. Used internally by `TokenCache`.

```typescript
import { MemoryCache } from '@humanspeak/svelte-markdown'

const cache = new MemoryCache<string>({
    maxSize: 100,
    ttl: 5 * 60 * 1000
})

cache.set('key', 'value')
const value = cache.get('key') // 'value'
```

### `TokenCache`

A specialized cache class for markdown tokens, built on `MemoryCache`. Provides convenience methods for storing and retrieving parsed tokens keyed by source content and parser options.

```typescript
import { TokenCache } from '@humanspeak/svelte-markdown'

const cache = new TokenCache({
    maxSize: 100,       // Cache up to 100 documents
    ttl: 10 * 60 * 1000 // 10-minute TTL
})
```

See [Token Caching](/docs/advanced/token-caching) for full documentation.

### `tokenCache`

The global singleton `TokenCache` instance used internally by all `SvelteMarkdown` components. Defaults to 50 entries with a 5-minute TTL.

```typescript
import { tokenCache } from '@humanspeak/svelte-markdown'

// Check cache statistics
console.log(tokenCache.size)

// Clear all cached tokens
tokenCache.clearAllTokens()
```

## Import Summary

```typescript
// Default export
import SvelteMarkdown from '@humanspeak/svelte-markdown'

// Named exports -- components & constants
import {
    Html,
    UnsupportedHTML,
    Unsupported,
    defaultRenderers,
    rendererKeys,
    htmlRendererKeys
} from '@humanspeak/svelte-markdown'

// Named exports -- filtering functions
import {
    allowHtmlOnly,
    excludeHtmlOnly,
    buildUnsupportedHTML,
    allowRenderersOnly,
    excludeRenderersOnly,
    buildUnsupportedRenderers
} from '@humanspeak/svelte-markdown'

// Named exports -- cache utilities
import {
    MemoryCache,
    TokenCache,
    tokenCache
} from '@humanspeak/svelte-markdown'

// Type exports
import type {
    HtmlRenderers,
    RendererComponent,
    Renderers,
    StreamingChunk,
    StreamingOffsetChunk,
    SvelteMarkdownOptions,
    SvelteMarkdownProps,
    Token,
    TokensList
} from '@humanspeak/svelte-markdown'
```

<!-- Source: https://markdown.svelte.page/docs/examples/basic-rendering -->

# Basic Rendering

> Learn common @humanspeak/svelte-markdown rendering patterns for strings, token arrays, reactive updates, SvelteKit usage, and default output.

**Source:** [https://markdown.svelte.page/docs/examples/basic-rendering](https://markdown.svelte.page/docs/examples/basic-rendering)

---

These examples demonstrate common usage patterns for rendering markdown with `@humanspeak/svelte-markdown`.

## Simple Markdown String

The most basic usage -- pass a markdown string to the `source` prop:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
# Welcome

This is a paragraph with **bold**, *italic*, and ~~strikethrough~~ text.

- Item one
- Item two
- Item three
    `
</script>

<SvelteMarkdown {source} />
```

## Reactive Source

Bind the `source` prop to a reactive variable so the rendered output updates automatically:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    let source = $state('# Hello\n\nStart typing...')
</script>

<textarea bind:value={source} rows="6" cols="60"></textarea>
<SvelteMarkdown {source} />
```

## Headings with IDs

By default, headings receive auto-generated `id` attributes (via [github-slugger](https://github.com/Flet/github-slugger)):

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
# Introduction
## Getting Started
### Installation
## Usage
### Basic Example
    `
</script>

<!-- Headings get ids: "introduction", "getting-started", "installation", etc. -->
<SvelteMarkdown {source} />
```

Add a prefix to all heading IDs:

```svelte
<SvelteMarkdown
    {source}
    options={{ headerIds: true, headerPrefix: 'doc-' }}
/>
<!-- IDs: "doc-introduction", "doc-getting-started", etc. -->
```

Disable heading IDs entirely:

```svelte
<SvelteMarkdown {source} options={{ headerIds: false }} />
```

## Links

Markdown links render as `<a>` elements:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
Visit [Svelte](https://svelte.dev) and [GitHub](https://github.com "GitHub Homepage").
    `
</script>

<SvelteMarkdown {source} />
```

## Images

Images are rendered with lazy loading and fade-in effects by default:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
![Alt text](https://picsum.photos/400/200 "Photo caption")
    `
</script>

<SvelteMarkdown {source} />
```

## Code Blocks

Fenced code blocks include the language as a CSS class for syntax highlighting integration:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = "```javascript\nconst x = 42;\nconsole.log(x);\n```"
</script>

<SvelteMarkdown {source} />
<!-- Renders: <pre class="javascript"><code>...</code></pre> -->
```

## Inline Code

Inline code renders within `<code>` elements:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = 'Use the `console.log()` function to debug.'
</script>

<SvelteMarkdown {source} />
```

## Tables (GFM)

GitHub Flavored Markdown tables are supported when `gfm` is enabled (the default):

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
| Name    | Type     | Default |
|---------|----------|---------|
| source  | string   | ""      |
| isInline | boolean | false   |
| gfm     | boolean  | true    |
    `
</script>

<SvelteMarkdown {source} />
```

Tables support column alignment:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
| Left | Center | Right |
|:-----|:------:|------:|
| A    |   B    |     C |
| D    |   E    |     F |
    `
</script>

<SvelteMarkdown {source} />
```

## Blockquotes

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
> This is a blockquote.
>
> It can span multiple paragraphs.
    `
</script>

<SvelteMarkdown {source} />
```

## Ordered and Unordered Lists

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
Unordered list:

- First item
- Second item
  - Nested item
- Third item

Ordered list:

1. Step one
2. Step two
3. Step three
    `
</script>

<SvelteMarkdown {source} />
```

## Line Breaks

Enable `breaks` to convert single newlines to `<br>` elements:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `Line one
Line two
Line three`
</script>

<!-- Without breaks: all on one line -->
<SvelteMarkdown {source} />

<!-- With breaks: each line separated by <br> -->
<SvelteMarkdown {source} options={{ breaks: true }} />
```

## Horizontal Rules

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
Section one

---

Section two
    `
</script>

<SvelteMarkdown {source} />
```

## Mixed Content

A complete example combining multiple markdown features:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
# Project Documentation

## Overview

This project uses **Svelte 5** with *TypeScript* support.

## Installation

\`\`\`bash
npm install @humanspeak/svelte-markdown
\`\`\`

## Features

| Feature | Status |
|---------|--------|
| Markdown | Supported |
| HTML | Supported |
| GFM | Supported |

> **Note:** All features are enabled by default.

## Links

- [Documentation](/docs)
- [GitHub](https://github.com/humanspeak/svelte-markdown)

---

*Built with @humanspeak/svelte-markdown*
    `
</script>

<SvelteMarkdown {source} />
```

## Related

- [Getting Started](/docs/getting-started) -- installation and setup
- [SvelteMarkdown API](/docs/api/svelte-markdown) -- full component reference
- [Inline Rendering Examples](/docs/examples/inline-rendering) -- using `isInline`

<!-- Source: https://markdown.svelte.page/docs/examples/custom-renderers -->

# Custom Renderers Examples

> See practical custom renderer examples for @humanspeak/svelte-markdown, including links, code blocks, images, typed props, and reusable components.

**Source:** [https://markdown.svelte.page/docs/examples/custom-renderers](https://markdown.svelte.page/docs/examples/custom-renderers)

---

These examples demonstrate how to create custom renderers to change the way specific markdown elements are rendered.

## Open External Links in New Tab

Create a link renderer that opens external links in a new tab:

```svelte
<!-- ExternalLink.svelte -->
<script lang="ts">
    import type { Snippet } from 'svelte'

    interface Props {
        href?: string
        title?: string
        children?: Snippet
    }

    const { href = '', title = undefined, children }: Props = $props()

    const isExternal = $derived(
        href.startsWith('http://') || href.startsWith('https://')
    )
</script>

{#if isExternal}
    <a {href} {title} target="_blank" rel="noopener noreferrer">
        {@render children?.()}
        <span class="external-icon"> &#x2197;</span>
    </a>
{:else}
    <a {href} {title}>
        {@render children?.()}
    </a>
{/if}
```

```svelte
<!-- Usage -->
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import ExternalLink from './ExternalLink.svelte'

    const source = `
- [Internal link](/about)
- [External link](https://svelte.dev)
    `
</script>

<SvelteMarkdown {source} renderers={{ link: ExternalLink }} />
```

## Syntax-Highlighted Code Blocks

Integrate a syntax highlighter (e.g., Prism or Highlight.js) into a custom code renderer:

```svelte
<!-- HighlightedCode.svelte -->
<script lang="ts">
    import { onMount } from 'svelte'

    interface Props {
        lang: string
        text: string
    }

    const { lang, text }: Props = $props()

    let codeElement: HTMLElement
    let highlighted = $state(false)

    onMount(async () => {
        // Example using Prism.js (if loaded globally)
        if (typeof Prism !== 'undefined' && lang) {
            const grammar = Prism.languages[lang]
            if (grammar && codeElement) {
                codeElement.innerHTML = Prism.highlight(text, grammar, lang)
                highlighted = true
            }
        }
    })
</script>

<div class="code-wrapper">
    {#if lang}
        <span class="lang-badge">{lang}</span>
    {/if}
    <pre class={lang}><code
        bind:this={codeElement}
        class="language-{lang}"
        class:highlighted
    >{text}</code></pre>
</div>
```

```svelte
<!-- Usage -->
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import HighlightedCode from './HighlightedCode.svelte'
</script>

<SvelteMarkdown
    source={"```typescript\nconst x: number = 42;\n```"}
    renderers={{ code: HighlightedCode }}
/>
```

## Headings with Anchor Links

Add clickable anchor links to headings for easy sharing:

```svelte
<!-- AnchorHeading.svelte -->
<script lang="ts">
    import type { Snippet } from 'svelte'
    import type { SvelteMarkdownOptions } from '@humanspeak/svelte-markdown'

    interface Props {
        depth: number
        raw: string
        text: string
        options: SvelteMarkdownOptions
        slug: (val: string) => string
        children?: Snippet
    }

    const { depth, text, options, slug, children }: Props = $props()

    const id = $derived(
        options.headerIds ? options.headerPrefix + slug(text) : undefined
    )
</script>

<svelte:element this="h{depth}" {id}>
    {@render children?.()}
    {#if id}
        <a href="#{id}" aria-label="Link to {text}" class="anchor">
            #
        </a>
    {/if}
</svelte:element>
```

## Styled Blockquotes

Transform blockquotes into styled callout boxes:

```svelte
<!-- Callout.svelte -->
<script lang="ts">
    import type { Snippet } from 'svelte'

    interface Props {
        children?: Snippet
    }

    const { children }: Props = $props()
</script>

<aside class="callout" role="note">
    <div class="callout-bar"></div>
    <div class="callout-content">
        {@render children?.()}
    </div>
</aside>

<style>
    .callout {
        display: flex;
        margin: 1em 0;
        border-radius: 6px;
        background: #f8f9fa;
        overflow: hidden;
    }
    .callout-bar {
        width: 4px;
        background: #3b82f6;
        flex-shrink: 0;
    }
    .callout-content {
        padding: 12px 16px;
    }
</style>
```

```svelte
<SvelteMarkdown
    source={"> Important information here"}
    renderers={{ blockquote: Callout }}
/>
```

## Custom Table with Styling

Wrap tables in a scrollable container:

```svelte
<!-- ScrollableTable.svelte -->
<script lang="ts">
    import type { Snippet } from 'svelte'

    interface Props {
        children?: Snippet
    }

    const { children }: Props = $props()
</script>

<div class="table-container">
    <table>
        {@render children?.()}
    </table>
</div>

<style>
    .table-container {
        overflow-x: auto;
        margin: 1em 0;
        border: 1px solid #e2e8f0;
        border-radius: 8px;
    }
    table {
        width: 100%;
        border-collapse: collapse;
    }
</style>
```

## Combining Multiple Custom Renderers

Pass multiple custom renderers at once:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import ExternalLink from './ExternalLink.svelte'
    import AnchorHeading from './AnchorHeading.svelte'
    import HighlightedCode from './HighlightedCode.svelte'
    import Callout from './Callout.svelte'
    import ScrollableTable from './ScrollableTable.svelte'

    const source = `
# Welcome

> This is a callout.

Visit [Svelte](https://svelte.dev) for more info.

| Column A | Column B |
|----------|----------|
| Data 1   | Data 2   |

\`\`\`javascript
console.log('Hello!')
\`\`\`
    `
</script>

<SvelteMarkdown
    {source}
    renderers={{
        heading: AnchorHeading,
        link: ExternalLink,
        code: HighlightedCode,
        blockquote: Callout,
        table: ScrollableTable
    }}
/>
```

## Related

- [Custom Renderers Guide](/docs/renderers/custom-renderers) -- detailed guide to building renderers
- [Markdown Renderers](/docs/renderers/markdown-renderers) -- all renderer props
- [HTML Filtering Examples](/docs/examples/html-filtering) -- filtering HTML tags

<!-- Source: https://markdown.svelte.page/docs/examples/html-filtering -->

# HTML Filtering Examples

> Filter HTML tags in markdown content with @humanspeak/svelte-markdown examples for blocking all HTML, allow-listing tags, and deny-list rules.

**Source:** [https://markdown.svelte.page/docs/examples/html-filtering](https://markdown.svelte.page/docs/examples/html-filtering)

---

These examples demonstrate how to use the allow/deny filtering utilities to control which HTML tags are rendered within markdown content.

## Block All HTML

The safest option for user-generated content -- block all raw HTML while preserving markdown syntax:

```svelte
<script>
    import SvelteMarkdown, { buildUnsupportedHTML } from '@humanspeak/svelte-markdown'

    const source = `
# Heading

This paragraph has **markdown** that works.

<div>This HTML is blocked.</div>

<script>alert('blocked')<\/script>

More **markdown** continues here.
    `

    const renderers = {
        html: buildUnsupportedHTML()
    }
</script>

<SvelteMarkdown {source} {renderers} />
<!-- The <div> and <script> tags produce no output -->
<!-- Markdown headings, bold, etc. render normally -->
```

## Allow Only Specific Tags

Allow only a curated set of safe HTML tags:

```svelte
<script>
    import SvelteMarkdown, { allowHtmlOnly } from '@humanspeak/svelte-markdown'

    const source = `
Text with <strong>bold HTML</strong> and <em>italic HTML</em>.

<div class="custom">This div is blocked.</div>

<a href="https://example.com">This link works.</a>

<iframe src="https://evil.com"></iframe>
    `

    const renderers = {
        html: allowHtmlOnly(['strong', 'em', 'a', 'code', 'br'])
    }
</script>

<SvelteMarkdown {source} {renderers} />
<!-- strong, em, a, code, br render normally -->
<!-- div, iframe, and all other tags are suppressed -->
```

## Block Specific Tags

Block only the tags you consider dangerous, allowing everything else:

```svelte
<script>
    import SvelteMarkdown, { excludeHtmlOnly } from '@humanspeak/svelte-markdown'

    const source = `
<div>This div renders normally.</div>

<p>Paragraphs work too.</p>

<iframe src="https://example.com">Blocked!</iframe>

<form action="/submit"><input type="text" /></form>
    `

    const renderers = {
        html: excludeHtmlOnly([
            'iframe',
            'embed',
            'form',
            'input',
            'textarea',
            'select',
            'button',
            'canvas'
        ])
    }
</script>

<SvelteMarkdown {source} {renderers} />
<!-- div, p render normally -->
<!-- iframe, form, input are suppressed -->
```

## Allow Tags with Custom Components

Use the tuple syntax to allow specific tags and render them with custom Svelte components:

```svelte
<!-- SafeLink.svelte -->
<script lang="ts">
    import type { Snippet } from 'svelte'

    const { href, children, ...rest }: any = $props()

    // Force all links to open in new tab
    const safeHref = $derived(
        href?.startsWith('javascript:') ? '#' : href
    )
</script>

<a href={safeHref} target="_blank" rel="noopener noreferrer" {...rest}>
    {@render children?.()}
</a>
```

```svelte
<!-- Usage -->
<script>
    import SvelteMarkdown, { allowHtmlOnly } from '@humanspeak/svelte-markdown'
    import SafeLink from './SafeLink.svelte'

    const source = `
<a href="https://example.com">Safe external link</a>

<a href="javascript:alert('xss')">Blocked javascript: link</a>

<strong>Bold is allowed</strong>

<iframe src="https://evil.com">Blocked</iframe>
    `

    const renderers = {
        html: allowHtmlOnly([
            ['a', SafeLink],
            'strong',
            'em',
            'code'
        ])
    }
</script>

<SvelteMarkdown {source} {renderers} />
```

## Combine HTML and Markdown Filtering

Restrict both HTML tags and markdown renderers for maximum control:

```svelte
<script>
    import SvelteMarkdown, {
        allowHtmlOnly,
        allowRenderersOnly
    } from '@humanspeak/svelte-markdown'

    const source = `
# Heading (allowed)

![Image](photo.jpg) (blocked)

**Bold** and *italic* work.

\`\`\`
Code blocks are blocked.
\`\`\`

<div>HTML div is blocked.</div>

<em>HTML emphasis is allowed.</em>
    `

    const renderers = {
        // Only allow basic markdown renderers
        ...allowRenderersOnly([
            'paragraph', 'text', 'heading',
            'strong', 'em', 'link', 'br',
            'list', 'listitem'
        ]),
        // Only allow safe HTML tags
        html: allowHtmlOnly(['strong', 'em', 'a', 'br'])
    }
</script>

<SvelteMarkdown {source} {renderers} />
<!-- Images, code blocks, HTML divs are all suppressed -->
<!-- Headings, paragraphs, bold, italic, and safe HTML render -->
```

## Exclude with Overrides

Block specific tags while providing custom components for others:

```svelte
<script>
    import SvelteMarkdown, { excludeHtmlOnly } from '@humanspeak/svelte-markdown'
    import SafeLink from './SafeLink.svelte'

    const source = `
<a href="https://example.com">Custom link component</a>

<iframe src="bad.html">Blocked</iframe>

<div>Default div renderer</div>
    `

    const renderers = {
        html: excludeHtmlOnly(
            ['iframe', 'embed', 'form'],       // Block these
            [['a', SafeLink]]                   // Override <a> with custom component
        )
    }
</script>

<SvelteMarkdown {source} {renderers} />
<!-- iframe is blocked -->
<!-- <a> uses SafeLink component -->
<!-- <div> uses the default div renderer -->
```

## Related

- [Allow/Deny](/docs/advanced/allow-deny) -- API reference for all filtering functions
- [Security](/docs/advanced/security) -- security best practices
- [HTML Renderers](/docs/renderers/html-renderers) -- all 69+ HTML tag renderers

<!-- Source: https://markdown.svelte.page/docs/examples/inline-rendering -->

# Inline Rendering

> Render inline markdown with @humanspeak/svelte-markdown using the isInline prop for span-friendly text, links, emphasis, and compact UI contexts.

**Source:** [https://markdown.svelte.page/docs/examples/inline-rendering](https://markdown.svelte.page/docs/examples/inline-rendering)

---

The `isInline` prop tells `SvelteMarkdown` to parse the source as inline markdown rather than block-level markdown. This is useful when you want to render markdown within a `<span>`, `<p>`, or other inline HTML context without producing block-level elements like `<p>`, `<h1>`, or `<ul>`.

## Block vs Inline Parsing

By default, markdown is parsed as block content, which wraps text in `<p>` tags:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
</script>

<!-- Block parsing (default) -->
<SvelteMarkdown source="**Bold** and *italic*" />
<!-- Renders: <p><strong>Bold</strong> and <em>italic</em></p> -->

<!-- Inline parsing -->
<SvelteMarkdown source="**Bold** and *italic*" isInline={true} />
<!-- Renders: <strong>Bold</strong> and <em>italic</em> -->
```

Notice that inline parsing does not wrap the output in a `<p>` tag.

## Embedding Markdown in Text

Use `isInline` when you need to embed formatted text inside a paragraph or other inline container:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const status = '**Active**'
    const description = 'This feature is *experimental* and may change.'
</script>

<p>
    Status: <SvelteMarkdown source={status} isInline={true} />
</p>

<span>
    Note: <SvelteMarkdown source={description} isInline={true} />
</span>
```

## Dynamic Labels

Render user-provided markdown in places where block elements would break the layout:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const items = [
        { label: '**Important:** Review needed', status: 'pending' },
        { label: '*Optional:* Style updates', status: 'done' },
        { label: '`v2.0` Release notes', status: 'in-progress' }
    ]
</script>

<table>
    <thead>
        <tr><th>Item</th><th>Status</th></tr>
    </thead>
    <tbody>
        {#each items as item}
            <tr>
                <td>
                    <SvelteMarkdown source={item.label} isInline={true} />
                </td>
                <td>{item.status}</td>
            </tr>
        {/each}
    </tbody>
</table>
```

## What Inline Parsing Supports

When `isInline` is `true`, the following markdown elements are supported:

- **Bold** (`**text**`)
- **Italic** (`*text*`)
- **Strikethrough** (`~~text~~`)
- **Code spans** (`` `code` ``)
- **Links** (`[text](url)`)
- **Images** (`![alt](url)`)
- **Line breaks** (two trailing spaces or `\`)

The following block-level elements are **not** produced in inline mode:

- Headings (`# ...`)
- Paragraphs (no `<p>` wrapper)
- Lists (`-`, `1.`)
- Blockquotes (`> ...`)
- Code blocks (` ``` `)
- Tables
- Horizontal rules (`---`)

## Inline with Custom Renderers

Custom renderers work normally in inline mode:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import CustomLink from './CustomLink.svelte'
</script>

<p>
    Check out <SvelteMarkdown
        source="[our docs](https://example.com)"
        isInline={true}
        renderers={{ link: CustomLink }}
    />
</p>
```

## Related

- [SvelteMarkdown API](/docs/api/svelte-markdown) -- full prop documentation
- [Basic Rendering Examples](/docs/examples/basic-rendering) -- standard block rendering
- [Parsed Callback Examples](/docs/examples/parsed-callback) -- inspecting tokens

<!-- Source: https://markdown.svelte.page/docs/examples/linked-headings -->

# Linked Headings Examples

> Add clickable anchor links to markdown headings with @humanspeak/svelte-markdown using snippet overrides, custom renderers, and slugged IDs.

**Source:** [https://markdown.svelte.page/docs/examples/linked-headings](https://markdown.svelte.page/docs/examples/linked-headings)

---

By default, `@humanspeak/svelte-markdown` renders headings with `id` attributes (via `headerIds` option) but no clickable anchor links. Documentation sites commonly want headings that users can click or hover to get a permalink. Here are several approaches.

## Snippet Override (Recommended)

The simplest approach — add a hover-reveal `#` link after each heading inline:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
## Getting Started
Some intro text.

## Installation
Install the package.

## Usage
Use the component.
    `
</script>

<SvelteMarkdown {source}>
    {#snippet heading({ depth, text, slug, options, children })}
        {@const id = options.headerIds ? options.headerPrefix + slug(text) : undefined}
        <svelte:element this="h{depth}" {id} class="group relative">
            {@render children?.()}
            {#if id}
                <a
                    href="#{id}"
                    class="ml-2 opacity-0 group-hover:opacity-100 transition-opacity"
                    aria-label="Link to {text}"
                >
                    #
                </a>
            {/if}
        </svelte:element>
    {/snippet}
</SvelteMarkdown>
```

The `slug` function (from `github-slugger`) and `options` object are passed as snippet props. The `id` is computed the same way the built-in `Heading.svelte` renderer does it.

## Custom Renderer Component

For reuse across multiple pages, create a dedicated component:

```svelte
<!-- LinkedHeading.svelte -->
<script lang="ts">
    import type { Snippet } from 'svelte'
    import type { SvelteMarkdownOptions } from '@humanspeak/svelte-markdown'

    interface Props {
        depth: number
        raw: string
        text: string
        options: SvelteMarkdownOptions
        slug: (val: string) => string
        children?: Snippet
    }

    const { depth, raw, text, options, slug, children }: Props = $props()

    const id = $derived(options.headerIds ? options.headerPrefix + slug(text) : undefined)
</script>

<svelte:element this="h{depth}" {id} class="group relative">
    {@render children?.()}
    {#if id}
        <a
            href="#{id}"
            class="ml-2 opacity-0 group-hover:opacity-100 transition-opacity"
            aria-label="Link to {text}"
        >
            #
        </a>
    {/if}
</svelte:element>
```

Then use it via the `renderers` prop:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import LinkedHeading from './LinkedHeading.svelte'
</script>

<SvelteMarkdown {source} renderers={{ heading: LinkedHeading }} />
```

## Variation: Always-Visible Link Icon

Instead of a hover-reveal `#`, show a subtle link icon that's always visible:

```svelte
<SvelteMarkdown {source}>
    {#snippet heading({ depth, text, slug, options, children })}
        {@const id = options.headerIds ? options.headerPrefix + slug(text) : undefined}
        <svelte:element this="h{depth}" {id}>
            {@render children?.()}
            {#if id}
                <a href="#{id}" class="ml-2 text-gray-400 hover:text-gray-600" aria-label="Link to {text}">
                    🔗
                </a>
            {/if}
        </svelte:element>
    {/snippet}
</SvelteMarkdown>
```

## Variation: Wrapping Heading in a Link

Wrap the entire heading text in an `<a>` tag for a larger click target:

```svelte
<SvelteMarkdown {source}>
    {#snippet heading({ depth, text, slug, options, children })}
        {@const id = options.headerIds ? options.headerPrefix + slug(text) : undefined}
        <svelte:element this="h{depth}" {id} class="group">
            <a href={id ? `#${id}` : undefined} class="no-underline hover:underline text-inherit">
                {@render children?.()}
            </a>
        </svelte:element>
    {/snippet}
</SvelteMarkdown>
```

## Snippet Props Reference

The `heading` snippet receives these props from the built-in renderer:

| Prop | Type | Description |
|------|------|-------------|
| `depth` | `number` | Heading level (1–6) |
| `raw` | `string` | Original markdown source of the heading line |
| `text` | `string` | Plain-text content used for slug generation |
| `options` | `SvelteMarkdownOptions` | Parser options (controls `headerIds`, `headerPrefix`) |
| `slug` | `(val: string) => string` | Slugger function for generating heading IDs |
| `children` | `Snippet` | Rendered inline content of the heading |

## Related

- [Snippet Overrides Guide](/docs/renderers/snippet-overrides) — full documentation on snippet overrides
- [Snippet Overrides Examples](/docs/examples/snippet-overrides) — more snippet override patterns
- [Interactive Linked Headings Demo](/examples/linked-headings) — live playground

<!-- Source: https://markdown.svelte.page/docs/examples/parsed-callback -->

# Parsed Callback

> Use the parsed callback prop in @humanspeak/svelte-markdown to inspect token data, build tables of contents, count words, and analyze content.

**Source:** [https://markdown.svelte.page/docs/examples/parsed-callback](https://markdown.svelte.page/docs/examples/parsed-callback)

---

The `parsed` prop accepts a callback function that is invoked with the parsed token array whenever the markdown source is parsed. This is useful for building features on top of the token tree, such as tables of contents, word counts, or content analysis.

## Basic Usage

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    let tokenCount = $state(0)

    function handleParsed(tokens) {
        tokenCount = tokens.length
    }
</script>

<SvelteMarkdown source="# Hello **world**" parsed={handleParsed} />
<p>Token count: {tokenCount}</p>
```

## Building a Table of Contents

Extract headings from the parsed tokens to build a navigation sidebar:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
# Introduction
## Overview
## Getting Started
### Prerequisites
### Installation
## Usage
### Basic Example
### Advanced Example
## API Reference
    `

    let headings = $state([])

    function handleParsed(tokens) {
        headings = tokens
            .filter(token => token.type === 'heading')
            .map(token => ({
                depth: token.depth,
                text: token.text
            }))
    }
</script>

<div style="display: flex; gap: 2rem;">
    <nav>
        <h3>Contents</h3>
        <ul>
            {#each headings as heading}
                <li style="margin-left: {(heading.depth - 1) * 16}px">
                    <a href="#{heading.text.toLowerCase().replace(/\s+/g, '-')}">
                        {heading.text}
                    </a>
                </li>
            {/each}
        </ul>
    </nav>

    <article>
        <SvelteMarkdown {source} parsed={handleParsed} />
    </article>
</div>
```

## Word Count

Count the total words in the markdown content:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    let source = $state('# Hello World\n\nThis is a paragraph with several words.')
    let wordCount = $state(0)

    function countWords(tokens) {
        let text = ''
        function extractText(tokenList) {
            for (const token of tokenList) {
                if (token.text) {
                    text += ' ' + token.text
                }
                if (token.tokens) {
                    extractText(token.tokens)
                }
            }
        }
        extractText(tokens)
        wordCount = text.trim().split(/\s+/).filter(Boolean).length
    }
</script>

<textarea bind:value={source} rows="4" cols="60"></textarea>
<p>Words: {wordCount}</p>

<SvelteMarkdown {source} parsed={countWords} />
```

## Content Analysis

Analyze the structure of the parsed markdown:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
# Title

A paragraph with a [link](https://example.com) and **bold text**.

- List item 1
- List item 2

\`\`\`javascript
const x = 1
\`\`\`

> A blockquote
    `

    let analysis = $state({})

    function analyzeTokens(tokens) {
        const counts = {}
        for (const token of tokens) {
            counts[token.type] = (counts[token.type] || 0) + 1
        }
        analysis = counts
    }
</script>

<SvelteMarkdown {source} parsed={analyzeTokens} />

<h3>Token Analysis</h3>
<table>
    <thead>
        <tr><th>Token Type</th><th>Count</th></tr>
    </thead>
    <tbody>
        {#each Object.entries(analysis) as [type, count]}
            <tr>
                <td><code>{type}</code></td>
                <td>{count}</td>
            </tr>
        {/each}
    </tbody>
</table>
```

## Detecting HTML in User Input

Use the parsed callback to warn about HTML in user-generated content:

```svelte
<script>
    import SvelteMarkdown, { buildUnsupportedHTML } from '@humanspeak/svelte-markdown'

    let source = $state('')
    let hasHtml = $state(false)

    function checkForHtml(tokens) {
        hasHtml = tokens.some(token => token.type === 'html')
    }

    const renderers = {
        html: buildUnsupportedHTML()
    }
</script>

<textarea bind:value={source} rows="4" cols="60" placeholder="Enter markdown..."></textarea>

{#if hasHtml}
    <p style="color: orange;">
        Warning: HTML detected in input. HTML tags will not be rendered.
    </p>
{/if}

<SvelteMarkdown {source} parsed={checkForHtml} {renderers} />
```

## Reactive Updates

The `parsed` callback fires reactively via Svelte's `$effect`. It is called again whenever the parsed tokens change, which happens when:

- The `source` prop changes
- The `options` prop changes
- The `isInline` prop changes

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    let source = $state('# Hello')
    let lastParsed = $state(null)

    function handleParsed(tokens) {
        lastParsed = new Date().toLocaleTimeString()
        console.log('Parsed at:', lastParsed, 'Tokens:', tokens.length)
    }
</script>

<input bind:value={source} style="width: 100%;" />
<p>Last parsed: {lastParsed}</p>

<SvelteMarkdown {source} parsed={handleParsed} />
```

## Related

- [SvelteMarkdown API](/docs/api/svelte-markdown) -- full `parsed` prop documentation
- [Token Caching](/docs/advanced/token-caching) -- how tokens are cached
- [Types & Exports](/docs/api/types) -- `Token` and `TokensList` types

<!-- Source: https://markdown.svelte.page/docs/examples/snippet-overrides -->

# Snippet Overrides Examples

> Use Svelte 5 snippet overrides in @humanspeak/svelte-markdown to customize markdown rendering inline for links, code, images, and paragraphs.

**Source:** [https://markdown.svelte.page/docs/examples/snippet-overrides](https://markdown.svelte.page/docs/examples/snippet-overrides)

---

These examples demonstrate how to use Svelte 5 snippets to customize markdown rendering directly in your template, without creating separate component files.

## Basic Paragraph Styling

Add a class or wrapper to paragraphs with a simple snippet:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = 'This paragraph gets custom styling automatically.'
</script>

<SvelteMarkdown {source}>
    {#snippet paragraph({ children })}
        <p class="prose text-gray-700 leading-relaxed">
            {@render children?.()}
        </p>
    {/snippet}
</SvelteMarkdown>
```

## External Links with Icon

Open all links in a new tab and add a visual indicator:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
Check out [Svelte](https://svelte.dev) and [SvelteKit](https://kit.svelte.dev).
    `
</script>

<SvelteMarkdown {source}>
    {#snippet link({ href, title, children })}
        <a
            {href}
            {title}
            target="_blank"
            rel="noopener noreferrer"
            class="text-blue-600 underline hover:text-blue-800"
        >
            {@render children?.()}
            <span aria-hidden="true"> ↗</span>
        </a>
    {/snippet}
</SvelteMarkdown>
```

## Headings with Anchor Links

Add clickable anchor links to headings for easy deep-linking:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
## Getting Started
Some intro text.

## Installation
Install the package.

## Usage
Use the component.
    `
</script>

<SvelteMarkdown {source}>
    {#snippet heading({ depth, text, slug, options, children })}
        {@const id = options.headerIds ? options.headerPrefix + slug(text) : undefined}
        <svelte:element this="h{depth}" {id} class="group relative">
            {@render children?.()}
            {#if id}
                <a
                    href="#{id}"
                    class="ml-2 opacity-0 group-hover:opacity-100 transition-opacity"
                    aria-label="Link to {text}"
                >
                    #
                </a>
            {/if}
        </svelte:element>
    {/snippet}
</SvelteMarkdown>
```

## Code Blocks with Language Badge

Wrap code blocks with a language indicator:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = "```typescript\nconst greeting: string = 'Hello, Svelte!'\n```"
</script>

<SvelteMarkdown {source}>
    {#snippet code({ lang, text })}
        <div class="relative rounded-lg overflow-hidden border">
            {#if lang}
                <div class="absolute top-0 right-0 px-2 py-1 text-xs bg-gray-200 rounded-bl">
                    {lang}
                </div>
            {/if}
            <pre class="p-4 overflow-x-auto"><code>{text}</code></pre>
        </div>
    {/snippet}
</SvelteMarkdown>
```

## Callout-Style Blockquotes

Transform blockquotes into styled callout boxes:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = '> **Note:** This is an important callout with **bold** text inside.'
</script>

<SvelteMarkdown {source}>
    {#snippet blockquote({ children })}
        <aside class="flex gap-3 p-4 my-4 bg-blue-50 border-l-4 border-blue-500 rounded-r-lg" role="note">
            <span class="text-blue-500 font-bold shrink-0">ℹ</span>
            <div>{@render children?.()}</div>
        </aside>
    {/snippet}
</SvelteMarkdown>
```

## Custom List Markers

Replace default bullet points with custom markers:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
- First item
- Second item
- Third item
    `
</script>

<SvelteMarkdown {source}>
    {#snippet list({ ordered, children })}
        {#if ordered}
            <ol class="space-y-2">{@render children?.()}</ol>
        {:else}
            <ul class="space-y-2 list-none pl-0">{@render children?.()}</ul>
        {/if}
    {/snippet}

    {#snippet listitem({ children })}
        <li class="flex items-start gap-2">
            <span class="text-green-500 shrink-0">✓</span>
            <div>{@render children?.()}</div>
        </li>
    {/snippet}
</SvelteMarkdown>
```

## Responsive Tables

Wrap tables in a scrollable container with styling:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
| Feature | Status | Notes |
|---------|--------|-------|
| Snippets | ✅ Done | v0.9+ |
| Caching | ✅ Done | 50-200x faster |
| TypeScript | ✅ Done | Full support |
    `
</script>

<SvelteMarkdown {source}>
    {#snippet table({ children })}
        <div class="overflow-x-auto my-4 rounded-lg border border-gray-200 shadow-sm">
            <table class="w-full border-collapse">
                {@render children?.()}
            </table>
        </div>
    {/snippet}

    {#snippet tablecell({ header, align, children })}
        {#if header}
            <th class="bg-gray-50 px-4 py-3 text-left text-sm font-semibold" style:text-align={align}>
                {@render children?.()}
            </th>
        {:else}
            <td class="px-4 py-3 text-sm border-t" style:text-align={align}>
                {@render children?.()}
            </td>
        {/if}
    {/snippet}
</SvelteMarkdown>
```

## Images with Captions

Turn image titles into figure captions:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = "![A scenic mountain view](/mountain.jpg 'Photo taken in the Alps')"
</script>

<SvelteMarkdown {source}>
    {#snippet image({ href, title, text })}
        <figure class="my-6 text-center">
            <img
                src={href}
                alt={text}
                class="rounded-lg shadow-md max-w-full mx-auto"
                loading="lazy"
            />
            {#if title}
                <figcaption class="mt-2 text-sm text-gray-500 italic">
                    {title}
                </figcaption>
            {/if}
        </figure>
    {/snippet}
</SvelteMarkdown>
```

## HTML Tag Overrides

Override how raw HTML tags render using the `html_` prefix:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
<div class="alert">This is an alert box</div>

<a href="https://example.com">External link in HTML</a>
    `
</script>

<SvelteMarkdown {source}>
    {#snippet html_div({ attributes, children })}
        <div {...attributes} class="p-4 rounded-lg bg-yellow-50 border border-yellow-200">
            {@render children?.()}
        </div>
    {/snippet}

    {#snippet html_a({ attributes, children })}
        <a {...attributes} target="_blank" rel="noopener noreferrer" class="text-blue-600">
            {@render children?.()}
        </a>
    {/snippet}
</SvelteMarkdown>
```

## Multiple Overrides Together

Combine several snippet overrides for a fully customized rendering experience:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = `
# Project Update

Here's what changed this week:

- Implemented **snippet overrides** for inline customization
- Added [TypeScript types](https://www.typescriptlang.org/) for all props
- Fixed a bug in the \`Parser\` component

> **Tip:** Snippets are the fastest way to customize rendering.

\`\`\`javascript
const greeting = 'Hello from snippets!'
\`\`\`
    `
</script>

<SvelteMarkdown {source}>
    {#snippet heading({ depth, children })}
        <svelte:element this="h{depth}" class="font-bold text-gray-900 mb-4">
            {@render children?.()}
        </svelte:element>
    {/snippet}

    {#snippet paragraph({ children })}
        <p class="text-gray-700 leading-relaxed mb-4">{@render children?.()}</p>
    {/snippet}

    {#snippet link({ href, title, children })}
        <a {href} {title} target="_blank" rel="noopener noreferrer" class="text-blue-600 underline">
            {@render children?.()}
        </a>
    {/snippet}

    {#snippet blockquote({ children })}
        <aside class="border-l-4 border-blue-400 pl-4 my-4 italic text-gray-600">
            {@render children?.()}
        </aside>
    {/snippet}

    {#snippet code({ lang, text })}
        <pre class="bg-gray-900 text-green-400 p-4 rounded-lg overflow-x-auto my-4"><code>{text}</code></pre>
    {/snippet}

    {#snippet listitem({ children })}
        <li class="flex items-start gap-2 mb-1">
            <span class="text-blue-500">•</span>
            <div>{@render children?.()}</div>
        </li>
    {/snippet}
</SvelteMarkdown>
```

## Snippet vs Component Side-by-Side

The same customization as a snippet override vs a component renderer:

**Snippet approach** (inline, no extra file):
```svelte
<SvelteMarkdown {source}>
    {#snippet link({ href, title, children })}
        <a {href} {title} target="_blank" rel="noopener noreferrer">
            {@render children?.()}
        </a>
    {/snippet}
</SvelteMarkdown>
```

**Component approach** (separate file):
```svelte
<!-- ExternalLink.svelte -->
<script lang="ts">
    import type { Snippet } from 'svelte'

    interface Props {
        href?: string
        title?: string
        children?: Snippet
    }

    const { href = '', title = undefined, children }: Props = $props()
</script>

<a {href} {title} target="_blank" rel="noopener noreferrer">
    {@render children?.()}
</a>
```

```svelte
<!-- Usage -->
<SvelteMarkdown {source} renderers={{ link: ExternalLink }} />
```

Both produce the same result. Use snippets for simple, one-off overrides. Use component renderers when you need styles, state, lifecycle hooks, or reusability across pages.

## Related

- [Snippet Overrides Guide](/docs/renderers/snippet-overrides) -- full documentation
- [Custom Renderers Examples](/docs/examples/custom-renderers) -- component-based examples
- [Interactive Snippet Demo](/examples/snippet-overrides) -- live playground

<!-- Source: https://markdown.svelte.page/docs/getting-started -->

# Getting Started

> Get started fast with @humanspeak/svelte-markdown in Svelte 5: install the package, render markdown, enable TypeScript, and customize output.

**Source:** [https://markdown.svelte.page/docs/getting-started](https://markdown.svelte.page/docs/getting-started)

---

**@humanspeak/svelte-markdown** is a powerful, customizable markdown renderer for Svelte 5 with full TypeScript support. It parses markdown using [Marked](https://marked.js.org/) and renders it through a composable system of Svelte components that you can override and extend.

## Installation

Install the package using your preferred package manager:

```bash
npm install @humanspeak/svelte-markdown
```

```bash
pnpm add @humanspeak/svelte-markdown
```

```bash
yarn add @humanspeak/svelte-markdown
```

## Quick Start

Import the `SvelteMarkdown` component and pass your markdown string to the `source` prop:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = '# Hello World\n\nThis is **bold** and *italic* text.'
</script>

<SvelteMarkdown {source} />
```

This renders the markdown as HTML using the built-in default renderers.

## Basic Props

The `SvelteMarkdown` component accepts the following props:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `source` | `string \| Token[]` | `[]` | Markdown string or pre-parsed tokens to render |
| `renderers` | `Partial<Renderers>` | `{}` | Custom renderer components to override defaults |
| `options` | `Partial<SvelteMarkdownOptions>` | `{}` | Parser configuration options |
| `isInline` | `boolean` | `false` | Parse as inline markdown (no block-level elements) |
| `parsed` | `(tokens: Token[] \| TokensList) => void` | `() => {}` | Callback invoked with parsed tokens |

## Configuration Options

You can configure the markdown parser through the `options` prop:

```svelte
<SvelteMarkdown
    source="# Hello"
    options={{
        headerIds: true,
        headerPrefix: 'doc-',
        gfm: true,
        breaks: false
    }}
/>
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `headerIds` | `boolean` | `true` | Generate `id` attributes on headings |
| `headerPrefix` | `string` | `''` | Prefix for generated heading IDs |
| `gfm` | `boolean` | `true` | Enable GitHub Flavored Markdown |
| `breaks` | `boolean` | `false` | Convert single newlines to `<br>` |

## Overriding Renderers

You can replace any built-in renderer with your own Svelte component:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import CustomLink from './CustomLink.svelte'

    const source = 'Visit [example](https://example.com)'
</script>

<SvelteMarkdown {source} renderers={{ link: CustomLink }} />
```

## Features

- **Svelte 5** runes compatibility with `$props()` and `$derived()`
- **TypeScript** with complete type definitions for all exports
- **24 markdown renderers** covering all standard markdown elements
- **69+ HTML tag renderers** for raw HTML within markdown
- **Token caching** with LRU eviction for high-performance re-renders
- **Allow/deny filtering** to control which elements are rendered
- **Custom renderers** for full control over output

## Next Steps

- [SvelteMarkdown API Reference](/docs/api/svelte-markdown) -- full component documentation
- [Types & Exports](/docs/api/types) -- all exported types, functions, and constants
- [Markdown Renderers](/docs/renderers/markdown-renderers) -- the 24 built-in markdown renderers
- [Custom Renderers Guide](/docs/renderers/custom-renderers) -- how to build your own renderers
- [Token Caching](/docs/advanced/token-caching) -- performance optimization with caching
- [Basic Rendering Examples](/docs/examples/basic-rendering) -- common usage patterns

<!-- Source: https://markdown.svelte.page/docs/migration -->

# Migration Guide

> Migrate from svelte-markdown to @humanspeak/svelte-markdown for Svelte 5 with TypeScript support, token caching, streaming, and new renderer APIs.

**Source:** [https://markdown.svelte.page/docs/migration](https://markdown.svelte.page/docs/migration)

---

Migrate from the original `svelte-markdown` (by Pablo Berganza) to `@humanspeak/svelte-markdown` -- the actively maintained Svelte 5 successor.

## Why Migrate?

The original `svelte-markdown` package is no longer actively maintained and does not support Svelte 5. `@humanspeak/svelte-markdown` is a drop-in replacement that adds:

- **Svelte 5 support** -- built with runes (`$props`, `$derived`, `$state`)
- **Full TypeScript support** -- complete type definitions for all exports
- **Token caching** -- LRU cache for 50-200x faster re-renders
- **69+ HTML tag renderers** -- dedicated components for HTML within markdown
- **Allow/deny filtering** -- fine-grained control over rendered elements
- **Snippet overrides** -- customize rendering inline with Svelte 5 snippets
- **Marked extensions** -- KaTeX, Mermaid, and any marked extension via the `extensions` prop
- **Async parsing** -- support for async marked extensions
- **Active maintenance** -- regular updates, bug fixes, and new features

## Step-by-Step Migration

### 1. Update Dependencies

Remove the old package and install the new one:

```bash
# Remove old package
npm uninstall svelte-markdown

# Install new package
npm install @humanspeak/svelte-markdown
```

### 2. Update Imports

Find and replace all imports. Change this:

```javascript
import SvelteMarkdown from 'svelte-markdown'
```

To this:

```javascript
import SvelteMarkdown from '@humanspeak/svelte-markdown'
```

### 3. Update Svelte to Version 5

`@humanspeak/svelte-markdown` requires Svelte 5. If you haven't upgraded yet:

```bash
npm install svelte@5
```

See the [official Svelte 5 migration guide](https://svelte.dev/docs/svelte/v5-migration-guide) for framework-level changes.

### 4. Update Custom Renderers

If you have custom renderer components, update them to use Svelte 5 runes:

**Before (Svelte 4):**

```svelte
<script>
    export let href = ''
    export let title = ''
</script>

<a {href} {title}>
    <slot />
</a>
```

**After (Svelte 5):**

```svelte
<script>
    const { href = '', title = '', children } = $props()
</script>

<a {href} {title}>
    {@render children?.()}
</a>
```

### 5. Update Component Usage (if needed)

The core API is the same. The `source`, `renderers`, `options`, `isInline`, and `parsed` props work identically:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    const source = '# Hello World'
</script>

<!-- Same API as before -->
<SvelteMarkdown {source} />
```

## New Features Available After Migration

Once migrated, you can immediately use these new capabilities:

### Token Caching

Automatic LRU caching for parsed markdown tokens -- no code changes needed:

```svelte
<!-- Caching is enabled by default -->
<SvelteMarkdown {source} />
```

### Allow/Deny Filtering

Control exactly which elements are rendered:

```svelte
<script>
    import SvelteMarkdown, { allowHtmlOnly, excludeRenderersOnly } from '@humanspeak/svelte-markdown'

    const htmlRenderers = allowHtmlOnly(['strong', 'em', 'a'])
    const renderers = excludeRenderersOnly(['html', 'image'])
</script>

<SvelteMarkdown {source} {renderers} {htmlRenderers} />
```

### Snippet Overrides

Customize rendering inline without creating separate component files:

```svelte
<SvelteMarkdown {source}>
    {#snippet heading(props)}
        <h1 class="custom-heading">{@render props.children?.()}</h1>
    {/snippet}
</SvelteMarkdown>
```

### Marked Extensions

Use the built-in extensions, or any third-party marked extension:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import { markedKatex, KatexRenderer } from '@humanspeak/svelte-markdown/extensions'

    const extensions = [markedKatex()]
    const renderers = { inlineKatex: KatexRenderer, blockKatex: KatexRenderer }
</script>

<SvelteMarkdown source={`Euler's identity: \\(e^{i\\pi} + 1 = 0\\)`} {extensions} {renderers} />
```

## API Compatibility

| Feature | svelte-markdown | @humanspeak/svelte-markdown |
|---------|----------------|----------------------------|
| `source` prop | string | string \| Token[] |
| `renderers` prop | object | Partial\<Renderers\> (typed) |
| `options` prop | object | Partial\<SvelteMarkdownOptions\> (typed) |
| `isInline` prop | boolean | boolean |
| `parsed` callback | function | function |
| `extensions` prop | -- | MarkedExtension[] |
| `snippetOverrides` prop | -- | SnippetOverrides |
| Custom renderers | Svelte 4 components | Svelte 5 components |
| TypeScript | Partial | Full type coverage |
| HTML tag renderers | -- | 69+ built-in |
| Token caching | -- | Built-in LRU |
| Allow/deny filtering | -- | 6 utility functions |

## Related

- [Getting Started](/docs/getting-started) -- installation and setup
- [SvelteMarkdown API](/docs/api/svelte-markdown) -- full component reference
- [Custom Renderers](/docs/renderers/custom-renderers) -- building custom renderers
- [Types & Exports](/docs/api/types) -- all exported types and utilities

<!-- Source: https://markdown.svelte.page/docs/renderers/custom-renderers -->

# Custom Renderers

> Create custom renderer components for @humanspeak/svelte-markdown, override built-ins, pass typed props, and tailor markdown output in Svelte 5.

**Source:** [https://markdown.svelte.page/docs/renderers/custom-renderers](https://markdown.svelte.page/docs/renderers/custom-renderers)

---

One of the most powerful features of `@humanspeak/svelte-markdown` is the ability to replace any built-in renderer with your own Svelte component. This gives you full control over how each markdown element is rendered.

## How It Works

When `SvelteMarkdown` parses markdown, it produces a tree of tokens. Each token has a `type` (e.g., `heading`, `paragraph`, `link`) that maps to a renderer key. The component looks up the renderer for each token and passes the token's data as props.

Your custom renderers replace the defaults for whichever keys you specify:

```svelte
<SvelteMarkdown
    source={markdown}
    renderers={{
        heading: MyHeading,
        link: MyLink,
        code: MyCode
    }}
/>
```

## Creating a Custom Renderer

A custom renderer is a standard Svelte 5 component. It receives props that correspond to the token's data, plus a `children` snippet for tokens that contain nested content.

### Step 1: Check the Props

Look up the renderer you want to override in the [Markdown Renderers](/docs/renderers/markdown-renderers) reference to see what props it receives.

### Step 2: Create the Component

Create a Svelte component that accepts those props:

```svelte
<!-- CustomLink.svelte -->
<script lang="ts">
    import type { Snippet } from 'svelte'

    interface Props {
        href?: string
        title?: string
        children?: Snippet
    }

    const { href = '', title = undefined, children }: Props = $props()
</script>

<a
    {href}
    {title}
    target="_blank"
    rel="noopener noreferrer"
    class="custom-link"
>
    {@render children?.()}
</a>

<style>
    .custom-link {
        color: #0066cc;
        text-decoration: underline;
    }
</style>
```

### Step 3: Pass It to SvelteMarkdown

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import CustomLink from './CustomLink.svelte'
</script>

<SvelteMarkdown
    source="Visit [our site](https://example.com) for more info."
    renderers={{ link: CustomLink }}
/>
```

## Common Custom Renderer Examples

### Custom Heading with Anchor Links

```svelte
<!-- AnchorHeading.svelte -->
<script lang="ts">
    import type { Snippet } from 'svelte'
    import type { SvelteMarkdownOptions } from '@humanspeak/svelte-markdown'

    interface Props {
        depth: number
        raw: string
        text: string
        options: SvelteMarkdownOptions
        slug: (val: string) => string
        children?: Snippet
    }

    const { depth, text, options, slug, children }: Props = $props()

    const id = $derived(
        options.headerIds ? options.headerPrefix + slug(text) : undefined
    )
</script>

<svelte:element this="h{depth}" {id} class="heading">
    {#if id}
        <a href="#{id}" class="anchor-link">#</a>
    {/if}
    {@render children?.()}
</svelte:element>

<style>
    .heading {
        position: relative;
    }
    .anchor-link {
        position: absolute;
        left: -1.5em;
        opacity: 0;
        text-decoration: none;
    }
    .heading:hover .anchor-link {
        opacity: 0.5;
    }
</style>
```

### Custom Code Block with Syntax Highlighting

```svelte
<!-- HighlightedCode.svelte -->
<script lang="ts">
    interface Props {
        lang: string
        text: string
    }

    const { lang, text }: Props = $props()
</script>

<div class="code-block">
    {#if lang}
        <div class="code-lang">{lang}</div>
    {/if}
    <pre><code class="language-{lang}">{text}</code></pre>
</div>

<style>
    .code-block {
        position: relative;
        border-radius: 8px;
        overflow: hidden;
    }
    .code-lang {
        position: absolute;
        top: 0;
        right: 0;
        padding: 2px 8px;
        font-size: 0.75rem;
        background: rgba(0, 0, 0, 0.1);
        border-bottom-left-radius: 4px;
    }
</style>
```

### Custom Image with Caption

```svelte
<!-- CaptionedImage.svelte -->
<script lang="ts">
    interface Props {
        href?: string
        title?: string
        text?: string
    }

    const { href = '', title = undefined, text = '' }: Props = $props()
</script>

<figure>
    <img src={href} alt={text} {title} loading="lazy" />
    {#if text}
        <figcaption>{text}</figcaption>
    {/if}
</figure>

<style>
    figure {
        margin: 1.5em 0;
        text-align: center;
    }
    img {
        max-width: 100%;
        border-radius: 4px;
    }
    figcaption {
        margin-top: 0.5em;
        font-size: 0.875rem;
        color: #666;
    }
</style>
```

### Custom Blockquote with Callout Styling

```svelte
<!-- CalloutBlockquote.svelte -->
<script lang="ts">
    import type { Snippet } from 'svelte'

    interface Props {
        children?: Snippet
    }

    const { children }: Props = $props()
</script>

<div class="callout">
    <div class="callout-icon">i</div>
    <div class="callout-content">
        {@render children?.()}
    </div>
</div>

<style>
    .callout {
        display: flex;
        gap: 12px;
        padding: 16px;
        background: #f0f4ff;
        border-left: 4px solid #3b82f6;
        border-radius: 4px;
        margin: 1em 0;
    }
    .callout-icon {
        font-weight: bold;
        color: #3b82f6;
    }
</style>
```

## Overriding HTML Tag Renderers

You can also override the renderers for specific HTML tags that appear in raw HTML within markdown:

```svelte
<!-- CustomDiv.svelte -->
<script lang="ts">
    import type { Snippet } from 'svelte'

    const { class: className, children, ...rest }: any = $props()
</script>

<div class="custom-wrapper {className || ''}" {...rest}>
    {@render children?.()}
</div>
```

```svelte
<SvelteMarkdown
    source={markdown}
    renderers={{
        html: {
            div: CustomDiv
        }
    }}
/>
```

## Custom HTML Tags

The parsing pipeline accepts any HTML tag name, not just the ~90 built-in ones. To render a custom tag like `<click>`, `<tooltip>`, or a web component, provide a renderer under the `html` key:

```svelte
<!-- ClickButton.svelte -->
<script lang="ts">
    import type { Snippet } from 'svelte'

    const { children, ...rest }: { children?: Snippet; [key: string]: any } = $props()
</script>

<button class="click-btn" {...rest}>
    {@render children?.()}
</button>
```

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import ClickButton from './ClickButton.svelte'
</script>

<SvelteMarkdown
    source={'<click data-action="submit">Click Me</click>'}
    renderers={{ html: { click: ClickButton } }}
/>
```

Custom tags work exactly like built-in HTML tag overrides — the component receives the tag's attributes and a `children` snippet for nested content. You can also use [snippet overrides](/docs/renderers/snippet-overrides#custom-html-tags) for quick inline customization.

## Setting a Renderer to `null`

You can set any renderer to `null` to suppress that element type entirely:

```svelte
<SvelteMarkdown
    source={markdown}
    renderers={{
        image: null,
        hr: null
    }}
/>
```

## Using `defaultRenderers` as a Base

You can import the default renderer map and extend it:

```typescript
import { defaultRenderers } from '@humanspeak/svelte-markdown'

const myRenderers = {
    ...defaultRenderers,
    heading: MyHeading,
    link: MyLink
}
```

## Passing Custom Data to Renderers

Any extra props you pass to `<SvelteMarkdown>` beyond the standard props (`source`, `renderers`, `options`, `isInline`, `parsed`) are automatically forwarded to every renderer component. This lets you pass application-specific context that your custom renderers can use.

### How It Works

`SvelteMarkdown` collects unknown props via `...rest` and spreads them through the `Parser` to each renderer. Your custom renderer simply declares the extra prop in its interface:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import CustomText from './CustomText.svelte'

    let userData = $state({
        theme: 'dark',
        locale: 'en-US',
        permissions: ['read', 'write']
    })
</script>

<SvelteMarkdown
    source={markdown}
    {userData}
    renderers={{ rawtext: CustomText }}
/>
```

Inside your custom renderer, access the forwarded prop directly:

```svelte
<!-- CustomText.svelte -->
<script lang="ts">
    interface Props {
        text?: string
        userData?: { theme: string; locale: string; permissions: string[] }
    }

    const { text, userData }: Props = $props()
</script>

<span class="text-{userData?.theme}">
    {text}
</span>
```

### Production Example: Dynamic Value Interpolation

A powerful real-world use case is passing structured data alongside markdown and using a custom renderer to interpolate live values into the rendered output. For example, you can pass a data object containing placeholder values, and the renderer replaces template markers with rich interactive elements:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import RawText from './RawText.svelte'

    let markdownBlock = $state({
        message: 'The total revenue is {revenue} across {count} transactions.',
        values: {
            revenue: { type: 'currency', value: 125000, description: 'Total Q4 revenue' },
            count: { type: 'number', value: 1847, description: 'Transaction count' }
        }
    })
</script>

<SvelteMarkdown
    source={markdownBlock.message}
    {markdownBlock}
    renderers={{ rawtext: RawText }}
/>
```

The custom `RawText` renderer receives both the `text` prop (from the token) and the `markdownBlock` prop (forwarded from `SvelteMarkdown`). It can then parse the text for `{placeholder}` patterns and replace them with rich UI elements -- tooltips, hover cards, formatted values, loading skeletons, etc.

```svelte
<!-- RawText.svelte -->
<script lang="ts">
    interface Props {
        text?: string
        markdownBlock?: {
            message: string
            values: Record<string, { type: string; value: unknown; description?: string }>
        }
    }

    const { text, markdownBlock }: Props = $props()

    // Parse text for {placeholder} patterns and replace with values from markdownBlock
    const segments = $derived.by(() => {
        if (!text || !markdownBlock?.values) return [{ type: 'text', content: text }]

        const result = []
        const regex = /\{([^}]+)\}/g
        let lastIndex = 0
        let match

        while ((match = regex.exec(text)) !== null) {
            if (match.index > lastIndex) {
                result.push({ type: 'text', content: text.slice(lastIndex, match.index) })
            }
            const key = match[1]
            const value = markdownBlock.values[key]
            if (value) {
                result.push({ type: 'value', data: value })
            }
            lastIndex = match.index + match[0].length
        }

        if (lastIndex < text.length) {
            result.push({ type: 'text', content: text.slice(lastIndex) })
        }
        return result
    })
</script>

{#each segments as segment}
    {#if segment.type === 'text'}
        <span>{segment.content}</span>
    {:else if segment.type === 'value'}
        <strong title={segment.data.description}>{segment.data.value}</strong>
    {/if}
{/each}
```

This pattern is especially useful for AI chat interfaces, data dashboards, and CMS applications where markdown content contains dynamic references that need to be resolved at render time.

## Tips

- Your custom component receives the same props as the built-in renderer it replaces. Check the [Markdown Renderers](/docs/renderers/markdown-renderers) reference for each renderer's prop signature.
- Components that render child content must accept and render a `children` snippet: `{@render children?.()}`.
- Use `$props()` (Svelte 5 runes) to destructure incoming props.
- You can mix custom and default renderers freely -- only override the ones you need.
- Any extra props passed to `SvelteMarkdown` are forwarded to all renderers, so you can pass application context without needing Svelte context stores.

## Related

- [Markdown Renderers](/docs/renderers/markdown-renderers) -- all 24 built-in renderers with their props
- [HTML Renderers](/docs/renderers/html-renderers) -- all 69+ HTML tag renderers
- [Custom Renderers Examples](/docs/examples/custom-renderers) -- runnable code examples

<!-- Source: https://markdown.svelte.page/docs/renderers/html-renderers -->

# HTML Renderers

> Browse all built-in HTML tag renderer components in @humanspeak/svelte-markdown, with tag coverage, override patterns, and allow/deny filtering.

**Source:** [https://markdown.svelte.page/docs/renderers/html-renderers](https://markdown.svelte.page/docs/renderers/html-renderers)

---

When your markdown source contains raw HTML (which Marked parses as `html` tokens), `@humanspeak/svelte-markdown` renders each HTML tag through a dedicated Svelte component. The package ships with renderers for 69+ standard HTML tags.

These HTML renderers are separate from the markdown renderers. They handle HTML elements that appear within markdown content, parsed by [HTMLParser2](https://github.com/fb55/htmlparser2).

## Accessing HTML Renderers

The full HTML renderer map is available as a named export:

```typescript
import { Html, htmlRendererKeys } from '@humanspeak/svelte-markdown'

// Html is an object mapping tag names to Svelte components
console.log(Html.div)    // Div component
console.log(Html.strong) // Strong component

// htmlRendererKeys is an array of all tag names
console.log(htmlRendererKeys) // ['a', 'abbr', 'address', ...]
```

## Overriding HTML Renderers

Override specific HTML tag renderers via the `renderers.html` prop:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import CustomDiv from './CustomDiv.svelte'

    const source = 'Some markdown with <div>raw HTML</div> inside'
</script>

<SvelteMarkdown
    {source}
    renderers={{
        html: {
            div: CustomDiv
        }
    }}
/>
```

Your `html` overrides are merged with the defaults -- only the tags you specify are replaced.

## Complete Tag List

Below is the full list of supported HTML tags, organized by category.

### Text Content

| Tag | Element | Description |
|-----|---------|-------------|
| `p` | `<p>` | Paragraph |
| `blockquote` | `<blockquote>` | Block quotation |
| `pre` | `<pre>` | Preformatted text |
| `hr` | `<hr>` | Thematic break |
| `br` | `<br>` | Line break |

### Headings

| Tag | Element | Description |
|-----|---------|-------------|
| `h1` | `<h1>` | Heading level 1 |
| `h2` | `<h2>` | Heading level 2 |
| `h3` | `<h3>` | Heading level 3 |
| `h4` | `<h4>` | Heading level 4 |
| `h5` | `<h5>` | Heading level 5 |
| `h6` | `<h6>` | Heading level 6 |

### Inline Text Semantics

| Tag | Element | Description |
|-----|---------|-------------|
| `a` | `<a>` | Anchor / hyperlink |
| `abbr` | `<abbr>` | Abbreviation |
| `b` | `<b>` | Bring attention to |
| `bdi` | `<bdi>` | Bidirectional isolate |
| `bdo` | `<bdo>` | Bidirectional override |
| `cite` | `<cite>` | Citation |
| `code` | `<code>` | Inline code |
| `del` | `<del>` | Deleted text |
| `dfn` | `<dfn>` | Definition term |
| `em` | `<em>` | Emphasis |
| `i` | `<i>` | Idiomatic text |
| `kbd` | `<kbd>` | Keyboard input |
| `mark` | `<mark>` | Highlighted text |
| `s` | `<s>` | Strikethrough |
| `samp` | `<samp>` | Sample output |
| `small` | `<small>` | Side comment |
| `span` | `<span>` | Generic inline container |
| `strong` | `<strong>` | Strong importance |
| `sub` | `<sub>` | Subscript |
| `sup` | `<sup>` | Superscript |
| `u` | `<u>` | Unarticulated annotation |
| `var` | `<var>` | Variable |

### Lists

| Tag | Element | Description |
|-----|---------|-------------|
| `ol` | `<ol>` | Ordered list |
| `ul` | `<ul>` | Unordered list |
| `li` | `<li>` | List item |
| `dl` | `<dl>` | Description list |
| `dt` | `<dt>` | Description term |
| `dd` | `<dd>` | Description details |
| `menu` | `<menu>` | Menu list |

### Table Elements

| Tag | Element | Description |
|-----|---------|-------------|
| `table` | `<table>` | Table |
| `thead` | `<thead>` | Table head |
| `tbody` | `<tbody>` | Table body |
| `tfoot` | `<tfoot>` | Table footer |
| `tr` | `<tr>` | Table row |
| `th` | `<th>` | Table header cell |
| `td` | `<td>` | Table data cell |

### Sectioning

| Tag | Element | Description |
|-----|---------|-------------|
| `article` | `<article>` | Self-contained composition |
| `aside` | `<aside>` | Sidebar content |
| `div` | `<div>` | Generic block container |
| `footer` | `<footer>` | Footer |
| `header` | `<header>` | Header |
| `hgroup` | `<hgroup>` | Heading group |
| `main` | `<main>` | Main content |
| `nav` | `<nav>` | Navigation |
| `section` | `<section>` | Standalone section |
| `address` | `<address>` | Contact information |

### Media & Embedded Content

| Tag | Element | Description |
|-----|---------|-------------|
| `audio` | `<audio>` | Audio content |
| `canvas` | `<canvas>` | Drawing surface |
| `embed` | `<embed>` | Embedded content |
| `iframe` | `<iframe>` | Inline frame |
| `img` | `<img>` | Image |
| `param` | `<param>` | Object parameter |
| `picture` | `<picture>` | Responsive image container |
| `source` | `<source>` | Media source |
| `track` | `<track>` | Text track for media |

### Forms & Interactive

| Tag | Element | Description |
|-----|---------|-------------|
| `button` | `<button>` | Clickable button |
| `datalist` | `<datalist>` | Predefined options |
| `details` | `<details>` | Disclosure widget |
| `dialog` | `<dialog>` | Dialog box |
| `fieldset` | `<fieldset>` | Form field group |
| `form` | `<form>` | Form |
| `input` | `<input>` | Form input |
| `label` | `<label>` | Form label |
| `legend` | `<legend>` | Fieldset caption |
| `meter` | `<meter>` | Scalar measurement |
| `optgroup` | `<optgroup>` | Option group |
| `option` | `<option>` | Select option |
| `output` | `<output>` | Calculation result |
| `progress` | `<progress>` | Progress indicator |
| `select` | `<select>` | Dropdown selection |
| `summary` | `<summary>` | Disclosure summary |
| `textarea` | `<textarea>` | Multiline text input |

## UnsupportedHTML Component

The `UnsupportedHTML` component renders nothing. It is used by the allow/deny filtering system to suppress specific HTML tags:

```typescript
import { UnsupportedHTML } from '@humanspeak/svelte-markdown'
```

When a tag is mapped to `UnsupportedHTML`, any instances of that tag in the markdown source will produce no output.

## Filtering HTML Tags

Use the provided utility functions to control which HTML tags are rendered:

```svelte
<script>
    import SvelteMarkdown, {
        allowHtmlOnly,
        excludeHtmlOnly,
        buildUnsupportedHTML
    } from '@humanspeak/svelte-markdown'

    // Only allow safe inline tags
    const safeHtml = allowHtmlOnly(['strong', 'em', 'a', 'code'])

    // Block potentially dangerous tags
    const filteredHtml = excludeHtmlOnly(['iframe', 'form', 'input'])

    // Block all HTML
    const noHtml = buildUnsupportedHTML()
</script>

<SvelteMarkdown source={markdown} renderers={{ html: safeHtml }} />
```

See [Allow/Deny](/docs/advanced/allow-deny) for detailed documentation on these filtering functions.

## Related

- [Markdown Renderers](/docs/renderers/markdown-renderers) -- the 24 built-in markdown renderers
- [Custom Renderers](/docs/renderers/custom-renderers) -- guide to building custom components
- [Allow/Deny](/docs/advanced/allow-deny) -- HTML and renderer filtering
- [Security](/docs/advanced/security) -- security considerations for HTML rendering

<!-- Source: https://markdown.svelte.page/docs/renderers/markdown-renderers -->

# Markdown Renderers

> Browse all built-in markdown renderer components in @humanspeak/svelte-markdown, including token props, override patterns, and Svelte 5 examples.

**Source:** [https://markdown.svelte.page/docs/renderers/markdown-renderers](https://markdown.svelte.page/docs/renderers/markdown-renderers)

---

`@humanspeak/svelte-markdown` includes 24 built-in renderer components that handle the various token types produced by the Marked parser. Each renderer is a Svelte 5 component that accepts specific props based on the token type it handles.

You can override any renderer by passing a custom component via the `renderers` prop on `SvelteMarkdown`.

## Renderer Keys

The complete list of renderer keys is available at runtime via the `rendererKeys` export:

```typescript
import { rendererKeys } from '@humanspeak/svelte-markdown'
```

## Block-Level Renderers

### `heading`

Renders heading elements (`<h1>` through `<h6>`). When `headerIds` is enabled in options, each heading receives an `id` attribute generated by [github-slugger](https://github.com/Flet/github-slugger).

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `depth` | `number` | Heading level (1-6) |
| `raw` | `string` | Raw heading text |
| `text` | `string` | Plain text content (used for ID generation) |
| `options` | `SvelteMarkdownOptions` | Parser options (for `headerIds` and `headerPrefix`) |
| `slug` | `(val: string) => string` | Slugification function |
| `children` | `Snippet` | Rendered child content |

**Default output:** `<h1 id="...">`, `<h2 id="...">`, etc.

### `paragraph`

Renders paragraph elements.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `raw` | `string \| undefined` | Raw markdown source |
| `text` | `string \| undefined` | Plain text content |
| `children` | `Snippet` | Rendered child content |

**Default output:** `<p>`

### `blockquote`

Renders blockquote elements.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `raw` | `string \| undefined` | Raw markdown source |
| `text` | `string \| undefined` | Plain text content |
| `children` | `Snippet` | Rendered child content |

**Default output:** `<blockquote>`

### `code`

Renders fenced code blocks with a language class for syntax highlighting.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `lang` | `string` | Language identifier (e.g., `"javascript"`, `"python"`) |
| `text` | `string` | Code content |
| `codeBlockStyle` | `'indented' \| undefined` | Style of code block (indented vs fenced) |

**Default output:** `<pre class="{lang}"><code>{text}</code></pre>`

### `hr`

Renders horizontal rules. This renderer accepts no props.

**Default output:** `<hr />`

## List Renderers

### `list`

Renders ordered and unordered lists.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `ordered` | `boolean` | `true` for ordered lists, `false` for unordered |
| `start` | `number` | Starting number for ordered lists (default: `1`) |
| `loose` | `boolean \| undefined` | Whether the list has loose spacing |
| `children` | `Snippet` | Rendered child content (list items) |

**Default output:** `<ol start="...">` or `<ul>`

### `listitem`

Renders individual list items.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `text` | `string \| undefined` | Raw text content of the list item |
| `task` | `boolean \| undefined` | Whether this is a task/checkbox list item |
| `checked` | `boolean \| undefined` | Checkbox state (only meaningful when `task` is `true`) |
| `loose` | `boolean \| undefined` | Whether the item has loose spacing |
| `children` | `Snippet` | Rendered child content |
| `listItemIndex` | `number \| undefined` | Index of this item within the list |

**Default output:** `<li>`

### `orderedlistitem`

A specialized renderer for ordered list items. Set to `null` by default, which means the regular `listitem` renderer is used. Override this to render ordered list items differently from unordered ones.

**Default value:** `null` (falls back to `listitem`)

### `unorderedlistitem`

A specialized renderer for unordered list items. Set to `null` by default, which means the regular `listitem` renderer is used. Override this to render unordered list items differently from ordered ones.

**Default value:** `null` (falls back to `listitem`)

## Table Renderers

### `table`

Renders the outer table wrapper element.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `children` | `Snippet` | Rendered child content (thead and tbody) |

**Default output:** `<table>`

### `tablehead`

Renders the table head section.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `children` | `Snippet` | Rendered child content (header row) |

**Default output:** `<thead>`

### `tablebody`

Renders the table body section.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `children` | `Snippet` | Rendered child content (body rows) |

**Default output:** `<tbody>`

### `tablerow`

Renders individual table rows.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `children` | `Snippet` | Rendered child content (cells) |

**Default output:** `<tr>`

### `tablecell`

Renders individual table cells. Outputs either `<th>` or `<td>` based on the `header` prop, with optional text alignment.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `header` | `boolean` | `true` for header cells, `false` for data cells |
| `align` | `'left' \| 'center' \| 'right' \| 'justify' \| 'char' \| null \| undefined` | Text alignment |
| `children` | `Snippet` | Rendered child content |

**Default output:** `<th style="text-align: ...">` or `<td style="text-align: ...">`

## Inline Renderers

### `text`

Renders inline text content. This is a passthrough renderer that renders its children directly without any wrapping element.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `raw` | `string \| undefined` | Raw markdown source |
| `text` | `string \| undefined` | Plain text content |
| `children` | `Snippet` | Rendered child content |

**Default output:** (no wrapper -- renders children directly)

### `link`

Renders anchor links.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `href` | `string` | Link URL |
| `title` | `string \| undefined` | Link title attribute |
| `raw` | `string \| undefined` | Raw markdown source |
| `text` | `string \| undefined` | Plain text content of the link |
| `children` | `Snippet` | Rendered child content (link text) |

**Default output:** `<a href="..." title="...">`

### `image`

Renders images with built-in lazy loading and fade-in support via IntersectionObserver.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `href` | `string` | Image source URL |
| `title` | `string \| undefined` | Image title attribute |
| `text` | `string` | Alt text for the image |
| `raw` | `string \| undefined` | Raw markdown source |
| `lazy` | `boolean` | Enable lazy loading (default: `true`) |
| `fadeIn` | `boolean` | Enable fade-in animation on load (default: `true`) |

**Default output:** `<img src="..." alt="..." title="..." loading="lazy">`

The default Image renderer uses `IntersectionObserver` to defer loading images until they are near the viewport (with a 50px root margin). Images start with `opacity: 0` and transition to full opacity when loaded.

### `em`

Renders emphasized (italic) text.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `raw` | `string \| undefined` | Raw markdown source |
| `text` | `string \| undefined` | Plain text content |
| `children` | `Snippet` | Rendered child content |

**Default output:** `<em>`

### `strong`

Renders strong (bold) text.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `raw` | `string \| undefined` | Raw markdown source |
| `text` | `string \| undefined` | Plain text content |
| `children` | `Snippet` | Rendered child content |

**Default output:** `<strong>`

### `codespan`

Renders inline code spans.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `raw` | `string` | Raw code text including backticks |
| `text` | `string \| undefined` | Decoded text content (backticks stripped) |

**Default output:** `<code>`

### `del`

Renders strikethrough text (requires GFM to be enabled).

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `raw` | `string \| undefined` | Raw markdown source |
| `text` | `string \| undefined` | Plain text content |
| `children` | `Snippet` | Rendered child content |

**Default output:** `<del>`

### `br`

Renders line breaks.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `children` | `Snippet` | Any trailing content |

**Default output:** `<br />`

## Special Renderers

### `escape`

Renders escaped characters (e.g., `\*` renders as `*`).

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `text` | `string` | The escaped character |
| `raw` | `string \| undefined` | Raw markdown source (e.g., `\*`) |

**Default output:** plain text (no wrapper)

### `rawtext`

Renders raw text content that is not part of any other token.

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `text` | `string` | Raw text content |

**Default output:** plain text (no wrapper)

## Overriding a Renderer

To override any renderer, create a Svelte component that accepts the same props and pass it via the `renderers` prop:

```svelte
<!-- CustomHeading.svelte -->
<script lang="ts">
    import type { Snippet } from 'svelte'

    interface Props {
        depth: number
        raw: string
        text: string
        children?: Snippet
    }

    const { depth, text, children }: Props = $props()
</script>

<div class="heading heading-{depth}" data-text={text}>
    {@render children?.()}
</div>
```

```svelte
<!-- App.svelte -->
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import CustomHeading from './CustomHeading.svelte'
</script>

<SvelteMarkdown
    source="# My Heading"
    renderers={{ heading: CustomHeading }}
/>
```

## Related

- [HTML Renderers](/docs/renderers/html-renderers) -- renderers for raw HTML tags in markdown
- [Custom Renderers Guide](/docs/renderers/custom-renderers) -- detailed guide to building custom renderers
- [Allow/Deny](/docs/advanced/allow-deny) -- filtering which renderers are active

<!-- Source: https://markdown.svelte.page/docs/renderers/snippet-overrides -->

# Snippet Overrides

> Customize markdown rendering inline with Svelte 5 snippets in @humanspeak/svelte-markdown, no separate renderer files required for common overrides.

**Source:** [https://markdown.svelte.page/docs/renderers/snippet-overrides](https://markdown.svelte.page/docs/renderers/snippet-overrides)

---

Svelte 5 snippets let you customize how markdown elements render **directly in your template**, without creating separate component files. This is ideal for quick tweaks — adding a class, wrapping in a div, changing an attribute — where a full component would be overkill.

## How It Works

Pass named snippets as children of `<SvelteMarkdown>`. Each snippet name matches a renderer key and receives the same props the corresponding component would, plus a `children` snippet for container elements:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'

    const source = '# Hello\n\nA paragraph with [a link](https://example.com).'
</script>

<SvelteMarkdown {source}>
    {#snippet heading({ depth, children })}
        <svelte:element this="h{depth}" class="my-heading">
            {@render children?.()}
        </svelte:element>
    {/snippet}

    {#snippet paragraph({ children })}
        <p class="prose">{@render children?.()}</p>
    {/snippet}

    {#snippet link({ href, title, children })}
        <a {href} {title} target="_blank" rel="noopener noreferrer">
            {@render children?.()}
        </a>
    {/snippet}
</SvelteMarkdown>
```

## Container vs Leaf Renderers

Renderers fall into two categories based on whether they have nested content:

### Container Renderers

These receive a `children` snippet that renders their inner content. You **must** call `{@render children?.()}` to display nested elements:

| Renderer | Key Props |
|----------|-----------|
| `paragraph` | `raw`, `text`, `children` |
| `heading` | `depth`, `raw`, `text`, `options`, `slug`, `children` |
| `link` | `href`, `title`, `raw`, `text`, `children` |
| `blockquote` | `raw`, `text`, `children` |
| `list` | `ordered`, `start`, `loose`, `children` |
| `listitem` | `text`, `task`, `checked`, `loose`, `listItemIndex`, `children` |
| `table` | `children` |
| `tablehead` | `children` |
| `tablebody` | `children` |
| `tablerow` | `children` |
| `tablecell` | `header`, `align`, `children` |
| `em` | `raw`, `text`, `children` |
| `strong` | `raw`, `text`, `children` |
| `del` | `raw`, `text`, `children` |
| `text` | `raw`, `text`, `children` |

### Leaf Renderers

These render terminal content and do **not** receive `children`:

| Renderer | Key Props |
|----------|-----------|
| `code` | `lang`, `text`, `codeBlockStyle` |
| `codespan` | `raw`, `text` |
| `image` | `href`, `title`, `text`, `raw` |
| `hr` | *(none)* |
| `br` | *(none)* |
| `rawtext` | `text` |
| `escape` | `text`, `raw` |

## Examples

### Custom Paragraph

```svelte
<SvelteMarkdown source="Hello world">
    {#snippet paragraph({ children })}
        <p class="prose leading-relaxed">{@render children?.()}</p>
    {/snippet}
</SvelteMarkdown>
```

### Heading with Wrapper

```svelte
<SvelteMarkdown source="## Section Title">
    {#snippet heading({ depth, children })}
        <div class="heading-wrapper">
            <svelte:element this="h{depth}" class="title">
                {@render children?.()}
            </svelte:element>
        </div>
    {/snippet}
</SvelteMarkdown>
```

### External Links

```svelte
<SvelteMarkdown source="Visit [Svelte](https://svelte.dev)">
    {#snippet link({ href, title, children })}
        <a {href} {title} target="_blank" rel="noopener noreferrer" class="external-link">
            {@render children?.()}
            <span aria-hidden="true"> ↗</span>
        </a>
    {/snippet}
</SvelteMarkdown>
```

### Code Block (Leaf)

Since `code` is a leaf renderer, it receives data props but no `children`:

```svelte
<SvelteMarkdown source={"```js\nconsole.log('hi')\n```"}>
    {#snippet code({ lang, text })}
        <div class="code-wrapper">
            {#if lang}<span class="lang-badge">{lang}</span>{/if}
            <pre><code>{text}</code></pre>
        </div>
    {/snippet}
</SvelteMarkdown>
```

### Image (Leaf)

```svelte
<SvelteMarkdown source="![Alt text](/photo.jpg 'Caption')">
    {#snippet image({ href, title, text })}
        <figure>
            <img src={href} alt={text} loading="lazy" />
            {#if title}<figcaption>{title}</figcaption>{/if}
        </figure>
    {/snippet}
</SvelteMarkdown>
```

### Styled Blockquote

```svelte
<SvelteMarkdown source="> Important note here">
    {#snippet blockquote({ children })}
        <aside class="callout" role="note">
            {@render children?.()}
        </aside>
    {/snippet}
</SvelteMarkdown>
```

### List with Custom Markers

```svelte
<SvelteMarkdown source="- First\n- Second\n- Third">
    {#snippet list({ ordered, children })}
        <ul class="custom-list">{@render children?.()}</ul>
    {/snippet}

    {#snippet listitem({ children })}
        <li class="custom-item">
            <span class="marker">→</span>
            {@render children?.()}
        </li>
    {/snippet}
</SvelteMarkdown>
```

### Task List with Custom Checkboxes

The `listitem` snippet receives `task` and `checked` props, making it easy to customize task list rendering:

```svelte
<SvelteMarkdown source="- [x] Done\n- [ ] Todo\n- Regular item">
    {#snippet listitem({ text, task, checked, children })}
        <li class:task>
            {#if task}
                <label>
                    <input type="checkbox" {checked} disabled />
                    <span class:done={checked}>{@render children?.()}</span>
                </label>
            {:else}
                {@render children?.()}
            {/if}
        </li>
    {/snippet}
</SvelteMarkdown>
```

### Table with Scroll Container

```svelte
<SvelteMarkdown source="| A | B |\n|---|---|\n| 1 | 2 |">
    {#snippet table({ children })}
        <div class="overflow-x-auto rounded-lg border">
            <table class="w-full">{@render children?.()}</table>
        </div>
    {/snippet}

    {#snippet tablecell({ header, align, children })}
        {#if header}
            <th class="bg-gray-100 px-4 py-2" style:text-align={align}>
                {@render children?.()}
            </th>
        {:else}
            <td class="px-4 py-2" style:text-align={align}>
                {@render children?.()}
            </td>
        {/if}
    {/snippet}
</SvelteMarkdown>
```

## HTML Tag Snippets

HTML tags that appear in raw HTML within markdown can also be overridden with snippets. To avoid name collisions with markdown renderer keys (e.g., `em`, `strong`, `code`), HTML snippets use an `html_` prefix.

All HTML snippets share a uniform props interface:

```typescript
interface HtmlSnippetProps {
    attributes?: Record<string, any>
    children?: Snippet
}
```

### Examples

```svelte
<SvelteMarkdown source={'<div class="note">Important</div>'}>
    {#snippet html_div({ attributes, children })}
        <div {...attributes} class="custom-wrapper">
            {@render children?.()}
        </div>
    {/snippet}
</SvelteMarkdown>
```

```svelte
<SvelteMarkdown source={'<a href="https://example.com">Link</a>'}>
    {#snippet html_a({ attributes, children })}
        <a {...attributes} target="_blank" rel="noopener noreferrer">
            {@render children?.()}
        </a>
    {/snippet}
</SvelteMarkdown>
```

## Custom HTML Tags

Snippet overrides work for arbitrary (non-standard) HTML tags too, not just built-in ones. Use the `html_` prefix followed by the tag name:

```svelte
<SvelteMarkdown source={'<click data-action="submit">Click Me</click>'}>
    {#snippet html_click({ attributes, children })}
        <button {...attributes} class="custom-btn">
            {@render children?.()}
        </button>
    {/snippet}
</SvelteMarkdown>
```

This works for any tag name — `html_tooltip`, `html_alert`, `html_my-component`, etc. The snippet receives the same `{ attributes, children }` props as built-in HTML tag snippets.

If you also provide a component renderer for the same custom tag via `renderers={{ html: { click: ClickComponent } }}`, the snippet takes precedence.

## Precedence

When both a snippet override and a component renderer are provided for the same token type, the **snippet always wins**:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import CustomParagraph from './CustomParagraph.svelte'
</script>

<!-- The snippet takes precedence over the component renderer -->
<SvelteMarkdown
    source="Test"
    renderers={{ paragraph: CustomParagraph }}
>
    {#snippet paragraph({ children })}
        <p class="snippet-wins">{@render children?.()}</p>
    {/snippet}
</SvelteMarkdown>
```

The full precedence order is: **Snippet > Component renderer > Default renderer**.

## Partial Overrides

You only need to override the renderers you care about. Everything else uses the default (or component renderer if provided):

```svelte
<SvelteMarkdown source="# Title\n\nA paragraph with **bold** text.">
    {#snippet paragraph({ children })}
        <p class="custom">{@render children?.()}</p>
    {/snippet}
    <!-- heading, strong, etc. all use their defaults -->
</SvelteMarkdown>
```

## Combining with Component Renderers

Snippets and component renderers work together. Use component renderers for complex, reusable overrides and snippets for quick, one-off tweaks:

```svelte
<script>
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import HighlightedCode from './HighlightedCode.svelte'
</script>

<SvelteMarkdown
    source={markdown}
    renderers={{ code: HighlightedCode }}
>
    {#snippet paragraph({ children })}
        <p class="prose">{@render children?.()}</p>
    {/snippet}

    {#snippet link({ href, title, children })}
        <a {href} {title} class="text-blue-600 underline">
            {@render children?.()}
        </a>
    {/snippet}
</SvelteMarkdown>
```

## TypeScript Types

Every snippet prop interface is exported for use in external code. The full set covers all 23 token kinds the renderer emits — block-level (paragraph, heading, list, table, blockquote, hr), inline (text, link, image, em, strong, codespan, del), structural (raw text, escape, br), and embedded HTML.

```typescript
import type {
    // Block-level
    ParagraphSnippetProps,
    HeadingSnippetProps,
    HrSnippetProps,
    BlockquoteSnippetProps,
    ListSnippetProps,
    ListItemSnippetProps,
    CodeSnippetProps,
    TableSnippetProps,
    TableHeadSnippetProps,
    TableBodySnippetProps,
    TableRowSnippetProps,
    TableCellSnippetProps,
    // Inline
    TextSnippetProps,
    RawTextSnippetProps,
    EscapeSnippetProps,
    LinkSnippetProps,
    ImageSnippetProps,
    EmSnippetProps,
    StrongSnippetProps,
    CodespanSnippetProps,
    DelSnippetProps,
    BrSnippetProps,
    // Embedded HTML
    HtmlSnippetProps,
    // Override-map types
    SnippetOverrides,
    HtmlSnippetOverrides
} from '@humanspeak/svelte-markdown'
```

## When to Use Snippets vs Custom Renderers

| Use Case | Recommended Approach |
|----------|---------------------|
| Add a CSS class to paragraphs | Snippet |
| Open links in new tab | Snippet |
| Syntax highlighting with external library | Component renderer |
| Complex renderer with internal state | Component renderer |
| One-off style tweak for a specific page | Snippet |
| Reusable renderer across many pages | Component renderer |
| Quick prototyping | Snippet |

## Related

- [Custom Renderers](/docs/renderers/custom-renderers) -- component-based renderer overrides
- [Markdown Renderers](/docs/renderers/markdown-renderers) -- all 24 built-in renderers with their props
- [HTML Renderers](/docs/renderers/html-renderers) -- all HTML tag renderers
- [Snippet Overrides Examples](/docs/examples/snippet-overrides) -- runnable code examples
- [Interactive Snippet Demo](/examples/snippet-overrides) -- live playground