README.md

SwiftCommonMark

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

Usage

You can create a Document by providing a CommonMark string.

let document = Document(
    #"""
    It's very easy to make some words **bold** and other words *italic* with Markdown.

    **Want to experiment with Markdown?** Play with the [reference CommonMark
    implementation](https://spec.commonmark.org/dingus/).
    """#
)

And access its abstract syntax tree via the blocks property.

for block in document.blocks {
    switch block {
    case let .blockQuote(blocks):
        // Inspect the nested blocks
    case let .list(list):
        print(list.style) // bullet or ordered
        print(list.spacing) // loose or tight
        for item in list.items {
            // Inspect item.blocks
        }
    case let .code(text, language):
        // A code block
    case let .html(content):
        // An HTML block
    case let .paragraph(inlines):
        // Inspect nested inlines
        for inline in inlines {
            switch inline {
            case let .text(text):
                // Plain text
            case .softBreak:
                // A soft break is usually replaced by a space
            case .lineBreak:
                // A line break
            case let .code(text):
                // Inline code
            case let .html(text):
                // Inline HTML
            case let .emphasis(inlines):
                // Emphasized inlines
            case let .strong(inlines):
                // Strong inlines
            case let .link(inlines, url, title):
                // A link
            case let .image(inlines, url, title):
                // An image
            }
        }
    case let .heading(inlines, level):
        // A heading with the specified level
    case .thematicBreak:
        // A thematic break
    }
}

The MarkdownUI library uses this technique to render a CommonMark Document into an NSAttributedString.

From Swift 5.4 onwards, you can create a Document in a type-safe manner using an embedded DSL.

let document = Document {
    Heading(level: 2) {
        "Markdown lists"
    }
    "Sometimes you want numbered lists:"
    List(start: 1) {
        "One"
        "Two"
        "Three"
    }
    "Sometimes you want bullet points:"
    List {
        "Start a line with a star"
        "Profit!"
        Item {
            "And you can have sub points:"
            List {
                "Like this"
                "And this"
            }
        }
    }
}

You can always get the CommonMark syntax of a document by accessing its description. For instance, calling description in the previous document:

print(document.description)

Produces the following output:

## Markdown lists

Sometimes you want numbered lists:

1.  One
2.  Two
3.  Three

Sometimes you want bullet points:

  - Start a line with a star
  - Profit\!
  - And you can have sub points:
      - Like this
      - And this

Installation

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

• SwiftDocOrg/CommonMark