swift-markdown-ui

MarkdownUI Project Introduction

Overview

MarkdownUI is a robust library designed for displaying and customizing Markdown text within SwiftUI applications. It supports a wide array of Markdown features as detailed by the GitHub Flavored Markdown Spec. This support includes, but is not limited to, displaying images, various heading levels, lists (such as task lists), blockquotes, code snippets, tables, and thematic divisions. In addition, it allows for styled text and links.

The library provides versatile theming options, enabling developers to utilize built-in themes or create personalized themes. This level of customization ensures that MarkdownUI can elegantly integrate within any SwiftUI project aesthetics.

Minimum Requirements

MarkdownUI can be utilized on various Apple platforms, having the following system requirements:

• macOS: Version 12.0 or later
• iOS: Version 15.0 or later
• tvOS: Version 15.0 or later
• watchOS: Version 8.0 or later

Some advanced features, such as table displays or multi-image paragraphs, require versions as follows:

• macOS: 13.0+
• iOS: 16.0+
• tvOS: 16.0+
• watchOS: 9.0+

Getting Started

Creating a Markdown View

Creating a Markdown view is initially straightforward. A Markdown view presents richly formatted text relying on Markdown syntax. It supports diverse content types, including images, headings, and lists.

Developers can employ the initializer init(_:baseURL:imageBaseURL:) to render a Markdown view with a straightforward Markdown string. Here's an example:

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

Furthermore, developers can build a Markdown view with the powerful init(baseURL:imageBaseURL:content:) initializer which leverages a Markdown content builder:

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/")!
      )
      "."
    }
  }
}

For models where Markdown content is pre-determined, a MarkdownContent value can be used to prevent repetitive parsing during view construction.

Styling Markdown

MarkdownUI applies a default theme, but developers can modify how content appears using different themes or creating custom ones.

For instance, applying the gitHub theme is done using the markdownTheme(_:) modifier:

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)

Text styles can be specifically overridden using the markdownTextStyle(_:textStyle:) modifier. An example of customizing the code text style is:

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

Developers can also adjust specific block styles using the markdownBlockStyle(_:body:) modifier, tailoring sections like blockquotes without impacting other styles.

Documentation

Online documentation is extensively hosted by the Swift Package Index, available for different MarkdownUI versions. Additionally, there are supplementary resources and articles available to assist developers in making the most out of this library.

Demo and Installation

Complete capabilities of MarkdownUI can be explored through a companion demo project, showcasing practical applications of the library’s features.

For Swift Package Manager

To include MarkdownUI in Swift projects using the Swift Package Manager, the Package.swift file should be amended to include:

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

Then, add "MarkdownUI" as a project dependency.

For Xcode Projects

To add MarkdownUI:

1. Navigate to the File menu and select Add Packages…
2. In the search field, enter https://github.com/gonzalezreal/swift-markdown-ui
3. Link MarkdownUI to the desired application target

By adhering to these guidelines, developers can seamlessly deploy MarkdownUI in their projects, enhancing the capacity to incorporate intricate and attractive markdown content in SwiftUI applications.