Down

Build Status MIT licensed CocoaPods Swift 5 macOS iOS tvOS Linux Code Coverage

基于 cmark v0.29.0 构建的,在 Swift 中超快的 Markdown (CommonMark) 渲染引擎。

你的应用在使用它吗?请告诉我们!

如果你正在寻找 iwasrobbed/Down,你找到了!这个仓库的创建者 Rob Phillips 已经将它转移给了我,我将成为主要的维护者。感谢 Rob 将 Down 带到现在的高度,并信任我来继续维护它。

所有指向 iwasrobbed/Down 的现有引用都应该重定向到这个仓库。但是,建议更新这些 URL 以指向这个仓库。

维护者

安装

注意:Swift 支持情况总结在下表中。

Swift 版本 标签
Swift 5.1 >= 0.9.0
Swift 5.0 >= 0.8.1
Swift 4 >= 0.4.x
Swift 3 0.3.x

现在在 master 分支上以及任何标签 >= 0.8.1 (Swift 4 是 >= 0.4.x, Swift 3 是 0.3.x)

使用 CocoaPods 快速安装

pod 'Down'

使用 Carthage 安装

github "johnxnguyen/Down"

由于 Carthage 在平台指定方面的限制,你需要使用 Carthage 定义平台。

例如:

carthage update --platform iOS

使用 Swift Package Manager 安装

要将 Down 添加到你的项目中,选择 File → Swift Packages → Add Package Dependency,然后输入 Down 的 GitHub URL。 有关详细说明,请参阅 Adding Package Dependencies to Your App

或者手动安装

  1. 克隆这个仓库
  2. 将 Down 项目拖放到你的工作区文件中,并将该框架添加到嵌入式框架部分
  3. 构建并运行你的应用程序
  4. ?
  5. 成功

强大的性能

cmark 可以在眨眼之间渲染 Markdown 版本的《战争与和平》(在一台有十年历史的笔记本电脑上耗时 127 毫秒,而眨眼需要 100-400 毫秒)。 在我们的 基准测试 中,cmark 比原始的 Markdown.pl 快 10,000 倍,并且与目前最快的 Markdown 处理器相当。

该库已经使用 american fuzzy lop 进行了广泛的模糊测试。 测试套件包括一些病态的用例,这些用例会导致许多其他 Markdown 解析器运行缓慢(例如,数千层深的嵌套括号文本或块引用)。

输出格式

视图渲染

DownView 类提供了一种非常简单的方法来解析 UTF-8 编码的 Markdown 字符串,并将其转换为可以添加到任何视图的 Web 视图

let downView = try? DownView(frame: self.view.bounds, markdownString: "**Oh Hai**") {
    // Optional callback for loading finished
}
// Now add to view or constrain w/ Autolayout
// Or you could optionally update the contents at some point:
try? downView?.update(markdownString:  "## [Google](https://google.com)") {
    // Optional callback for loading finished
}

渲染此 README 的 Meta 示例

Example gif

解析 API

如果你只是想要开箱即用的解析和转换设置,那么 Down 结构体可以满足你的所有需求。

let down = Down(markdownString: "## [Down](https://github.com/johnxnguyen/Down)")

// Convert to HTML
let html = try? down.toHTML()
// "<h2><a href=\"https://github.com/johnxnguyen/Down\">Down</a></h2>\n"

// Convert to XML
let xml = try? down.toXML()
// "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE document SYSTEM \"CommonMark.dtd\">\n<document xmlns=\"http://commonmark.org/xml/1.0\">\n  <heading level=\"2\">\n    <link destination=\"https://github.com/johnxnguyen/Down\" title=\"\">\n      <text>Down</text>\n    </link>\n  </heading>\n</document>\n"

// Convert to groff man
let man = try? down.toGroff()
// ".SS\nDown (https://github.com/johnxnguyen/Down)\n"

// Convert to LaTeX
let latex = try? down.toLaTeX()
// "\\subsection{\\href{https://github.com/johnxnguyen/Down}{Down}}\n"

// Convert to CommonMark Markdown
let commonMark = try? down.toCommonMark()
// "## [Down](https://github.com/johnxnguyen/Down)\n"

// Convert to an attributed string
let attributedString = try? down.toAttributedString()
// NSAttributedString representation of the rendered HTML;
// by default, uses a stylesheet that matches NSAttributedString's default font,
// but you can override this by passing in your own, using the 'stylesheet:' parameter.

// Convert to abstract syntax tree
let ast = try? down.toAST()
// Returns pointer to AST that you can manipulate

渲染粒度

如果你希望对要支持的输出类型有更高的粒度,你可以创建自己的结构体,至少符合以下可渲染协议之一

示例

public struct MarkdownToHTML: DownHTMLRenderable {
    /**
     A string containing CommonMark Markdown
    */
    public var markdownString: String

    /**
     Initializes the container with a CommonMark Markdown string which can then be rendered as HTML using `toHTML()`

     - parameter markdownString: A string containing CommonMark Markdown

     - returns: An instance of Self
     */
    @warn_unused_result
    public init(markdownString: String) {
        self.markdownString = markdownString
    }
}

DownView 的配置

可以使用你自己的 HTML/CSS 的自定义 bundle 配置 DownView,或者进行诸如支持动态类型或自定义字体等操作。它是完全可配置的。

可以在 DownView 的实例化函数 中找到此选项。

防止缩放

DownView 的默认实现允许缩放渲染的内容。 如果你想禁用此功能,那么你需要使用自定义 bundle 实例化 DownView,其中 index.html 中的 viewport 已被赋值为 user-scalable=no。 更多信息可以在这里找到。

选项

每个协议都有影响渲染或解析的选项

/**
 Default options
*/
public static let `default` = DownOptions(rawValue: 0)

// MARK: - Rendering Options

/**
 Include a `data-sourcepos` attribute on all block elements
*/
public static let sourcePos = DownOptions(rawValue: 1 << 1)

/**
 Render `softbreak` elements as hard line breaks.
*/
public static let hardBreaks = DownOptions(rawValue: 1 << 2)

/**
 Suppress raw HTML and unsafe links (`javascript:`, `vbscript:`,
 `file:`, and `data:`, except for `image/png`, `image/gif`,
 `image/jpeg`, or `image/webp` mime types).  Raw HTML is replaced
 by a placeholder HTML comment. Unsafe links are replaced by
 empty strings. Note that this option is provided for backwards
 compatibility, but safe mode is now the default.
*/
public static let safe = DownOptions(rawValue: 1 << 3)

/**
 Allow raw HTML and unsafe links. Note that safe mode is now
 the default, and the unsafe option must be used if rendering
 of raw HTML and unsafe links is desired.
*/
public static let unsafe = DownOptions(rawValue: 1 << 17)

// MARK: - Parsing Options

/**
 Normalize tree by consolidating adjacent text nodes.
*/
public static let normalize = DownOptions(rawValue: 1 << 4)

/**
 Validate UTF-8 in the input before parsing, replacing illegal
 sequences with the replacement character U+FFFD.
*/
public static let validateUTF8 = DownOptions(rawValue: 1 << 5)

/**
 Convert straight quotes to curly, --- to em dashes, -- to en dashes.
*/
public static let smart = DownOptions(rawValue: 1 << 6)

/**
 Combine smart typography with HTML rendering.
*/
public static let smartUnsaFe = DownOptions(rawValue: (1 << 17) + (1 << 6))

支持

Swift; iOS 9+, tvOS 9+, macOS 10.11+

Markdown 规范

Down 基于 CommonMark 规范构建。

朋友们的一点帮助

请随意 fork 并创建一个 pull request 来修复错误或进行改进,请务必保持一般的编码风格,添加测试,并根据需要添加注释。

致谢

该库是 cmark 的一个封装,cmark 基于 CommonMark Markdown 规范构建。

cmark 版权所有 (c) 2014, John MacFarlane。 查看完整许可