svelte-markdown: Instructions file for Claude Code

CLAUDE.md

This file provides guidance for AI assistants working with this codebase.

Project Overview

@humanspeak/svelte-markdown is a powerful, customizable markdown renderer for Svelte 5 with TypeScript support. Built as a successor to the original svelte-markdown package by Pablo Berganza, now maintained by Humanspeak, Inc.

• Package: @humanspeak/svelte-markdown
• Homepage: https://markdown.svelte.page
• Repository: https://github.com/humanspeak/svelte-markdown

Key Technologies

• Svelte 5 with runes compatibility
• TypeScript with strict typing
• Marked for markdown parsing
• HTMLParser2 for secure HTML parsing
• github-slugger for heading ID generation
• Vite + SvelteKit for build system

Project Structure

src/
├── lib/
│   ├── index.ts              # Main entry point / exports
│   ├── SvelteMarkdown.svelte # Main component
│   ├── types.ts              # TypeScript types
│   ├── renderers/            # Markdown token renderers
│   │   ├── *.svelte          # Individual renderers (Paragraph, Link, etc.)
│   │   └── html/             # HTML element renderers
│   │       └── *.svelte      # Individual HTML tags (Div, Span, etc.)
│   └── utils/                # Utility functions
│       ├── markdown-parser.ts
│       ├── incremental-parser.ts # Streaming tail-window parser
│       ├── sanitize.ts       # Default URL/attribute sanitizers
│       ├── token-cache.ts    # LRU caching for parsed tokens
│       ├── cache.ts          # Generic memory cache
│       ├── rendererKeys.ts   # Canonical renderer key lists
│       └── unsupported*.ts   # Allow/deny helper utilities
├── routes/                   # SvelteKit routes (for dev/testing)
└── app.d.ts                  # App-level type declarations
tests/                        # Playwright E2E tests
docs/                         # Documentation site

Development Commands

# Development
pnpm dev              # Start dev server
pnpm dev:pkg          # Watch and rebuild package

# Testing
pnpm test             # Run vitest with coverage
pnpm test:only        # Run vitest without coverage
pnpm test:watch       # Run vitest in watch mode
pnpm test:e2e         # Run Playwright E2E tests
pnpm test:all         # Run both unit and E2E tests

# Building
pnpm build            # Build the package
pnpm package          # Create distributable package
pnpm check            # Run svelte-check type checking

# Code Quality — use Trunk, not raw prettier/eslint
trunk fmt             # Format changed files
trunk check           # Lint changed files
trunk check --fix     # Lint changed files and auto-fix