@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

• 🚀 Full markdown syntax support through Marked
• 💪 Complete TypeScript support with strict typing
• 🎨 Customizable component rendering system
• 🔒 Secure HTML parsing via HTMLParser2
• 🎯 GitHub-style slug generation for headers
• ♿ WCAG 2.1 accessibility compliance
• 🧪 Comprehensive test coverage (vitest and playwright)
• 🔄 Svelte 5 runes compatibility

Installation

npm i -S @humanspeak/svelte-markdown

Or with your preferred package manager:

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

External Dependencies

This package carefully selects its dependencies to provide a robust and maintainable solution:

Core Dependencies

• marked

  • Industry-standard markdown parser
  • Battle-tested in production
  • Extensive security features

• github-slugger

  • GitHub-style heading ID generation
  • Unicode support
  • Collision handling

• htmlparser2

  • High-performance HTML parsing
  • Streaming capabilities
  • Security-focused design

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

TypeScript Support

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

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

Custom Renderer Example

Here's a complete example of a custom renderer with TypeScript support:

<script lang="ts">
    import type { Snippet } from 'svelte'

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

    const { href = '', title = '', text = '', children }: Props = $props()
</script>

<a {href} {title} class="custom-link">
    {@render children?.() ?? text}
</a>

Advanced Features

Table Support with Mixed Content

The package excels at handling complex nested structures and mixed content:

| Type       | Content                                 |
| ---------- | --------------------------------------- |
| Nested     | <div>**bold** and _italic_</div>        |
| Mixed List | <ul><li>Item 1</li><li>Item 2</li></ul> |
| Code       | <code>`inline code`</code>              |

HTML in Markdown

Seamlessly mix HTML and Markdown:

<div style="color: blue">
  ### This is a Markdown heading inside HTML
  And here's some **bold** text too!
</div>

<details>
<summary>Click to expand</summary>

- This is a markdown list
- Inside an HTML details element
- Supporting **bold** and _italic_ text

</details>

Available Renderers

• text - Text within other elements
• paragraph - Paragraph (<p>)
• em - Emphasis (<em>)
• strong - Strong/bold (<strong>)
• hr - Horizontal rule (<hr>)
• blockquote - Block quote (<blockquote>)
• del - Deleted/strike-through (<del>)
• link - Link (<a>)
• image - Image (<img>)
• table - Table (<table>)
• tablehead - Table head (<thead>)
• tablebody - Table body (<tbody>)
• tablerow - Table row (<tr>)
• tablecell - Table cell (<td>/<th>)
• list - List (<ul>/<ol>)
• listitem - List item (<li>)
• heading - Heading (<h1>-<h6>)
• codespan - Inline code (<code>)
• code - Block of code (<pre><code>)
• html - HTML node

Optional List Renderers

For fine-grained styling:

• orderedlistitem - Items in ordered lists
• unorderedlistitem - Items in unordered lists

HTML Renderers

The html renderer is special and can be configured separately to handle HTML elements:

| Element | Description | | -------- | -------------------- | | div | Division element | | span | Inline container | | table | HTML table structure | | thead | Table header group | | tbody | Table body group | | tr | Table row | | td | Table data cell | | th | Table header cell | | ul | Unordered list | | ol | Ordered list | | li | List item | | code | Code block | | em | Emphasized text | | strong | Strong text | | a | Anchor/link | | img | Image |

You can customize HTML rendering by providing your own components:

import type { HtmlRenderers } from '@humanspeak/svelte-markdown'

const customHtmlRenderers: Partial<HtmlRenderers> = {
    div: YourCustomDivComponent,
    span: YourCustomSpanComponent
}

Events

The component emits a parsed event when tokens are calculated:

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

    const handleParsed = (tokens: Token[] | TokensList) => {
        console.log('Parsed tokens:', tokens)
    }
</script>

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

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 |

License

MIT © Humanspeak, Inc.

Credits

Made with ♥ by Humanspeak