SwiftFastMarkdown

A high-performance, SwiftUI-native markdown parser and renderer for iOS 18+ and macOS 15+.

Built with Carmack-level rigor: measurable claims, testable contracts, no magic.

Features

• Blazing Fast: md4c-based parser achieves sub-millisecond parsing for typical documents
• Zero-Copy IR: ByteRange references into source data minimize allocations
• SwiftUI Native: First-class SwiftUI views with stable identity for efficient diffing
• Streaming Support: Incremental O(n) parser for real-time AI chat interfaces
• Render Caching: CachedAttributedStringRenderer for near-instant repeated renders
• GFM Extensions: Tables, task lists, strikethrough, autolinks via md4c flags
• Syntax Highlighting: Pluggable protocol with thread-safe highlight.js implementation
• iOS 26 Liquid Glass: Native glass effects with iOS 18 material fallback
• 106 Tests: Comprehensive test coverage including CommonMark spec compliance

Performance

Optimization Flags Applied:

• Swift: -Ounchecked, -disable-actor-data-race-checks
• C (md4c): -O3, -ffast-math

Metric	Result	Target	Status
Parse 10KB	0.191ms	<1ms	✅ 5.2x better
Render 10KB	~3.7ms	<5ms	✅ 25% headroom
Chunk parse	0.008ms	<0.5ms	✅ 62x better

Build Command:

swift build -c release

Applied Optimizations

Optimization	Impact	Status
Swift 6 -Ounchecked	Parse 5.2x better	✅ Applied
Concurrency checks disabled	Chunk parse 62x better	✅ Applied
C -O3 for md4c	Parse 2% better	✅ Applied
AttributedString Caching	Near-instant repeated renders	✅ Applied

Future Optimizations (Investigated)

Optimization	Effort	Expected Impact	Notes
LTO (Link-Time Optimization)	Medium	3-4%	⚠️ Breaks Swift 6.2 build (known issue)
SIMD/Vectorization	Medium	~0%	md4c is state-machine based, not data-parallel
Profile-Guided Optimization (PGO)	High	10-20%	Requires instrumented builds, real workloads
Swift 6 Embedded Mode	Low	0% speed	Reduces binary size only
CoreText Bypass	High	20-30%	Sacrifices SwiftUI AttributedString compatibility

Note: LTO showed 3.9% render improvement in testing but causes link errors with Swift 6.2. This is a known Swift toolchain issue that may be resolved in future releases.

Quick Start

import SwiftFastMarkdown

// Simple rendering
let document = MarkdownParser.parse("# Hello **World**")
MarkdownView(document: document)

// Streaming for AI chat
StreamingMarkdownView(content: $streamingContent, isStreaming: true)

// Cached rendering for repeated renders (SwiftUI previews, etc.)
let cachedRenderer = CachedAttributedStringRenderer()
let attributed = await cachedRenderer.render(document, style: .default)

See HOWTO.md for comprehensive usage guide.

Installation

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/mneves/swift-fast-markdown.git", from: "1.0.1")
]

Core Components

Component	Purpose
MarkdownParser	Static document parsing
IncrementalMarkdownParser	Streaming/chunked parsing
MarkdownView	Rich SwiftUI rendering
FastMarkdownText	Lightweight AttributedString rendering
StreamingMarkdownView	Real-time streaming with binding
AsyncStreamMarkdownView	AsyncSequence-based streaming

Architecture

┌─────────────────────────────────────────────────────────────┐
│                   SwiftFastMarkdown v1.0.1                  │
├─────────────────────────────────────────────────────────────┤
│  Layer 3: Rendering                                         │
│  ├── MarkdownView (rich, block-level views)                 │
│  ├── FastMarkdownText (AttributedString fast path)          │
│  ├── StreamingMarkdownView (real-time streaming)            │
│  └── Liquid Glass (iOS 26) / Material (iOS 18) fallback     │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: IR (Intermediate Representation)                  │
│  ├── MarkdownDocument (Sendable, Equatable)                 │
│  ├── MarkdownBlock (stable IDs for SwiftUI diffing)         │
│  └── ByteRange (zero-copy string extraction)                │
├─────────────────────────────────────────────────────────────┤
│  Layer 1: Parser                                            │
│  ├── md4c (CommonMark 0.31 + GFM extensions)                │
│  └── Push-model callbacks → Swift IR builder                │
└─────────────────────────────────────────────────────────────┘

GFM Extensions

Extension	Example	Status
Tables	| A | B |	✅
Task Lists	- [x] Done	✅
Strikethrough	~~deleted~~	✅
Autolinks	www.example.com	✅

Thread Safety

All public APIs are thread-safe:

• MarkdownParser - Stateless, safe for concurrent use
• IncrementalMarkdownParser - Internal locking via NSLock
• HighlighterSwiftEngine - Actor with dedicated queue for JavaScriptCore thread-affinity
• LRUCache - Wrapped in actor for thread-safe access

Requirements

• iOS 18.0+ / macOS 15.0+
• Swift 6.0+
• Xcode 16.0+

Documentation

• HOWTO.md - Comprehensive usage guide with examples
• CHANGELOG.md - Version history and release notes

Acknowledgments

Special thanks to Thomas Ricouard (@Dimillian) for his excellent Swift/SwiftUI Skills that helped ensure this library follows best practices for SwiftUI performance, Liquid Glass implementation, Swift concurrency, and UI patterns.

License

Apache License 2.0. See LICENSE for details.