CommonMark

A Swift package for working with CommonMark text. It's built on top of libcmark and fully compliant with the CommonMark Spec.

Usage

import CommonMark
letmarkdown=#"""# [Universal Declaration of Human Rights][udhr]## Article 1.All human beings are born free and equal in dignity and rights. They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood.[udhr]: https://www.un.org/en/universal-declaration-human-rights/ "View full version""""#letdocument=tryDocument(markdown)

Inspecting Document Nodes

document.children.count // 3
letheading= document.children[0]as!Heading
heading.headerLevel // 1
heading.children.count // 1
letlink= heading.children[0]as!Link
link.urlString // "https://www.un.org/en/universal-declaration-human-rights/")
link.title // "View full version"
letsubheading= document.children[1]as!Heading
subheading.headerLevel // 2
subheading.children.count // 1
letsubheadingText= subheading.children[0]as!Text
subheadingText.literal // "Article 1."
letparagraph= document.children[2]as!Paragraph
paragraph.description // "All human beings [ ... ]"
paragraph.range.lowerBound // (line: 5, column: 1)
paragraph.range.upperBound // (line: 7, column: 62)

Rendering to HTML, XML, LaTeX, and Manpage

lethtml= document.render(format:.html) // <h1> [ ... ]
letxml= document.render(format:.xml) // <?xml [ ... ]
letlatex= document.render(format:.latex) // \section{ [ ... ]
letmanpage= document.render(format:.manpage) // .SH [ ... ]
// To get back CommonMark text, // you can either render with the `.commonmark` format...
document.render(format:.commonmark) // # [Universal [ ... ]
// ...or call `description`
// (individual nodes also return their CommonMark representation as their description)
document.description // # [Universal [ ... ]

Creating Documents From Scratch

Using Result Builders

In Swift 5.4 and later, you can create CommonMark documents using @resultBuilder initializers.

import CommonMark
letdocument=Document{Heading{Link(urlString:"https://www.un.org/en/universal-declaration-human-rights/",
title:"View full version"){"Universal Declaration of Human Rights"}}Section{ // sections increase the level of contained headings
Heading{"Article 1."} // this is a second-level heading
}
// block-level strings are parsed as CommonMark literals
""" **All** human beings are born free and equal in dignity and rights. They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood."""}

Using the Conventional Approach

The following code produces the same result as the preceding example, using conventional Swift initializers.

letlink=Link(urlString:"https://www.un.org/en/universal-declaration-human-rights/",
title:"View full version", text:"Universal Declaration of Human Rights")letheading=Heading(level:1, children:[link])letsubheading=Heading(level:2, text:"Article 1.")letparagraph=Paragraph(children:#"""All human beings are born free and equal in dignity and rights.They are endowed with reason and conscienceand should act towards one another in a spirit of brotherhood."""#.split(separator:"\n").flatMap{[Text(String($0)),SoftLineBreak()]})Document(children:[heading, subheading, paragraph]).description == document.description // true

CommonMark Spec Compliance

This package passes all of the 649 test cases in the latest version (0.29) of the CommonMark Spec:

$ swift test Executed 649 tests, with 0 failures (0 unexpected) in 0.178 (0.201) seconds

Requirements

• Swift 5.1+

Installation

Swift Package Manager

Add the CommonMark package to your target dependencies in Package.swift:

import PackageDescription
letpackage=Package(
name:"YourProject",
dependencies:[.package(
url:"https://github.com/SwiftDocOrg/CommonMark",
from:"0.5.1"),])

Then run the swift build command to build your project.

License

MIT

Contact

Mattt (@mattt)