SwiftStreamingMarkdown

An iOS and macOS Markdown renderer that offers smooth streaming experiences.

• ⚡ Smooth, high-performance streaming transitions for newly received text
• 🧮 Native inline and block LaTeX math rendering
• 🔗 Inline citation UI for source-grounded LLM responses
• 🎨 Highly configurable typography, theming, and iOS context menus
• 📊 Built-in hooks for analytics and interaction tracking

Catalog

• Demos
• Markdown support
  • Supported
  • Not yet supported
  • Streaming Performance
• Installation
  • Xcode
  • Package.swift
  • Binary Size
• Quick start
• Streaming usage
• Customizing the theme
• Listening for events
• Sample app
• Development
• Contributing
• Security
• License

Demos

Here are a few demos to help you quickly understand this library's capabilities. More can be found in the sample app.

Table	table-demo.mov
LaTeX	math-demo.mov
Customization	customizability-demo.mov
Inline citation
Code block

Markdown support

The renderer targets the subset of CommonMark + GitHub-flavored Markdown that LLM responses actually emit. Unsupported syntax degrades to readable text so streamed responses never break.

Supported

• Headings (# … ######)
• Paragraphs with soft and hard line breaks
• Bold, italic, bold-italic, strikethrough
• Inline code
• Inline links
• Fenced code blocks with language tag
• Block quotes (with nested inlines, lists, and citations)
• Ordered lists
• Unordered lists (with nesting)
• Task lists (- [ ] / - [x]), display-only
• Thematic breaks (---)
• Tables with :---, :---:, ---: column alignment
• Inline LaTeX math via \( … \)
• Display LaTeX math via $$ … $$
• Inline citation pills

Not yet supported

• Images (![alt](url)) — alt text only
• Footnotes ([^1])
• Highlight (==text==), superscript (^x^), subscript (~x~)
• Raw HTML (<details>, <kbd>, <aside>, …) — kept inline as text
• GitHub alerts (> [!NOTE]) — rendered as plain block quotes
• Container directives (::: warning … :::) and admonitions (!!! note)
• Mermaid / PlantUML diagrams — rendered as fenced code

The bundled Kitchen Sink demonstration in the sample app exercises every item above so you can verify the fallback behavior on-device.

Streaming Performance

SwiftStreamingMarkdown includes built-in animations for streaming content as new text arrives. It is designed to keep rendering smooth while minimizing main-thread work. The chart below compares its performance against popular Markdown libraries that do not provide built-in streaming support.

Profiling was performed on an iPhone XS using the sample app while continuously streaming content and scrolling. Even under this demanding workload on older hardware, SwiftStreamingMarkdown maintains smooth rendering without noticeable UI stalls.

SwiftStreamingMarkdown
Markdown library without streaming support

Installation

SwiftStreamingMarkdown is distributed exclusively as a Swift Package.

Xcode

1. Choose File ▸ Add Package Dependencies…
2. Enter https://github.com/microsoft/SwiftStreamingMarkdown
3. Select the version rule you want (e.g. Up to next minor) and add the SwiftStreamingMarkdown product to your app target.

Package.swift

.package(url: "https://github.com/microsoft/SwiftStreamingMarkdown", from: "0.1.0"),

.target(
  name: "MyApp",
  dependencies: [
    .product(name: "SwiftStreamingMarkdown", package: "SwiftStreamingMarkdown")
  ]
)

Binary Size

Integrating SwiftStreamingMarkdown adds approximately 1 MB to your app's App Store download size. The increase comes from the rendering engine and its dependencies (swift-markdown, cmark-gfm, iosMath for LaTeX, HighlightSwift for code syntax highlighting) and bundled resources (math font, syntax-highlighting theme). Actual size varies with architecture slices and App Store compression.

Quick start

The simplest entry point is MarkdownView, which parses and renders a static string of Markdown using the default theme:

import SwiftUI
import SwiftStreamingMarkdown

struct ContentView: View {
  var body: some View {
    ScrollView {
      MarkdownView(text: """
      # Hello, **world!**

      SwiftStreamingMarkdown supports tables, lists, code blocks, and
      inline `code`.

      ```swift
      print("Hello, world!")
      ```
      """)
      .padding()
    }
  }
}

Streaming usage

For chat-style UIs that grow the Markdown source over time, use StreamedMarkdownView. It takes a StreamedMarkdownSource whose text property yields progressively larger snapshots of the Markdown source (each emission is the full source so far, not a delta) and incrementally parses and renders them as they arrive.

import SwiftUI
import SwiftStreamingMarkdown

class ChatResponseSource: ObservableObject, StreamedMarkdownSource {
  var text: AsyncStream<String> { ... }
}

struct ChatBubble: View {
  @EnvironmentObject var source: ChatResponseSource

  var body: some View {
    StreamedMarkdownView(source: source)
  }
}

If you'd rather drive DocumentView directly, parse each snapshot with MarkdownParser.parse(text:config:) and feed the resulting RenderableDocument into your view yourself.

The bundled sample app demonstrates chunked streaming end-to-end with adjustable chunk size and interval, plus auto-scroll wired through a MarkdownListener.

Customizing the theme

MarkdownRenderConfig is the single source of truth for styling. Build one by composing the withXxx helpers on .default:

let config = MarkdownRenderConfig.default
  .withShouldAnimateText(value: true)
  .withHeadingStyle(value: MarkdownRenderConfig.defaultHeadingStyle)
  .withParagraphStyle(value: MarkdownRenderConfig.defaultParagraphStyle)

For finer control, construct MarkdownRenderConfig directly to override the inline, paragraph, heading, list, table, and citation styles in one place.

Listening for events

Conform to MarkdownListener to receive notifications whenever the renderer draws or the user interacts with rendered content (table copy/download taps, context-menu lifecycle, etc.):

final class AnalyticsListener: MarkdownListener {
  func onRender(markdown: RenderableDocument) async { /* ... */ }
  func onTableCopyTap(content: String) async { /* ... */ }
  func onTableDownloadTap(content: String) async { /* ... */ }
  func onContextMenuAppear(id: String, selectedContent: String) async { /* ... */ }
  func onContextMenuTap(id: String, selectedContent: String) async { /* ... */ }
}

MarkdownView(text: source, listener: AnalyticsListener())

The listener is propagated through the SwiftUI environment, so deeply nested rendered subviews observe the same hooks.

Sample app

A SwiftUI sample app lives in Examples/SwiftStreamingMarkdownSample. It includes a streaming demonstration with adjustable chunk size and interval, a settings screen, and a logging MarkdownListener implementation. The sample Xcode project is generated from Examples/SwiftStreamingMarkdownSample/project.yml; run make sample-project to generate and open it in Xcode.

Development

Run make help to see the repo's common development commands. The most useful targets are:

Command	Purpose
make dev-setup	Verify required local tools such as Xcode, SwiftLint, and XcodeGen; warn about optional snapshot diff helpers ImageMagick and diff-image.
make project	Resolve Swift package dependencies and open the package in Xcode.
make generate-sample-project	Generate the sample app project with XcodeGen.
make sample-project	Generate and open the sample app project in Xcode.
make lint	Run swiftlint --strict.
make test	Run the package unit tests with xcodebuild.
make build-sample	Generate and build the sample app.
make ci	Run lint, tests, and the sample-app build.
make cloc	Count code with cloc --vcs=git.

Contributing

Contributions are welcome! Bug reports and feature requests go through the issue templates. See CONTRIBUTING.md for local setup, code style, and the pull-request process.

This project follows the Microsoft Open Source Code of Conduct.

Security

Please follow the responsible-disclosure process described in SECURITY.md. Do not file security issues publicly.

License

SwiftStreamingMarkdown is released under the MIT License. Dependencies are declared in Package.swift; each upstream ships its own license terms via Swift Package Manager.