@humanspeak/svelte-markdown 1.0.0 → 1.0.2

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2024-2025 Humanspeak, Inc.
+Copyright (c) 2024-2026 Humanspeak, Inc.
 
 Copyright (c) 2020-2024 Pablo Berganza
 

package/README.md

@@ -20,11 +20,12 @@ A powerful, customizable markdown renderer for Svelte with TypeScript support. B
 - 🚀 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)
-- 🎨 Custom Marked extensions support (e.g., GitHub-style alerts)
+- 🧩 First-class marked extensions support via `extensions` prop (e.g., KaTeX math, alerts)
 - ⚡ Intelligent token caching (50-200x faster re-renders)
 - 🖼️ Smart image lazy loading with fade-in animation
 
@@ -71,7 +72,8 @@ import type {
     Renderers,
     Token,
     TokensList,
-    SvelteMarkdownOptions
+    SvelteMarkdownOptions,
+    MarkedExtension
 } from '@humanspeak/svelte-markdown'
 ```
 
@@ -259,6 +261,219 @@ Here's a complete example of a custom renderer with TypeScript support:
 
 If you would like to extend other renderers please take a look inside the [renderers folder](https://github.com/humanspeak/svelte-markdown/tree/main/src/lib/renderers) for the default implentation of them. If you would like feature additions please feel free to open an issue!
 
+## Snippet Overrides (Svelte 5)
+
+For simple tweaks — adding a class, changing an attribute, wrapping in a div — you can override renderers inline with Svelte 5 snippets instead of creating separate component files:
+
+```svelte
+<script lang="ts">
+    import SvelteMarkdown from '@humanspeak/svelte-markdown'
+
+    const source = '# Hello\n\nA paragraph with [a link](https://example.com).'
+</script>
+
+<SvelteMarkdown {source}>
+    {#snippet paragraph({ children })}
+        <p class="prose">{@render children?.()}</p>
+    {/snippet}
+
+    {#snippet heading({ depth, children })}
+        {#if depth === 1}
+            <h1 class="title">{@render children?.()}</h1>
+        {:else}
+            <h2>{@render children?.()}</h2>
+        {/if}
+    {/snippet}
+
+    {#snippet link({ href, title, children })}
+        <a {href} {title} target="_blank" rel="noopener noreferrer">
+            {@render children?.()}
+        </a>
+    {/snippet}
+
+    {#snippet code({ lang, text })}
+        <pre class="highlight {lang}"><code>{text}</code></pre>
+    {/snippet}
+</SvelteMarkdown>
+```
+
+### How it works
+
+- **Container renderers** (paragraph, heading, blockquote, list, etc.) receive a `children` snippet for nested content
+- **Leaf renderers** (code, image, hr, br) receive only data props — no `children`
+- **Precedence**: snippet > component renderer > default. If both a snippet and a `renderers.paragraph` component are provided, the snippet wins
+
+### HTML tag snippets
+
+HTML tag snippets use an `html_` prefix to avoid collisions with markdown renderer names:
+
+```svelte
+<SvelteMarkdown {source}>
+    {#snippet html_div({ attributes, children })}
+        <div class="custom-wrapper" {...attributes}>{@render children?.()}</div>
+    {/snippet}
+
+    {#snippet html_a({ attributes, children })}
+        <a {...attributes} target="_blank" rel="noopener noreferrer">
+            {@render children?.()}
+        </a>
+    {/snippet}
+</SvelteMarkdown>
+```
+
+All HTML snippets share a uniform props interface: `{ attributes?: Record<string, any>, children?: Snippet }`.
+
+### Custom HTML Tags
+
+You can render arbitrary (non-standard) HTML tags like `<click>`, `<tooltip>`, or any custom element by providing a renderer or snippet for the tag name. The parsing pipeline accepts any tag name — you just need to tell `SvelteMarkdown` how to render it.
+
+**Component renderer approach:**
+
+```svelte
+<script lang="ts">
+    import SvelteMarkdown from '@humanspeak/svelte-markdown'
+    import ClickButton from './ClickButton.svelte'
+
+    const source = '<click>Click Me</click>'
+    const renderers = { html: { click: ClickButton } }
+</script>
+
+<SvelteMarkdown {source} {renderers} />
+```
+
+**Snippet override approach:**
+
+```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>
+```
+
+Both approaches work for any tag name. Snippet overrides take precedence over component renderers when both are provided.
+
+## Marked Extensions
+
+Use third-party [marked extensions](https://marked.js.org/using_advanced#extensions) via the `extensions` prop. The component handles registering tokenizers internally — you just provide renderers for the custom token types.
+
+### KaTeX Math Rendering
+
+```bash
+npm install marked-katex-extension katex
+```
+
+**Component renderer approach:**
+
+```svelte
+<script lang="ts">
+    import SvelteMarkdown from '@humanspeak/svelte-markdown'
+    import type { RendererComponent, Renderers } from '@humanspeak/svelte-markdown'
+    import markedKatex from 'marked-katex-extension'
+    import KatexRenderer from './KatexRenderer.svelte'
+
+    interface KatexRenderers extends Renderers {
+        inlineKatex: RendererComponent
+        blockKatex: RendererComponent
+    }
+
+    const renderers: Partial<KatexRenderers> = {
+        inlineKatex: KatexRenderer,
+        blockKatex: KatexRenderer
+    }
+</script>
+
+<svelte:head>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.28/dist/katex.min.css" crossorigin="anonymous" />
+</svelte:head>
+
+<SvelteMarkdown
+    source="Euler's identity: $e^{{i\pi}} + 1 = 0$"
+    extensions={[markedKatex({ throwOnError: false })]}
+    {renderers}
+/>
+```
+
+Where `KatexRenderer.svelte` is:
+
+```svelte
+<script lang="ts">
+    import katex from 'katex'
+
+    interface Props {
+        text: string
+        displayMode?: boolean
+    }
+    const { text, displayMode = false }: Props = $props()
+
+    const html = $derived(katex.renderToString(text, { throwOnError: false, displayMode }))
+</script>
+
+{@html html}
+```
+
+**Snippet override approach** (no separate component file needed):
+
+```svelte
+<script lang="ts">
+    import SvelteMarkdown from '@humanspeak/svelte-markdown'
+    import katex from 'katex'
+    import markedKatex from 'marked-katex-extension'
+</script>
+
+<svelte:head>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.28/dist/katex.min.css" crossorigin="anonymous" />
+</svelte:head>
+
+<SvelteMarkdown
+    source="Euler's identity: $e^{{i\pi}} + 1 = 0$"
+    extensions={[markedKatex({ throwOnError: false })]}
+>
+    {#snippet inlineKatex(props)}
+        {@html katex.renderToString(props.text, { displayMode: false })}
+    {/snippet}
+    {#snippet blockKatex(props)}
+        {@html katex.renderToString(props.text, { displayMode: true })}
+    {/snippet}
+</SvelteMarkdown>
+```
+
+### 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: marked-katex-extension 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`, `level` for alerts).
+
+See the [full documentation](https://markdown.svelte.page/docs/advanced/marked-extensions) and [interactive demo](https://markdown.svelte.page/examples/marked-extensions).
+
+### 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
@@ -417,12 +632,13 @@ The component emits a `parsed` event when tokens are calculated:
 
 ## Props
 
-| Prop      | Type                    | Description                           |
-| --------- | ----------------------- | ------------------------------------- |
-| source    | `string \| Token[]`     | Markdown content or pre-parsed tokens |
-| renderers | `Partial<Renderers>`    | Custom component overrides            |
-| options   | `SvelteMarkdownOptions` | Marked parser configuration           |
-| isInline  | `boolean`               | Toggle inline parsing mode            |
+| Prop       | Type                    | Description                                      |
+| ---------- | ----------------------- | ------------------------------------------------ |
+| source     | `string \| Token[]`     | Markdown content or pre-parsed tokens            |
+| renderers  | `Partial<Renderers>`    | Custom component overrides                       |
+| options    | `SvelteMarkdownOptions` | Marked parser configuration                      |
+| isInline   | `boolean`               | Toggle inline parsing mode                       |
+| extensions | `MarkedExtension[]`     | Third-party marked extensions (e.g., KaTeX math) |
 
 ## Security
 

package/dist/Parser.svelte

@@ -95,7 +95,7 @@
             />
         {/each}
     {/if}
-{:else if type in renderers}
+{:else if type in renderers || type in snippetOverrides}
     {#if type === 'table'}
         {#if renderers.table && renderers.tablerow && renderers.tablecell}
             {@const tableSnippet = snippetOverrides[type]}

package/dist/SvelteMarkdown.svelte

@@ -59,7 +59,8 @@
         type TokensList
     } from './utils/markdown-parser.js'
     import { parseAndCacheTokens } from './utils/parse-and-cache.js'
-    import { rendererKeysInternal, htmlRendererKeysInternal } from './utils/rendererKeys.js'
+    import { rendererKeysInternal } from './utils/rendererKeys.js'
+    import { Marked } from 'marked'
 
     const {
         source = [],
@@ -67,12 +68,23 @@
         options = {},
         isInline = false,
         parsed = () => {},
+        extensions = [],
         ...rest
     }: SvelteMarkdownProps & {
         [key: string]: unknown
     } = $props()
 
-    const combinedOptions = $derived({ ...defaultOptions, ...options })
+    // Extract custom token type names from the extensions array
+    const extensionTokenNames = $derived(
+        extensions.flatMap((ext) => ext.extensions?.map((e) => e.name) ?? [])
+    )
+
+    // Create a scoped Marked instance and extract its resolved defaults
+    const extensionDefaults = $derived(
+        extensions.length > 0 ? new Marked(...extensions).defaults : {}
+    )
+
+    const combinedOptions = $derived({ ...defaultOptions, ...extensionDefaults, ...options })
     const slugger = new Slugger()
 
     const tokens = $derived.by(() => {
@@ -106,10 +118,13 @@
             : defaultRenderers.html
     })
 
-    // Collect markdown snippet overrides (keys matching renderer names)
+    // All renderer keys: built-in + extension token names
+    const allRendererKeys = $derived([...rendererKeysInternal, ...extensionTokenNames])
+
+    // Collect markdown snippet overrides (keys matching renderer names or extension token names)
     const snippetOverrides = $derived(
         Object.fromEntries(
-            rendererKeysInternal
+            allRendererKeys
                 .filter((key) => key in rest && rest[key] != null)
                 .map((key) => [key, rest[key]])
         )
@@ -118,15 +133,15 @@
     // Collect HTML snippet overrides (keys matching html_<tag>)
     const htmlSnippetOverrides = $derived(
         Object.fromEntries(
-            htmlRendererKeysInternal
-                .filter((key) => `html_${key}` in rest && rest[`html_${key}`] != null)
-                .map((key) => [key, rest[`html_${key}`]])
+            Object.entries(rest)
+                .filter(([key, val]) => key.startsWith('html_') && val != null)
+                .map(([key, val]) => [key.slice(5), val])
         )
     )
 
     // Passthrough: everything that isn't a known snippet override
     const snippetKeySet = $derived(
-        new Set([...rendererKeysInternal, ...htmlRendererKeysInternal.map((k) => `html_${k}`)])
+        new Set([...allRendererKeys, ...Object.keys(rest).filter((k) => k.startsWith('html_'))])
     )
     const passThroughProps = $derived(
         Object.fromEntries(Object.entries(rest).filter(([key]) => !snippetKeySet.has(key)))

package/dist/index.d.ts

@@ -59,5 +59,7 @@ export { htmlRendererKeysInternal as htmlRendererKeys, rendererKeysInternal as r
  */
 export { MemoryCache } from './utils/cache.js';
 export { TokenCache, tokenCache } from './utils/token-cache.js';
+/** Re-exported `MarkedExtension` type for the `extensions` prop. */
+export type { MarkedExtension } from 'marked';
 /** Re-exported types for consumer convenience. */
 export type { BlockquoteSnippetProps, BrSnippetProps, CodeSnippetProps, CodespanSnippetProps, DelSnippetProps, EmSnippetProps, EscapeSnippetProps, HeadingSnippetProps, HrSnippetProps, HtmlRenderers, HtmlSnippetOverrides, HtmlSnippetProps, ImageSnippetProps, LinkSnippetProps, ListItemSnippetProps, ListSnippetProps, ParagraphSnippetProps, RawTextSnippetProps, RendererComponent, Renderers, SnippetOverrides, StrongSnippetProps, SvelteMarkdownOptions, SvelteMarkdownProps, TableBodySnippetProps, TableCellSnippetProps, TableHeadSnippetProps, TableRowSnippetProps, TableSnippetProps, TextSnippetProps, Token, TokensList };

package/dist/types.d.ts

@@ -17,7 +17,7 @@
  *
  * @packageDocumentation
  */
-import type { Token, TokensList } from 'marked';
+import type { MarkedExtension, Token, TokensList } from 'marked';
 import type { Snippet } from 'svelte';
 import type { MarkedOptions, Renderers } from './utils/markdown-parser.js';
 import type { HtmlKey } from './utils/rendererKeys.js';
@@ -152,6 +152,29 @@ export type SvelteMarkdownProps<T extends Renderers = Renderers> = {
      * generation settings.  Merged with {@link defaultOptions}.
      */
     options?: Partial<SvelteMarkdownOptions>;
+    /**
+     * Array of marked extensions to apply when parsing.
+     *
+     * Internally creates a scoped `Marked` instance, extracts its resolved
+     * defaults, and merges them into the parser options so the lexer
+     * recognises any custom token types the extensions define.
+     *
+     * Extension token names are also used to collect snippet overrides,
+     * enabling both component-renderer and snippet-based rendering of
+     * custom tokens.
+     *
+     * @defaultValue `[]`
+     *
+     * @example
+     * ```svelte
+     * <SvelteMarkdown
+     *   source={markdown}
+     *   extensions={[markedKatex({ throwOnError: false })]}
+     *   renderers={{ inlineKatex: KatexRenderer, blockKatex: KatexRenderer }}
+     * />
+     * ```
+     */
+    extensions?: MarkedExtension[];
     /**
      * When `true`, the source is parsed with `Lexer.lexInline()` instead of
      * `Lexer.lex()`, producing only inline tokens (no block elements).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-markdown",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Fast, customizable markdown renderer for Svelte with built-in caching, TypeScript support, and Svelte 5 runes",
   "keywords": [
     "svelte",
@@ -74,12 +74,13 @@
     "@playwright/cli": "^0.1.1",
     "@playwright/test": "^1.58.2",
     "@sveltejs/adapter-auto": "^7.0.1",
-    "@sveltejs/kit": "^2.52.0",
+    "@sveltejs/kit": "^2.52.2",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/svelte": "^5.3.1",
     "@testing-library/user-event": "^14.6.1",
+    "@types/katex": "^0.16.8",
     "@types/node": "^25.2.3",
     "@typescript-eslint/eslint-plugin": "^8.56.0",
     "@typescript-eslint/parser": "^8.56.0",
@@ -93,13 +94,15 @@
     "globals": "^17.3.0",
     "husky": "^9.1.7",
     "jsdom": "^28.1.0",
+    "katex": "^0.16.28",
+    "marked-katex-extension": "^5.1.7",
     "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
-    "prettier-plugin-svelte": "^3.4.1",
+    "prettier-plugin-svelte": "^3.5.0",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "publint": "^0.3.17",
-    "svelte": "^5.51.3",
-    "svelte-check": "^4.4.0",
+    "svelte": "^5.53.0",
+    "svelte-check": "^4.4.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.56.0",
     "vite": "^7.3.1",
@@ -123,7 +126,7 @@
     "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
     "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
     "dev": "vite dev",
-    "dev:all": "concurrently -k -n pkg,docs -c green,cyan \"pnpm -w -r --filter @humanspeak/svelte-motion run dev:pkg\" \"pnpm --filter docs run dev\"",
+    "dev:all": "concurrently -k -n pkg,docs -c green,cyan \"pnpm -w -r --filter @humanspeak/svelte-markdown run dev:pkg\" \"pnpm --filter docs run dev\"",
     "dev:pkg": "svelte-kit sync && svelte-package --watch",
     "format": "prettier --write .",
     "lint": "prettier --check . && eslint .",