• This repository has been archived on 17/Oct/2021
  • Stars
    star
    179
  • Rank 214,039 (Top 5 %)
  • Language
    Swift
  • License
    MIT License
  • Created almost 5 years ago
  • Updated over 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Create, parse, and render Markdown text according to the CommonMark specification

CommonMark

CI Documentation

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

let markdown = #"""
# [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"
"""#

let document = try Document(markdown)

Inspecting Document Nodes

document.children.count // 3

let heading = document.children[0] as! Heading
heading.headerLevel // 1
heading.children.count // 1

let link = heading.children[0] as! Link
link.urlString // "https://www.un.org/en/universal-declaration-human-rights/")
link.title // "View full version"

let subheading = document.children[1] as! Heading
subheading.headerLevel // 2
subheading.children.count // 1

let subheadingText = subheading.children[0] as! Text
subheadingText.literal // "Article 1."

let paragraph = 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

let html = document.render(format: .html) // <h1> [ ... ]
let xml = document.render(format: .xml) // <?xml [ ... ]
let latex = document.render(format: .latex) // \section{ [ ... ]
let manpage = 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

let document = 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.

let link = Link(urlString: "https://www.un.org/en/universal-declaration-human-rights/",
                title: "View full version", 
                text: "Universal Declaration of Human Rights")
let heading = Heading(level: 1, children: [link])

let subheading = Heading(level: 2, text: "Article 1.")

let paragraph = Paragraph(children: #"""
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.
"""#.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

let package = 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)

More Repositories

1

swift-doc

A documentation generator for Swift projects
Swift
1,683
star
2

DocTest

An experimental tool for testing Swift example code in documentation.
Swift
358
star
3

GraphViz

A Swift package for working with GraphViz
Swift
291
star
4

SwiftSemantics

Uses SwiftSyntax to parse Swift code into its constituent declarations
Swift
224
star
5

swiftdoc.org

Auto-generated documentation for Swift. Command-click no more.
HTML
217
star
6

Markup

A Swift package for working with HTML, XML, and other markup languages, based on libxml2.
Swift
112
star
7

github-wiki-publish-action

GitHub Action that publishes the contents of a directory to your project's wiki
Shell
82
star
8

SwiftMarkup

Parses Swift documentation comments into structured entities
Swift
56
star
9

Git

A Swift package for working with Git, built on top of libgit2.
Swift
48
star
10

swiftdoc-parser

Header parsing and HTML generating utilities for SwiftDoc.org
JavaScript
42
star
11

TAP

A Swift package for the Test Anything Protocol (v13)
Swift
21
star
12

Swift-Semantic-Icons

Icons used by swift-doc to represent Swift code symbols.
20
star
13

DocSetUtil

Apple developer tool for working with .docset bundles
Makefile
19
star
14

StringLocationConverter

Converts String index values into their corresponding line & column numbers
Swift
16
star
15

SwiftPackageManifest

A package for decoding the output of `swift package dump-package`
Swift
15
star
16

Inflection

Swift
10
star
17

api.swiftdoc.org

A JSON API for SwiftDoc.org
JavaScript
8
star
18

swift-api-inventory

Swift
6
star
19

homebrew-formulae

Collection of Homebrew Formulae
Ruby
3
star
20

docsetutil-validate-action

JavaScript
2
star