<SvelteMarkdown source={markdown} extensions={[markedAlert()]}>
    {#snippet alert(props)}
        <div class="my-alert my-alert-{props.alertType}">
            <strong>{props.alertType}</strong>
            <p>{props.text}</p>
        </div>
    {/snippet}
</SvelteMarkdown>

Footnotes

Built-in support for footnote references and definitions. Footnote references ([^id]) render as superscript links, and definitions ([^id]: content) render as a numbered list at the end of the document with back-links.

<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import type { RendererComponent, Renderers } from '@humanspeak/svelte-markdown'
    import {
        markedFootnote,
        FootnoteRef,
        FootnoteSection
    } from '@humanspeak/svelte-markdown/extensions'
const source = 
Here is a statement[^1] with a footnote.

Another claim[^note] that needs a source.
[^1]: This is the first footnote.
[^note]: This is a named footnote.

interface FootnoteRenderers extends Renderers {
        footnoteRef: RendererComponent
        footnoteSection: RendererComponent
    }
const renderers: Partial<FootnoteRenderers> = {
        footnoteRef: FootnoteRef,
        footnoteSection: FootnoteSection
    }
</script>
<SvelteMarkdown {source} extensions={[markedFootnote()]} {renderers} />

Definitions may start with zero to three spaces. Continuation text must be indented by at least four spaces or one tab; one indentation unit is removed from the rendered plain text. A blank line belongs to a definition only when an indented continuation follows it, so an unindented paragraph, heading, list, fence, or HTML block after a definition remains normal document content. Empty definition bodies are supported. If a label is defined more than once, the first definition in document order wins.

FootnoteRef renders ^{id} and FootnoteSection renders an

with bidirectional links. Simple labels containing only ASCII letters, digits, _, and - retain the legacy IDs (fn-my-note and fnref-my-note). Other UTF-16 code units use a deterministic ~ plus four-digit lowercase hexadecimal encoding: for example, [^x:2] uses fn-x~003a2. Repeated references retain their visible label while receiving occurrence IDs such as fnref-note, fnref-note:ref:2, and fnref-note:ref:3; the definition renders one backlink for each occurrence. Link fragments URI-encode these full DOM IDs.

Custom component renderers and snippet overrides receive additive navigation props. A footnoteRef receives { id, referenceId? }, where referenceId is the prepared occurrence DOM ID. A footnoteSection receives { footnotes }, with each record shaped as { id, text, backrefs?: string[] }; backrefs contains the prepared reference DOM IDs. The built-in renderers keep their legacy first-reference fallback when these optional props are omitted.

IDs are coordinated within one SvelteMarkdown document. Separate component instances using the same labels are not automatically namespaced, so applications that place multiple rendered documents in one page should provide custom renderers if cross-document ID uniqueness is required. Footnote bodies are rendered as escaped plain text rather than Markdown, and this extension does not claim full CommonMark or GFM footnote compatibility.

Syntax Highlighting (Shiki or TanStack Highlight)

Unlike the marked extensions above, syntax highlighting is a renderer-level override: you replace the default code renderer with HighlightedCode, so there is no extensions prop entry and no marked tokenizer involved. HighlightedCode is engine-agnostic — it talks to a two-method CodeHighlighter interface, and two engines ship as opt-in factories on their own subpaths. Both are synchronous, so the code renderer never trips the async-extension guard — streaming stays fully enabled.

| Subpath | Exports | Optional peer | Core + ts/js/json | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------- | ----------------------- | | @humanspeak/svelte-markdown/extensions/highlight | HighlightedCode, CodeHighlighter, HIGHLIGHT_CONTEXT_KEY, setCodeHighlighter | none | — | | @humanspeak/svelte-markdown/extensions/shiki | createShikiHighlighter — TextMate grammars, inline theme colors | shiki | ~87 KB gzip | | @humanspeak/svelte-markdown/extensions/tanstack-highlight | createTanstackHighlighter — hand-written scanners, semantic th-* classes, CSS themes | @tanstack/highlight | ~4 KB gzip |

The TanStack adapter supports Highlight 0.1 and 1.x. Upgrading to 1.0 requires no changes to imports, factory options, or theme setup; JavaScript and TypeScript property names that are keywords may receive corrected colors.

Pick Shiki for editor-exact colors and 200+ grammars; pick TanStack Highlight for chat and agent UIs that stream a lot of code and care about weight (25 languages, themes are CSS variables so light/dark is a CSS toggle). Install the peer you use:

npm install shiki                # or
npm install @tanstack/highlight

Import only the languages (and, for Shiki, themes) you need, build a highlighter, register it, then map HighlightedCode to the code renderer:

<script lang="ts">
    import SvelteMarkdown from '@humanspeak/svelte-markdown'
    import {
        createTanstackHighlighter,
        HighlightedCode,
        setCodeHighlighter
    } from '@humanspeak/svelte-markdown/extensions/tanstack-highlight'
    import { ts } from '@tanstack/highlight/languages/ts'
    import { createThemeCss } from '@tanstack/highlight/theme'
    import githubDark from '@tanstack/highlight/themes/github-dark'
    import githubLight from '@tanstack/highlight/themes/github-light'

// Register once (module singleton). Every HighlightedCode instance resolves it.
    setCodeHighlighter(createTanstackHighlighter({ languages: [ts] }))
    // TanStack emits classes only — ship a theme stylesheet (match darkSelector to your app).
    const themeCss = createThemeCss({
        light: githubLight,
        dark: githubDark,
        darkSelector: 'html.dark'
    })
const source = '

ts\nconst answer: number = 42\n`'

{@html }

The Shiki variant is the same shape: createShikiHighlighter({ langs: [ts], themes: [githubDark] }) from extensions/shiki with shiki/langs/ and shiki/themes/ imports, and no stylesheet since colors are inlined.

The highlighter is resolved in priority order: an explicit highlighter prop → a Svelte context set under HIGHLIGHT_CONTEXT_KEY (for per-subtree engines/themes or SSR request isolation) → the module singleton from setCodeHighlighter. Unregistered languages and any per-block failure degrade to an escaped fallback <pre> rather than throwing mid-stream (Shiki: shiki-fallback; TanStack: its own th-code--plaintext so the block keeps your theme, or th-code--fallback with plaintextFallback: false). Both engines escape the code they emit and every fallback escapes its inputs, so the {@html} sink only ever receives library-generated or explicitly-escaped markup (the same trust model as KatexRenderer / MermaidRenderer). You can also implement CodeHighlighter yourself to wrap any other highlighter.
Backward compatibility. extensions/shiki still exports ShikiCode, SHIKI_CONTEXT_KEY, setShikiHighlighter, getShikiHighlighter, and ShikiHighlighter; they are aliases of the extensions/highlight names (same component, same symbol, same singleton). The only visible change is that with no highlighter configured at all the renderer's fallback <pre> carries highlight-fallback instead of shiki-fallback.
Bundle guidance — this is opt-in for a reason. The cost lands only when you construct a highlighter: importing HighlightedCode alone pulls in nothing from either engine, the core SvelteMarkdown bundle stays engine-free, and the two engines never leak into each other (all enforced by scripts/tree-shaking.mjs). Import narrowly: every extra grammar, language, or theme you import is bundled. Shiki's JS engine keeps SSR trivial (no WASM); highlight-heavy client apps can opt into its faster oniguruma-WASM engine, which is still streaming-safe. See the side-by-side streaming demo for live per-engine timings.
How It Works
Marked extensions define custom token types with a name property (e.g., inlineKatex, blockKatex, alert). When you pass extensions via the extensions prop, SvelteMarkdown automatically extracts these token type names and makes them available as both component renderer keys and snippet override names.
To find the token type names for any extension, check its source or documentation for the name field in its extensions array:

js // Example: markedKatex (built-in) registers tokens named "inlineKatex" and "blockKatex" // → use renderers={{ inlineKatex: ..., blockKatex: ... }} // → or {#snippet inlineKatex(props)} and {#snippet blockKatex(props)}

// Example: a custom alert extension registers a token named "alert" // → use renderers={{ alert: AlertComponent }} // → or {#snippet alert(props)}

Each snippet/component receives the token's properties as props (e.g., text, displayMode for KaTeX; text, alertType for alerts). Marked HTML renderer functions do not replace Svelte renderers; provide a component or snippet for each custom token type.

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.
This means extension factories can safely close over reactive state:

svelte

{#snippet displayValue(props)} {props.text} {/snippet}

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 flow into your renderer or snippet without requiring a manual cache key.

See the full documentation and interactive demo.
TypeScript
All snippet prop types are exported for use in external components:

typescript import type { ParagraphSnippetProps, HeadingSnippetProps, LinkSnippetProps, CodeSnippetProps, HtmlSnippetProps, SnippetOverrides, HtmlSnippetOverrides } from '@humanspeak/svelte-markdown'

## Advanced Features

Table Support with Mixed Content
The package excels at handling complex nested structures and mixed content:

markdown | Type | Content | | ---------- | --------------------------------------- | | Nested |
bold and _italic_
| | Mixed List |
• Item 1
• Item 2
| | Code | inline code |

### HTML in Markdown

Seamlessly mix HTML and Markdown:

markdown
### This is a Markdown heading inside HTML And here's some bold text too!
Click to expand
• This is a markdown list
• Inside an HTML details element
• Supporting bold and _italic_ text

### Markdown preprocessor (alpha)
We’re developing a Markdown preprocessor for authored pages and components.
It parses Markdown at build time while preserving SvelteMarkdown’s custom
Markdown renderers, and compiles embedded Svelte components and expressions without
requiring special delimiters. Static pages can use the same renderer
customization as runtime Markdown, without parsing the document again in the
browser.
Status: alpha. The API and supported syntax are still evolving. This alpha
does not yet provide a published preprocessor entry point.
Performance
Intelligent Token Caching
Parsed tokens are automatically cached using an LRU strategy, avoiding repeated lexing for previously seen content. The benefit depends on document size and parsing configuration. The cache uses FNV-1a hashing keyed on source + options, with LRU eviction (default 50 documents) and TTL expiration (default 5 minutes). No configuration required.

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

// Manual cache management tokenCache.clearAllTokens() tokenCache.deleteTokens(markdown, options)

// Custom cache instance const myCache = new TokenCache({ maxSize: 100, ttl: 10 60 1000 })

tokenCache is the shared cache used by the component. Creating a separate
TokenCache does not replace it; a custom instance is for your own token caching.
Treat cache option objects as immutable and create a new object when options change.

> Cache entries store the source string alongside its
> tokens so a hit is verified against hash collisions — getTokens,
> setTokens, and hasTokens are the supported token API. The raw
> get()/set() methods inherited from MemoryCache now operate on the
> wrapped { source, tokens } entry shape, not bare token arrays.
Smart Image Lazy Loading
The default Markdown image renderer lazy loads using native loading="lazy" and IntersectionObserver prefetching, with a smooth fade-in animation and error state handling. When an image URL changes, its load/error state resets for the new request; unchanged image URLs keep their existing DOM and completed state during updates. Reusing the same failed URL does not automatically retry it. Raw HTML <img> tags use the HTML renderer and do not inherit this behavior. To disable lazy loading or provide custom retry behavior for Markdown images, provide a custom image renderer:

svelte

svelte

### Optional streaming text segments and Motion

Default rendering remains ordinary unwrapped text. streamingText (default false) enables immutable source arrival metadata only with synchronous streaming; animation requires an explicitly selected renderer or snippet.

svelte

Install @humanspeak/svelte-motion@^2.0.1-0 explicitly for the optional streaming/motion subpath. It exports FadeWords (opacity), RiseWords (opacity plus vertical rise), FadeCharacters (graphemes), Fade (a whole extension token such as math), StreamingMotionProps and StreamingFadeProps. Motion is an optional peer; installing it alone enables nothing. Presets accept enabled, ink, animateRevisions, animateInitialContent, initial, animate, transition, variants, custom, locale, segmenter and a complete markup replacement segment snippet. Whitespace stays literal; RiseWords motion spans and ink-wipe wrappers are inline-block. Consumers control reduced motion via enabled.

All three presets use a leaf-local batch stagger of 0.02s capped at 0.16s. FadeWords fades over 0.65s (linear). RiseWords adds an 8px rise over 0.4s (easeOut) to the same fade. FadeCharacters keeps a 0.18s fade. FadeWords and RiseWords also apply an ink wipe, a feathered left-to-right mask reveal over 0.8s on arriving words; pass ink={false} to disable it or ink={{ duration }} to retime it (FadeCharacters leaves it off unless ink is passed). Consumer initial and animate replace the preset targets; transition replaces the entire default transition, including easing and stagger.
The core exports headless StreamingText with text, optional metadata, granularity: 'word' | 'grapheme' (word by default), locale, segmenter, and segment: Snippet<[StreamingTextSegment]>. Forward leaf/snippet streamingText into metadata. Without a snippet it emits escaped text without wrappers or segmentation. No Motion installation is required for core or headless use.
StreamingTextSegment has readonly id, text, index, start, end, isNew, batchId, batchIndex, isWhitespace and change: 'baseline' | 'append' | 'revision'. Offsets are leaf-local UTF-16. Creation eligibility and batch fields persist while an unfinished word grows. StreamingTextMetadata has readonly epoch, leafId, renderBatchId, provenance: 'exact' | 'unknown', readonly ranges and, on extension tokens only, arrival (StreamingTextArrival: change, batchId, revealedBeforeBatch). Each StreamingTextRange has readonly start, end, originId, change, batchId and revealedBeforeBatch. Other exported types are StreamingTextArrival, StreamingTextProps, StreamingTextSpan, StreamingTextSegmenter, StreamingTextGranularity and StreamingTextChange.
First/reset content is baseline; appends are arrivals; offset overwrites are revisions. Structural remounts do not replay already revealed source characters. Tokens produced by custom extension tokenizers (for example KaTeX math) have unknown provenance and no word segments; surrounding markdown text keeps its entrances. Wrap their renderer in Fade (<Fade {streamingText}><KatexRenderer {text} /></Fade>, block for display math) to fade the whole token in once, when it arrives; remounts of already revealed tokens and baseline content render without an entrance. Fade accepts streamingText, enabled, block, animateRevisions, animateInitialContent, initial, animate and transition. A walkTokens hook or custom tokenizer makes the whole parse unknown and suppresses automatic entrances. Tracking is per instance and discarded on resets, replacements, mode changes and toggles. Unicode boundaries require Intl.Segmenter or validated custom spans covering the exact text; locale/segmentation changes rebaseline. Changed leaves are resegmented with full context; completed unchanged leaves stay cached. Segment DOM cost is opt-in, and long open blocks/full-parser fallbacks retain their existing costs. Code renderers are excluded.
See the streaming text API and complete prop/imperative, custom snippet, SSR and reduced-motion examples and executable demo with actual source.
LLM Streaming
For real-time rendering of AI responses, enable the streaming prop. Append-only updates normally re-parse the open block at the end of the source and reuse unchanged tokens. Edits, reference definitions, and some extensions can require a full-document parse; work is not constant for every document or configuration.
The preferred API is now imperative: bind the component instance and call writeChunk() as chunks arrive. This avoids prop reactivity edge cases like identical consecutive string chunks being coalesced.

svelte

For websocket-style offset patches, pass an object chunk instead:

ts markdown?.writeChunk({ value: 'world', offset: 6 })

Object chunks overwrite the internal buffer at offset. This is overwrite semantics, not insert semantics: the chunk replaces characters starting at that index and preserves any trailing content after the overwritten span.

Offsets count JavaScript string positions (UTF-16 code units), not bytes. If offset skips ahead, missing positions are padded with spaces. A chunk that opens a gap larger than 1,000,000 positions is dropped with a warning. There is no delete or truncate behavior in offset mode.
Typical websocket-style usage can arrive out of order:

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

The internal buffer converges as later patches fill earlier gaps.

You can reset the internal streaming buffer at any time:

ts markdown?.resetStream('') markdown?.resetStream('# Seeded response')

The first successful write after a reset locks the stream into one input mode:

string chunks: append mode
{ value, offset } chunks: offset mode
Switching modes before resetStream() or a source prop reset logs a warning and drops the chunk. Offset chunks must use a non-negative safe integer offset.
Setting the source prop to a new value also resets the imperative buffer, seeds a new baseline value, and unlocks the input mode. Re-assigning the same value is not a change and resets nothing — see the warning below.
Resetting between messages
The streaming buffer, the incremental parser, and the input-mode lock are all per-component-instance state. They outlive any single message. If a component instance is reused for a second stream without being reset, the new stream starts on top of the previous message's buffer.
This bites the common chat-transcript pattern, because Svelte reuses the component instance whenever it isn't keyed by message identity:

svelte {#each messages as message} {/each} ``

Holding source="" for the entire conversation means the source` prop never changes, so nothing ever triggers the implicit rese

... (README truncated for length)