MarkdownUI Documentation

MarkdownUI is a library for displaying and customizing Markdown text in SwiftUI. It is compatible with the GitHub Flavored Markdown Spec and supports:

• Images
• Headings
• Lists (including task lists)
• Blockquotes
• Code blocks
• Tables
• Thematic breaks
• Styled text and links

To use MarkdownUI in a Swift Package Manager project, add the repository URL to your Package.swift dependencies and include MarkdownUI as a dependency for your target. Finally, import MarkdownUI in your source files.

// In Package.swift
.package(url: "https://github.com/gonzalezreal/swift-markdown-ui", from: "2.0.2")

.target(name: "<target>", dependencies: [
  .product(name: "MarkdownUI", package: "swift-markdown-ui")
]),

To improve performance, you can parse a Markdown string into a MarkdownContent value in your model layer. This prevents the Markdown view from having to perform the parsing step during view updates.

// Somewhere in the model layer
let content = MarkdownContent("You can try **CommonMark** [here](https://spec.commonmark.org/dingus/).")

// Later in the view layer
var body: some View {
  Markdown(self.model.content)
}

You can create a custom theme by instantiating an empty Theme and chaining text and block style modifiers. This allows you to define a cohesive look for all Markdown elements in one place.

extension Theme {
  static let fancy = Theme()
    .code {
      FontFamilyVariant(.monospaced)
      FontSize(.em(0.85))
    }
    .link {
      ForegroundColor(.purple)
    }
    // More text styles...
    .paragraph {
      configuration in
      configuration.label
        .relativeLineSpacing(.em(0.25))
        .markdownMargin(top: 0, bottom: 16)
    }
    .listItem {
      configuration in
      configuration.label
        .markdownMargin(top: .em(0.25))
    }
    // More block styles...
}

Use the markdownTextStyle(_:textStyle:) modifier to override a specific text style (e.g., \.code) from the current theme.

Markdown {
  """
  Use `git status` to list all new or modified files
  that haven't yet been committed.
  """
}
.markdownTextStyle(\.code) {
  FontFamilyVariant(.monospaced)
  FontSize(.em(0.85))
  ForegroundColor(.purple)
  BackgroundColor(.purple.opacity(0.25))
}

MarkdownUI 2 is a complete rewrite that introduces GitHub Flavored Markdown support, native SwiftUI rendering, and a new customization system using Theme, TextStyle, and BlockStyle.

Minimum Requirements

• macOS 12.0+, iOS 15.0+, tvOS 15.0+, watchOS 8.0+
• Note: Features like tables or multi-image paragraphs require macOS 13.0+, iOS 16.0+, tvOS 16.0+, or watchOS 9.0+.

You can customize the appearance of a Markdown view or an entire view hierarchy by applying a theme using the markdownTheme(_:) modifier. Built-in themes like .gitHub are available.

Markdown {
  """
  You can quote text with a `>`.

  > Outside of a dog, a book is man's best friend. Inside of a
  > dog it's too dark to read.

  – Groucho Marx
  """
}
.markdownTheme(.gitHub)

The simplest way to display Markdown is to pass a Markdown string directly to the Markdown view initializer. This view supports images, headings, lists, task lists, blockquotes, code blocks, tables, and thematic breaks.

let markdownString = """
  ## Try MarkdownUI

  **MarkdownUI** is a native Markdown renderer for SwiftUI
  compatible with the
  [GitHub Flavored Markdown Spec](https://github.github.com/gfm/).
  """

var body: some View {
  Markdown(markdownString)
}

Instead of a raw string, you can use the Markdown content builder to compose content using an expressive domain-specific language (DSL). This allows you to mix Markdown strings with structured components like Heading, Paragraph, Strong, and InlineLink.

var body: some View {
  Markdown {
    """
    ## Using a Markdown Content Builder
    Use Markdown strings or an expressive domain-specific language
    to build the content.
    """
    Heading(.level2) {
      "Try MarkdownUI"
    }
    Paragraph {
      Strong("MarkdownUI")
      " is a native Markdown renderer for SwiftUI"
      " compatible with the "
      InlineLink(
        "GitHub Flavored Markdown Spec",
        destination: URL(string: "https://github.github.com/gfm/")!
      )
      "."
    }
  }
}

Use the markdownBlockStyle(_:body:) modifier to override a specific block style (e.g., \.blockquote) while leaving other styles untouched. The closure provides a configuration object to customize the block's label and appearance.

Markdown {
  """
  You can quote text with a `>`.

  > Outside of a dog, a book is man's best friend. Inside of a
  > dog it's too dark to read.

  – Groucho Marx
  """
}
.markdownBlockStyle(\.blockquote) {
  configuration in
  configuration.label
    .padding()
    .markdownTextStyle {
      FontCapsVariant(.lowercaseSmallCaps)
      FontWeight(.semibold)
      BackgroundColor(nil)
    }
    .overlay(alignment: .leading) {
      Rectangle()
        .fill(Color.teal)
        .frame(width: 4)
    }
    .background(Color.teal.opacity(0.5))
}

You can customize the appearance of Markdown content by applying built-in themes using the .markdownTheme(_:) modifier. For example, applying .gitHub will change the styling to match GitHub's aesthetic.

Markdown {
  """
  You can quote text with a `>`.

  > Outside of a dog, a book is man's best friend. Inside of a
  > dog it's too dark to read.

  – Groucho Marx
  """
}
.markdownTheme(.gitHub)