Parse and create CommonMark documents in Swift.

What's New

SwiftCommonMark 1.0.0


Breaking changes:

  • Updated Document initializers.
  • Removed Document.applyingTransform(:) method.
  • Removed Document.imageURLs property.
  • Use element types as the associated values in Inline and Block enums.
  • @BlockBuilder has been replaced by @BlockArrayBuilder.
  • @InlineBuilder has been replaced by @InlineArrayBuilder.
  • @ItemBuilder has been replaced by @ItemArrayBuilder.


  • Added renderCommonMark() and renderHTML(options:) to Document, Block and Inline.
  • Added documentation for public APIs
  • Embedded cmark C library.


CI contact: @gonzalezreal

SwiftCommonMark is a library for parsing and creating Markdown documents in Swift, fully compliant with the CommonMark Spec.


A CommonMark Document consists of a sequence of blocks—structural elements like paragraphs, block quotations, lists, headings, rules, and code blocks. Some blocks, like blockquotes and list items, contain other blocks; others, like headings and paragraphs, contain inline text, links, emphasized text, images, code spans, etc.

You can create a Document by passing a CommonMark-formatted String or Data instance to initializers like init(markdown:options:).

do {
  let document = try Document(
    markdown: "You can try **CommonMark** [here](https://spec.commonmark.org/dingus/)."
} catch {
  print("Couldn't parse document.")

From Swift 5.4 onwards, you can create a Document by passing an array of Blocks constructed with a BlockArrayBuilder.

let document = Document {
  Heading(level: 2) {
    "Markdown lists"
  Paragraph {
    "Sometimes you want numbered lists:"
  OrderedList {
  Paragraph {
    "Sometimes you want bullet points:"
  BulletList {
    ListItem {
      Paragraph {
        "Start a line with a "
    ListItem {
    ListItem {
      "And you can have sub points:"
      BulletList {
        "Like this"
        "And this"

You can inspect the elements of a Document by accessing its blocks property.

for block in document.blocks {
  switch block {
  case .blockQuote(let blockQuote):
    for item in blockQuote.items {
      // Inspect the item
  case .bulletList(let bulletList):
    for item in bulletList.items {
      // Inspect the list item
  case .orderedList(let orderedList):
    for item in orderedList.items {
      // Inspect the list item
  case .code(let codeBlock):
  case .html(let htmlBlock):
  case .paragraph(let paragraph):
    for inline in paragraph.text {
      // Inspect the inline
  case .heading(let heading):
    for inline in heading.text {
      // Inspect the inline
  case .thematicBreak:
    // A thematic break

You can get back the CommonMark formatted text for a Document or render it as HTML.

let markdown = document.renderCommonMark()
let html = document.renderHTML()


You can add SwiftCommonMark to an Xcode project by adding it as a package dependency.

  1. From the File menu, select Swift Packages › Add Package Dependency…
  2. Enter https://github.com/gonzalezreal/SwiftCommonMark into the package repository URL text field
  3. Link CommonMark to your application target

Other Libraries


  • Swift Tools 5.3.0
View More Packages from this Author


  • None
Last updated: Tue Feb 27 2024 22:05:36 GMT-1000 (Hawaii-Aleutian Standard Time)