@humanspeak/svelte-markdown

A powerful, customizable markdown renderer for Svelte with TypeScript support. Built as a successor to the original svelte-markdown package by Pablo Berganza, now maintained and enhanced by Humanspeak, Inc.

Features

• 🔒 Secure HTML parsing via HTMLParser2 with built-in XSS defaults (protocol allowlist, on* handler stripping)
• 🚀 Full markdown syntax support through Marked
• 💪 Complete TypeScript support with strict typing
• 🔄 Svelte 5 runes compatibility
• ✂️ Inline snippet overrides — customize renderers without separate files
• 🎨 Customizable component rendering system
• ♿ WCAG 2.1 accessibility compliance
• 🎯 GitHub-style slug generation for headers
• 🧪 Comprehensive test coverage (vitest and playwright)
• 🧩 First-class marked extensions support via extensions prop (e.g., KaTeX math, alerts)
• 🎨 Opt-in syntax highlighting with one HighlightedCode renderer and your choice of engine (Shiki or TanStack Highlight) — streaming-compatible, tree-shaken out of the core bundle
• ⚡ Intelligent token caching (50-200x faster re-renders)
• 📡 LLM streaming mode with incremental rendering: work per frame is proportional to the open block, not the document (about 2–3 ms on mixed prose)
• 📬 Late and out-of-order packets: writeChunk({ value, offset }) assembles chunks in any arrival order and keeps rendering while gaps fill
• 🖼️ Smart image lazy loading with fade-in animation

Upgrading to 2.0

Version 2.0 rebuilds the streaming engine. Component props and the writeChunk() / resetStream() API are unchanged, and most apps only need the version bump. Two behaviors changed:

• Renderers for tokens inside list items and table cells receive only their own token fields; they no longer inherit the parent list's or table's raw, text, items, header, or rows.
• The default code renderer emits one text node per line, so code.firstChild is the first line only. textContent and innerHTML are unchanged.

Read the 2.0 upgrade guide for the full list, including streaming output fixes and the new IncrementalParser fields.

Upgrading with an AI assistant? Paste this so it reads the right sources first:

I am upgrading @humanspeak/svelte-markdown from 1.x to 2.0 in a Svelte 5 project.
Before changing anything, read these sources:

- Upgrade guide: https://markdown.svelte.page/docs/migration/v2.md
- Documentation index for LLMs: https://markdown.svelte.page/llms.txt
- Full documentation text: https://markdown.svelte.page/llms-full.txt
- Streaming behavior: https://markdown.svelte.page/docs/advanced/llm-streaming.md
- Direct parser use: https://markdown.svelte.page/docs/advanced/headless-parser.md
- Release notes: https://github.com/humanspeak/svelte-markdown/releases

Then search my codebase for:

1. Custom renderers or snippets used inside lists and tables that read raw,
   text, items, header, or rows from props.
2. Code that reads firstChild or childNodes of rendered <code> elements or of
   the markdown container.
3. Direct IncrementalParser usage.
4. Tests that snapshot streamed output mid-stream.

List each place that needs a change, explain why using the guide, and propose
the smallest fix.

Installation

npm i -S @humanspeak/svelte-markdown

Or with your preferred package manager:

pnpm add @humanspeak/svelte-markdown
yarn add @humanspeak/svelte-markdown

Basic Usage

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

    const source = `
# This is a header

This is a paragraph with **bold** and <em>mixed HTML</em>.

* List item with \`inline code\`
* And a [link](https://svelte.dev)
  * With nested items
  * Supporting full markdown
`
</script>

<SvelteMarkdown {source} />

Rendering AI Agent Output

Modern AI coding agents — Claude Code, Codex, agentic workflows — increasingly emit HTML alongside markdown for richer output (design mockups, dashboards, reports, interactive artifacts). @humanspeak/svelte-markdown is built for this:

• Mixed markdown + HTML in a single source — agents can interleave standard markdown with rich HTML (tables, SVG, custom elements) without a second renderer
• XSS defaults on by default — javascript: URLs and on* handlers stripped from agent output before render, no opt-in required (see Security)
• Streaming-aware sanitization — when streaming is enabled, each token is sanitized as it's emitted; mid-tag partials buffer until well-formed, so progressive HTML from an LLM renders without flicker
• Custom HTML tag support — route semantic markup like <tool-call>, <thinking>, or your own design-system tags to your own components via renderers.html (see Custom HTML Tags)

<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 />

For background on why HTML has become a common agent output format, see Thariq's post: Using Claude Code: The Unreasonable Effectiveness of HTML. For the full streaming API (offset chunks, reset, websocket patterns), see LLM Streaming below.

TypeScript Support

The package is written in TypeScript and includes full type definitions:

import type {
    Renderers,
    Token,
    TokensList,
    SvelteMarkdownOptions,
    MarkedExtension
} from '@humanspeak/svelte-markdown'

Exports for programmatic overrides

You can import renderer maps and helper keys to selectively override behavior.

import SvelteMarkdown, {
    // Maps
    defaultRenderers, // markdown renderer map
    Html, // HTML renderer map

    // Keys
    rendererKeys, // markdown renderer keys (excludes 'html')
    htmlRendererKeys, // HTML renderer tag names

    // Utility components
    Unsupported, // markdown-level unsupported fallback
    UnsupportedHTML // HTML-level unsupported fallback
} from '@humanspeak/svelte-markdown'

// Example: override a subset
const customRenderers = {
    ...defaultRenderers,
    link: CustomLink,
    html: {
        ...Html,
        span: CustomSpan
    }
}

// Optional: iterate keys when building overrides dynamically
for (const key of rendererKeys) {
    // if (key === 'paragraph') customRenderers.paragraph = MyParagraph
}
for (const tag of htmlRendererKeys) {
    // if (tag === 'div') customRenderers.html.div = MyDiv
}

Notes

• rendererKeys intentionally excludes html. Use htmlRendererKeys for HTML tag overrides.
• Unsupported and UnsupportedHTML are available if you want a pass-through fallback strategy.

Helper utilities for allow/deny strategies

These helpers make it easy to either allow only a subset or exclude only a subset of renderers without writing huge maps by hand.

• HTML helpers
  • buildUnsupportedHTML(): returns a map where every HTML tag uses UnsupportedHTML.
  • allowHtmlOnly(allowed): enable only the provided tags; others use UnsupportedHTML.
    • Accepts tag names like 'strong' or tuples like ['div', MyDiv] to plug in custom components.
  • excludeHtmlOnly(excluded, overrides?): disable only the listed tags (mapped to UnsupportedHTML), with optional overrides for non-excluded tags using tuples.
• Markdown helpers (non-HTML)
  • buildUnsupportedRenderers(): returns a map where all markdown renderers (except html) use Unsupported.
  • allowRenderersOnly(allowed): enable only the provided markdown renderer keys; others use Unsupported.
    • Accepts keys like 'paragraph' or tuples like `['p