@humanspeak/svelte-markdown 1.0.1 → 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

@@ -25,7 +25,7 @@ A powerful, customizable markdown renderer for Svelte with TypeScript support. B
 - ♿ 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
 
@@ -72,7 +72,8 @@ import type {
     Renderers,
     Token,
     TokensList,
-    SvelteMarkdownOptions
+    SvelteMarkdownOptions,
+    MarkedExtension
 } from '@humanspeak/svelte-markdown'
 ```
 
@@ -352,6 +353,111 @@ You can render arbitrary (non-standard) HTML tags like `<click>`, `<tooltip>`, o
 
 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:
@@ -526,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

@@ -60,6 +60,7 @@
     } from './utils/markdown-parser.js'
     import { parseAndCacheTokens } from './utils/parse-and-cache.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]])
         )
@@ -126,10 +141,7 @@
 
     // Passthrough: everything that isn't a known snippet override
     const snippetKeySet = $derived(
-        new Set([
-            ...rendererKeysInternal,
-            ...Object.keys(rest).filter((k) => k.startsWith('html_'))
-        ])
+        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.1",
+  "version": "1.0.2",
   "description": "Fast, customizable markdown renderer for Svelte with built-in caching, TypeScript support, and Svelte 5 runes",
   "keywords": [
     "svelte",
@@ -80,6 +80,7 @@
     "@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,6 +94,8 @@
     "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.5.0",
@@ -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 .",