Skip to content
A macOS framework for parsing text in Markdown format. The supported syntax is based on the CommonMark specification. The framework defines an abstract syntax for Markdown, provides a parser for parsing strings into abstract syntax trees, and comes with generators for creating HTML and attributed strings.
Swift Objective-C
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
MarkdownKit.xcodeproj
MarkdownKitPlayground.playground
Sources
Tests/MarkdownKitTests
.gitignore
CHANGELOG.md
CONTRIBUTING.md
LICENSE
Package.swift
README.md

README.md

Swift MarkdownKit

Platform: macOS Language: Swift 5 IDE: Xcode 10.3 License: Apache

Overview

Swift MarkdownKit is a framework for parsing text in Markdown format. The supported syntax is based on the CommonMark Markdown specification.

Swift MarkdownKit defines an abstract syntax for Markdown, it provides a parser for parsing strings into abstract syntax trees, and comes with generators for creating HTML and attributed strings.

Using the framework

Parsing Markdown

Class MarkdownParser provides a simple API for parsing Markdown in a string. The parser returns an abstract syntax tree representing the Markdown structure in the string:

let markdown = MarkdownParser.standard.parse("""
                 # Header
                 ## Sub-header
                 And this is a **paragraph**.
                 """)
print(markdown)

Executing this code will result in the follwing data structure of type Block getting printed:

document(heading(1, text("Header")),
         heading(2, text("Sub-header")),
         paragraph(text("And this is a "),
                   strong(text("paragraph")),
                   text("."))))

Block is a recursively defined enumeration of cases with associated values (also called an algebraic datatype). Case document refers to the root of a document. It contains a sequence of blocks. In the example above, two different types of blocks appear within the document: heading and paragraph. A heading case consists of a heading level (as its first argument) and heading text (as the second argument). A paragraph case simply consists of text.

Text is represented using the struct Text which is effectively a sequence of TextFragment values. TextFragment is yet another recursively defined enumeration with associated values. The example above shows two different TextFragment cases in action: text and strong. Case text represents plain strings. Case strong contains a Text object, i.e. it encapsulates a sequence of TextFragment values which are "marked up strongly".

Configuring the Markdown parser

The Markdown dialect supported by MarkdownParser is defined by two parameters: a sequence of block parsers (each represented as a subclass of BlockParser), and a sequence of inline transformers (each represented as a subclass of InlineTransformer). The initializer of class MarkdownParser accepts both components optionally. The default configuration (neither block parsers nor inline transformers are provided for the initializer) is able to handle Markdown based on the CommonMark specification.

Since MarkdownParser objects are stateless (beyond the configuration of block parsers and inline transformers), there is a predefined default MarkdownParser object accessible via the static property MarkdownParser.standard. This default parsing object is used in the example above.

Processing Markdown

The usage of abstract syntax trees for representing Markdown text has the advantage that it is very easy to process such data, in particular, to transform it and to extract information. Below is a short Swift snippet which illustrates how to process an abstract syntax tree for the purpose of extracting all top-level headers (i.e. this code prints the top-level outline of a text in Markdown format).

let markdown = MarkdownParser.standard.parse("""
                   # First *Header*
                   ## Sub-header
                   And this is a **paragraph**.
                   # Second **Header**
                   And this is another paragraph.
                 """)

func topLevelHeaders(doc: Block) -> [String] {
  guard case .document(let topLevelBlocks) = doc else {
    preconditionFailure("markdown block does not represent a document")
  }
  var outline: [String] = []
  for block in topLevelBlocks {
    if case .heading(1, let text) = block {
      outline.append(text.rawDescription)
    }
  }
  return outline
}

let headers = topLevelHeaders(doc: markdown)
print(headers)

This will print an array with the following two entries:

["First Header", "Second Header"]

Converting Markdown into other formats

Swift MarkdownKit currently provides two different generators, i.e. Markdown processors which output, for a given Markdown document, a corresponding representation in a different format.

HtmlGenerator defines a simple mapping from Markdown into HTML. Here is an example for the usage of the generator:

let html = HtmlGenerator.standard.generate(doc: markdown)

There are currently no means to customize HtmlGenerator beyond subclassing. Here is an example that defines a customized HTML generator which formats blockquote Markdown blocks using HTML tables:

open class CustomizedHtmlGenerator: HtmlGenerator {
  open override func generate(block: Block, tight: Bool = false) -> String {
    switch block {
      case .blockquote(let blocks):
        return "<table><tbody><tr><td style=\"background: #bbb; width: 0.2em;\"  />" +
               "<td style=\"width: 0.2em;\" /><td>\n" +
               self.generate(blocks: blocks) +
               "</td></tr></tbody></table>\n"
      default:
        return super.generate(block: block, tight: tight)
    }
  }
}

Swift MarkdownKit also comes with a generator for attributed strings. AttributedStringGenerator uses a customized HTML generator internally to define the translation from Markdown into NSAttributedString. The initializer of AttributedStringGenerator provides a number of parameters for customizing the style of the generated attributed string.

let generator = AttributedStringGenerator(fontSize: 12,
                                          fontFamily: "Helvetica, sans-serif",
                                          fontColor: "#33C",
                                          h1Color: "#000")
let attributedStr = generator.generate(doc: markdown)

Using the command-line tool

The Swift MarkdownKit Xcode project also implements a very simple command-line tool for either translating a single Markdown text file into HTML or for translating all Markdown files within a given directory into HTML.

The tool is provided to serve as a basis for customization to specific use cases. The simplest way to build the binary is to use the Swift Package Manager (SPM):

> git clone https://github.com/objecthub/swift-markdownkit.git
Cloning into 'swift-markdownkit'...
remote: Enumerating objects: 70, done.
remote: Counting objects: 100% (70/70), done.
remote: Compressing objects: 100% (54/54), done.
remote: Total 70 (delta 13), reused 65 (delta 11), pack-reused 0
Unpacking objects: 100% (70/70), done.
> cd swift-markdownkit
> swift build -c release
[1/3] Compiling Swift Module 'MarkdownKit' (25 sources)
[2/3] Compiling Swift Module 'MarkdownKitProcess' (1 sources)
[3/3] Linking ./.build/x86_64-apple-macosx/release/MarkdownKitProcess
> ./.build/x86_64-apple-macosx/release/MarkdownKitProcess
usage: mdkitprocess <source> [<target>]
where: <source> is either a Markdown file or a directory containing Markdown files
       <target> is either an HTML file or a directory in which HTML files are written

Known issues

There are a number of limitations and known issues:

  • The Markdown parser currently does not fully support link reference definitions. It is possible to define a link reference, but usage of such references is currently not supported.
  • Escaping of characters is not handled correctly when generating plain text or when generating HTML or attributed strings.

Requirements

The following technologies are needed to build the components of the Swift MarkdownKit framework. The command-line tool can be compiled with the Swift Package Manager, so Xcode is not strictly needed for that. Similarly, just for compiling the framework and trying the command-line tool in Xcode, the Swift Package Manager is not needed.

Copyright

Author: Matthias Zenger (matthias@objecthub.net)
Copyright © 2019 Google LLC.
Please note: This is not an official Google product.

You can’t perform that action at this time.