├── .gitignore ├── LICENSE.txt ├── readme.md └── en.md /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | .DS_Store 3 | fork 4 | source -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | Blackfriday is distributed under the Simplified BSD License: 2 | 3 | > Copyright © 2011 Russ Ross 4 | > All rights reserved. 5 | > 6 | > Redistribution and use in source and binary forms, with or without 7 | > modification, are permitted provided that the following conditions 8 | > are met: 9 | > 10 | > 1. Redistributions of source code must retain the above copyright 11 | > notice, this list of conditions and the following disclaimer. 12 | > 13 | > 2. Redistributions in binary form must reproduce the above 14 | > copyright notice, this list of conditions and the following 15 | > disclaimer in the documentation and/or other materials provided with 16 | > the distribution. 17 | > 18 | > THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 | > "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 | > LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 21 | > FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 22 | > COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 23 | > INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 24 | > BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 25 | > LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 26 | > CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27 | > LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 28 | > ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29 | > POSSIBILITY OF SUCH DAMAGE. 30 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # russross/blackfriday [![translate-svg]][translate-list] 2 | 3 | 4 | 5 | 6 | 7 | [explain]: http://llever.com/explain.svg 8 | [source]: https://github.com/chinanf-boy/Source-Explain 9 | [translate-svg]: http://llever.com/translate.svg 10 | [translate-list]: https://github.com/chinanf-boy/chinese-translate-list 11 | [size-img]: https://packagephobia.now.sh/badge?p=Name 12 | [size]: https://packagephobia.now.sh/result?p=Name 13 | 14 | 「 Blackfriday{黑色星期五}是一个[markdown][1]处理器，用[Go][2]实现. 」 15 | 16 | [中文](./readme.md) | [english](https://github.com/russross/blackfriday) 17 | 18 | --- 19 | 20 | ## 校对 🀄️ 21 | 22 | 23 | 24 | 25 | 26 | 翻译的原文 | 与日期 | 最新更新 | 更多 27 | ---|---|---|--- 28 | [commit] | ⏰ 2018-09-17 | ![last] | [中文翻译][translate-list] 29 | 30 | [last]: https://img.shields.io/github/last-commit/russross/blackfriday.svg 31 | [commit]: https://github.com/russross/blackfriday/tree/05f3235734ad95d0016f6a23902f06461fcf567a 32 | 33 | 34 | 35 | ### 贡献 36 | 37 | 欢迎 👏 勘误/校对/更新贡献 😊 [具体贡献请看](https://github.com/chinanf-boy/chinese-translate-list#贡献) 38 | 39 | ## 生活 40 | 41 | [If help, **buy** me coffee —— 营养跟不上了，给我来瓶营养快线吧! 💰](https://github.com/chinanf-boy/live-need-money) 42 | 43 | --- 44 | 45 | # Blackfriday[![Build Status][buildsvg]][buildurl][![Godoc][godocv2svg]][godocv2url] 46 | 47 | Blackfriday{黑色星期五}是一个[markdown][1]处理器，用[Go][2]实现. 它对输入是偏执严格的(所以你可以安全地提供用户提供的数据),且它很快,它支持常见的扩展(表格,智能标点符号替换等).并且它对所有 utf-8(unicode)输入都是安全的. 48 | 49 | 目前支持 HTML 输出以及 Smartypants 扩展. 50 | 51 | > 该 Smartypants 扩展，将 ascii 中的引号，连接号，省略号转换为对应的 HTML 等价表示。 52 | 53 | 它起源于 C 的[sundown][3], 并翻译翻译成 Go. 54 | 55 | ### 目录 56 | 57 | 58 | 59 | 60 | - [安装](#%E5%AE%89%E8%A3%85) 61 | - [版本](#%E7%89%88%E6%9C%AC) 62 | - [`dep` 已知问题](#dep-%E5%B7%B2%E7%9F%A5%E9%97%AE%E9%A2%98) 63 | - [用法](#%E7%94%A8%E6%B3%95) 64 | - [v1](#v1) 65 | - [v2](#v2) 66 | - [清理不受信任的内容](#%E6%B8%85%E7%90%86%E4%B8%8D%E5%8F%97%E4%BF%A1%E4%BB%BB%E7%9A%84%E5%86%85%E5%AE%B9) 67 | - [自定义选项,v1](#%E8%87%AA%E5%AE%9A%E4%B9%89%E9%80%89%E9%A1%B9v1) 68 | - [自定义选项,v2](#%E8%87%AA%E5%AE%9A%E4%B9%89%E9%80%89%E9%A1%B9v2) 69 | - [`blackfriday-tool`](#blackfriday-tool) 70 | - [消毒的 anchor 名称](#%E6%B6%88%E6%AF%92%E7%9A%84anchor%E5%90%8D%E7%A7%B0) 71 | - [特征](#%E7%89%B9%E5%BE%81) 72 | - [扩展](#%E6%89%A9%E5%B1%95) 73 | - [其他渲染器](#%E5%85%B6%E4%BB%96%E6%B8%B2%E6%9F%93%E5%99%A8) 74 | - [TODO](#todo) 75 | - [执照](#%E6%89%A7%E7%85%A7) 76 | 77 | 78 | 79 | ## 安装 80 | 81 | Blackfriday 与任何现代 Go 版本兼容. 安装 Go 和 git 后: 82 | 83 | ``` 84 | go get -u gopkg.in/russross/blackfriday.v2 85 | ``` 86 | 87 | 将下载,编译和安装包到您的`$GOPATH`目录层次结构 88 | 89 | ## 版本 90 | 91 | 目前维护和推荐版本的 Blackfriday 是`v2`.它正在自己的分支上开发:, 并且文档可在以下处获得. 92 | 93 | 若使用`go get`获取，它是通过[gopkg.in 网站][6]的`gopkg.in/russross/blackfriday.v2`, 但我们强烈建议使用包管理工具[dep][7]要么[Glide][8]并利用语义版本控制. 使用包管理,您应该导入`github.com/russross/blackfriday`并指定您使用的是 2.0.0 版. 94 | 95 | 与 v1 相比,版本 2 提供了许多改进: 96 | 97 | - 清理-Cleaned up API 98 | - 可单独运行[`Parse`][4],它为文档生成一个抽象语法树 AST 99 | - 最新的错误修复 100 | - 灵活地轻松添加自己的渲染扩展 101 | 102 | 潜在的缺点: 103 | 104 | - 我们的基准测试表明`v2`比`v1`略慢.目前约占球场 15%. 105 | - API 破损.如果您无法负担修改代码，以遵守新 API 并且不太关心新功能,那么`v2`可能不适合您. 106 | - 几个错误的修复拉下了,仍需要向前移植到`v2`.看问题[#348](https://github.com/russross/blackfriday/issues/348)跟踪. 107 | 108 | 如果你仍然对遗产`v1`感兴趣,你可以从`github.com/russross/blackfriday`中导入它.可以在此处找到旧版 v1 的文档: 109 | 110 | ### `dep` 已知问题 111 | 112 | 存在 Blackfriday `v1`*以及*与`dep`的已知问题.目前`dep`将 semver 版本优先于其他任何版本,并选择最新版本,加上它不适用`[[constraint]]`说明者可以传递包裹.因此,如果您使用的是 Blackfriday v1 的东西,则有些东西不能使用`dep`然而,你会得到 Blackfriday v2, 你的第一个依赖将无法建立. 113 | 114 | 它有几个修复,在这里记录: 115 | 116 | 与此同时,`dep`团队正在研究对传递依赖性问题的约束的更通用的解决方案:. 117 | 118 | ## 用法 119 | 120 | ### v1 121 | 122 | 对于基本用法,只需将输入，input 字节切片并调用: 123 | 124 | ``` 125 | output := blackfriday.MarkdownBasic(input) 126 | ``` 127 | 128 | 这使得它没有启用扩展.要获得更有用的功能集,请改用: 129 | 130 | ``` 131 | output := blackfriday.MarkdownCommon(input) 132 | ``` 133 | 134 | ### v2 135 | 136 | 对于最明智的 markdown 处理,只需输入，input 字节切片并调用: 137 | 138 | ```go 139 | output := blackfriday.Run(input) 140 | ``` 141 | 142 | 上面的 input 将被解析,并且输出使用一组最常用的扩展程序进行渲染 . 如果您想要最基本的功能集,与裸 Markdown 规范相对应,请使用: 143 | 144 | ```go 145 | output := blackfriday.Run(input, blackfriday.WithNoExtensions()) 146 | ``` 147 | 148 | ### 清理不受信任的内容 149 | 150 | Blackfriday 本身无法防范恶意内容.如果您正在处理用户提供的 markdown,我们建议您通过 HTML 清理程序运行 Blackfriday 的输出,例如[Bluemonday 忧愁星期一][5]. 151 | 152 | 以下是 Blackfriday 与 Bluemonday 一起使用的简单示例: 153 | 154 | ```go 155 | import ( 156 | "github.com/microcosm-cc/bluemonday" 157 | "gopkg.in/russross/blackfriday.v2" 158 | ) 159 | 160 | // ... 161 | unsafe := blackfriday.Run(input) 162 | html := bluemonday.UGCPolicy().SanitizeBytes(unsafe) 163 | ``` 164 | 165 | ### 自定义选项,v1 166 | 167 | 如果你想自定义选项集,首先得到一个渲染器(目前只有 HTML 输出引擎),然后用它来调用更通用`Markdown`功能.例如,请参阅的实现`MarkdownBasic`和`MarkdownCommon`在`markdown.go`. 168 | 169 | ### 自定义选项,v2 170 | 171 | 如果要自定义选项集,请使用`blackfriday.WithExtensions`,`blackfriday.WithRenderer`和`blackfriday.WithRefOverride`. 172 | 173 | ### `blackfriday-tool` 174 | 175 | 你也可以看看`blackfriday-tool`，有关如何使用它的更完整示例. 使用以下命令下载并安装: 176 | 177 | ``` 178 | go get github.com/russross/blackfriday-tool 179 | ``` 180 | 181 | 这是一个简单的命令行工具,允许您使用独立程序处理 markdown 文件.如果您只是在寻找一些示例代码,您还可以直接在 github 上浏览源代码: 182 | 183 | - 184 | 185 | **请注意**,如果您还没有 Blackfriday, 那可以先安装`blackfriday-tool`，因为除了工具本身之外,还会下载和安装 blackfriday. 工具二进制文件将安装在`$GOPATH/bin`.这是一个静态链接的二进制文件,可以将其复制到您需要的任何位置,而无需担心依赖项和库版本. 186 | 187 | ### 消毒的 anchor 名称 188 | 189 | > 作用如: `This is a header` => `this-is-a-header` 190 | 191 | Blackfriday 包括，一个用于创建与给定输入文本相对应的已消毒 anchor 名称的算法 .该算法用于为标题创建 anchor 点，若`EXTENSION_AUTO_HEADER_IDS`已启用. 该算法具有规范, 因此其他包可以创建兼容的 anchor 名称和到这些 anchor 的链接. 192 | 193 | 规范位于. 194 | 195 | [`SanitizedAnchorName`](https://godoc.org/github.com/russross/blackfriday#SanitizedAnchorName)正是公开的函数,并可用于创建 blackfriday 生成的 anchor 名称的兼容链接.该算法也在一个小的独立包中实现[`github.com/shurcooL/sanitized_anchor_name`](https://godoc.org/github.com/shurcooL/sanitized_anchor_name).它对于需要小包，并且不需要 blackfriday 的完整功能的客户来说非常有用. 196 | 197 | ## 特征 198 | 199 | 支持[sundown][3]的所有功能,包括: 200 | 201 | - **兼容性**. 通过 Markdown v1.0.3 测试套件，且带`--tidy`选项. 若没有`--tidy`,差异主要在于空格和 HTML 实体转义,其中 blackfriday 更一致和清洁. 202 | 203 | - **常见的扩展**,包括表格支持,围栏代码块,自动链接,删除线,非严格强调(加粗)等. 204 | 205 | - **安全**.Blackfriday 在解析时是偏执狂,可以安全地提供不受信任的用户输入，而不用担心会发生不良事件.测试套件压力会测试这个，且结果没有已知的输入使其崩溃. 如果你找到一个,请告诉我,并把它输入给我. 206 | 207 | 注意:在此上下文中的"安全"是指*仅限运行时安全*.为了保护自己免受不受信任内容中的 JavaScript 注入,请参阅[这个例子](https://github.com/russross/blackfriday#sanitize-untrusted-content). 208 | 209 | - **快速处理**.它足够快,可以在大多数 Web 应用程序中按需呈现,而无需缓存输出. 210 | 211 | - **线程安全**.您可以在不同的 goroutine 中运行多个解析器，而不会产生不良影响.不依赖于全局共享状态. 212 | 213 | - **最小的依赖关系**.Blackfriday 仅依赖于 Go 中的标准库包.源代码非常独立,因此很容易添加到任何项目,包括 Google App Engine 项目. 214 | 215 | - **符合标准**.使用适用于 HTML 4.01 和 XHTML 1.0 Transitional 的 W3C 验证工具成功验证输出. 216 | 217 | ## 扩展 218 | 219 | 除了标准的 markdown 语法之外,此包还实现了以下扩展: 220 | 221 | - **词内强调抑制**.在梳理代码时,`_`字符常用于单词内部(如:`hello_world`),因此将 markdown 解释为强调命令通常是错误的.Blackfriday 允许您将所有强调标记视为正常字符, 当它们出现在单词内部时. 222 | 223 | - **表格**.可以使用简单的语法在输入中绘制表来创建表: 224 | 225 | ``` 226 | Name | Age 227 | --------|------ 228 | Bob | 27 229 | Alice | 23 230 | ``` 231 | 232 | - **受控代码块**.除了标记代码块的常规 4 空格缩进之外,您还可以显式标记它们并提供语言(以使语法高亮简化).只需将其标记为: 233 | 234 | ```` 235 | ``` go 236 | func getTrue() bool { 237 | return true 238 | } 239 | ``` 240 | ```` 241 | 242 | 您可以使用 3 个或更多反引号来标记块的开头,并使用相同的数字来标记块的结尾. 243 | 244 | 要在使用 bluemonday HTML 清理程序时，保留被保护的代码块类,请使用以下策略: 245 | 246 | ```go 247 | p := bluemonday.UGCPolicy() 248 | p.AllowAttrs("class").Matching(regexp.MustCompile("^language-[a-zA-Z0-9]+$")).OnElements("code") 249 | html := p.SanitizeBytes(unsafe) 250 | ``` 251 | 252 | - **定义列表**.一个简单的定义列表由单行术语后跟冒号，和该术语的定义组成. 253 | 254 | ``` 255 | Cat 256 | : Fluffy animal everyone likes 257 | 258 | Internet 259 | : Vector of transmission for pictures of cats 260 | ``` 261 | 262 | 术语必须用`空行`与前一个定义分开. 263 | 264 | - **脚注**.文本中的标记将成为上标数字;脚注定义将放在文档末尾的脚注列表中.脚注如下所示: 265 | 266 | ``` 267 | This is a footnote.[^1] 268 | 269 | [^1]: the footnote text. 270 | ``` 271 | 272 | - **自动链上**.Blackfriday 可以找到未明确标记为链接的 URL，并将其转换为链接. 273 | 274 | - **删除线**.使用两个波浪(`~~`)标记应该划掉的文本. 275 | 276 | - **行线断裂**.启用此扩展程序(默认情况下,它已关闭`MarkdownBasic`和`MarkdownCommon`便利功能),输入中的换行符，转换为输出中的换行符. (也就是各个换行) 277 | 278 | - **聪明的报价**.支持 Smartypants 样式的标点替换,将普通的双引号和单引号转换为引号等. 279 | 280 | - **LaTeX 风格的破折号解析**是一个额外的选择,这里`--`被翻译成`–`,和`---`被翻译成`—`.这与大多数 smartypants 处理器不同,后者将单个连字符转换为`ndash`,将双连字符转换为`mdash`. 281 | 282 | - **智能分数**,任何看起来像分数的东西都被翻译成合适的 HTML(而不是像大多数智能处理器那样的一些特殊情况).例如,`4/5`变`4⁄5`,呈现为4/五. 283 | 284 | ## 其他渲染器 285 | 286 | Blackfriday 的结构允许替代渲染引擎.以下是一些关注的项目: 287 | 288 | - [github_flavored_markdown](https://godoc.org/github.com/shurcooL/github_flavored_markdown):提供 GitHub Flavored Markdown 渲染器,带有围栏代码块突出显示,可点击的标题 anchor 链接. 289 | 290 | 它不可自定义,其目标是生成 HTML 输出与[GitHub Markdown API 端点](https://developer.github.com/v3/markdown/#render-a-markdown-document-in-raw-mode)对上,除了渲染是在本地执行. 291 | 292 | - [markdownfmt](https://github.com/shurcooL/markdownfmt):像 gofmt,但用于 markdown. 293 | 294 | - [LaTeX output](https://bitbucket.org/ambrevar/blackfriday-latex):将输出呈现为 LaTeX. 295 | 296 | - [bfchroma](https://github.com/Depado/bfchroma/):提供方便的代码高亮显示库[chroma](https://github.com/alecthomas/chroma)集成.bfchroma 仅与 Blackfriday 的 v2 兼容,并提供与 Blackfriday 随时使用的嵌入式渲染器,以及进一步定制的选项和方法. 297 | 298 | ## TODO 299 | 300 | - 更多单元测试 301 | - 改进 Unicode 支持.它不了解所有 Unicode 规则(关于什么构成字母,标点符号等),因此在某些情况下它可能无法正确检测字的边界.所有 UTF-8 输入都是安全的. 302 | 303 | ## 执照 304 | 305 | [Blackfriday 根据简化 BSD 许可证分发](LICENSE.txt) 306 | 307 | [1]: https://daringfireball.net/projects/markdown/ 'Markdown' 308 | [2]: https://golang.org/ 'Go Language' 309 | [3]: https://github.com/vmg/sundown 'Sundown' 310 | [4]: https://godoc.org/gopkg.in/russross/blackfriday.v2#Parse 'Parse func' 311 | [5]: https://github.com/microcosm-cc/bluemonday 'Bluemonday' 312 | [6]: https://labix.org/gopkg.in 'gopkg.in' 313 | [7]: https://github.com/golang/dep/ 'dep' 314 | [8]: https://github.com/Masterminds/glide 'Glide' 315 | [buildsvg]: https://travis-ci.org/russross/blackfriday.svg?branch=master 316 | [buildurl]: https://travis-ci.org/russross/blackfriday 317 | [godocv2svg]: https://godoc.org/gopkg.in/russross/blackfriday.v2?status.svg 318 | [godocv2url]: https://godoc.org/gopkg.in/russross/blackfriday.v2 319 | -------------------------------------------------------------------------------- /en.md: -------------------------------------------------------------------------------- 1 | Blackfriday 2 | [![Build Status][BuildSVG]][BuildURL] 3 | [![Godoc][GodocV2SVG]][GodocV2URL] 4 | =========== 5 | 6 | Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It 7 | is paranoid about its input (so you can safely feed it user-supplied 8 | data), it is fast, it supports common extensions (tables, smart 9 | punctuation substitutions, etc.). and it is safe for all utf-8 10 | (unicode) input. 11 | 12 | HTML output is currently supported, along with Smartypants 13 | extensions. 14 | 15 | It started as a translation from C of [Sundown][3]. 16 | 17 | 18 | Installation 19 | ------------ 20 | 21 | Blackfriday is compatible with any modern Go release. With Go and git installed: 22 | 23 | go get -u gopkg.in/russross/blackfriday.v2 24 | 25 | will download, compile, and install the package into your `$GOPATH` directory 26 | hierarchy. 27 | 28 | 29 | Versions 30 | -------- 31 | 32 | Currently maintained and recommended version of Blackfriday is `v2`. It's being 33 | developed on its own branch: https://github.com/russross/blackfriday/tree/v2 and the 34 | documentation is available at 35 | https://godoc.org/gopkg.in/russross/blackfriday.v2. 36 | 37 | It is `go get`-able via [gopkg.in][6] at `gopkg.in/russross/blackfriday.v2`, 38 | but we highly recommend using package management tool like [dep][7] or 39 | [Glide][8] and make use of semantic versioning. With package management you 40 | should import `github.com/russross/blackfriday` and specify that you're using 41 | version 2.0.0. 42 | 43 | Version 2 offers a number of improvements over v1: 44 | 45 | * Cleaned up API 46 | * A separate call to [`Parse`][4], which produces an abstract syntax tree for 47 | the document 48 | * Latest bug fixes 49 | * Flexibility to easily add your own rendering extensions 50 | 51 | Potential drawbacks: 52 | 53 | * Our benchmarks show v2 to be slightly slower than v1. Currently in the 54 | ballpark of around 15%. 55 | * API breakage. If you can't afford modifying your code to adhere to the new API 56 | and don't care too much about the new features, v2 is probably not for you. 57 | * Several bug fixes are trailing behind and still need to be forward-ported to 58 | v2. See issue [#348](https://github.com/russross/blackfriday/issues/348) for 59 | tracking. 60 | 61 | If you are still interested in the legacy `v1`, you can import it from 62 | `github.com/russross/blackfriday`. Documentation for the legacy v1 can be found 63 | here: https://godoc.org/github.com/russross/blackfriday 64 | 65 | ### Known issue with `dep` 66 | 67 | There is a known problem with using Blackfriday v1 _transitively_ and `dep`. 68 | Currently `dep` prioritizes semver versions over anything else, and picks the 69 | latest one, plus it does not apply a `[[constraint]]` specifier to transitively 70 | pulled in packages. So if you're using something that uses Blackfriday v1, but 71 | that something does not use `dep` yet, you will get Blackfriday v2 pulled in and 72 | your first dependency will fail to build. 73 | 74 | There are couple of fixes for it, documented here: 75 | https://github.com/golang/dep/blob/master/docs/FAQ.md#how-do-i-constrain-a-transitive-dependencys-version 76 | 77 | Meanwhile, `dep` team is working on a more general solution to the constraints 78 | on transitive dependencies problem: https://github.com/golang/dep/issues/1124. 79 | 80 | 81 | Usage 82 | ----- 83 | 84 | ### v1 85 | 86 | For basic usage, it is as simple as getting your input into a byte 87 | slice and calling: 88 | 89 | output := blackfriday.MarkdownBasic(input) 90 | 91 | This renders it with no extensions enabled. To get a more useful 92 | feature set, use this instead: 93 | 94 | output := blackfriday.MarkdownCommon(input) 95 | 96 | ### v2 97 | 98 | For the most sensible markdown processing, it is as simple as getting your input 99 | into a byte slice and calling: 100 | 101 | ```go 102 | output := blackfriday.Run(input) 103 | ``` 104 | 105 | Your input will be parsed and the output rendered with a set of most popular 106 | extensions enabled. If you want the most basic feature set, corresponding with 107 | the bare Markdown specification, use: 108 | 109 | ```go 110 | output := blackfriday.Run(input, blackfriday.WithNoExtensions()) 111 | ``` 112 | 113 | ### Sanitize untrusted content 114 | 115 | Blackfriday itself does nothing to protect against malicious content. If you are 116 | dealing with user-supplied markdown, we recommend running Blackfriday's output 117 | through HTML sanitizer such as [Bluemonday][5]. 118 | 119 | Here's an example of simple usage of Blackfriday together with Bluemonday: 120 | 121 | ```go 122 | import ( 123 | "github.com/microcosm-cc/bluemonday" 124 | "gopkg.in/russross/blackfriday.v2" 125 | ) 126 | 127 | // ... 128 | unsafe := blackfriday.Run(input) 129 | html := bluemonday.UGCPolicy().SanitizeBytes(unsafe) 130 | ``` 131 | 132 | ### Custom options, v1 133 | 134 | If you want to customize the set of options, first get a renderer 135 | (currently only the HTML output engine), then use it to 136 | call the more general `Markdown` function. For examples, see the 137 | implementations of `MarkdownBasic` and `MarkdownCommon` in 138 | `markdown.go`. 139 | 140 | ### Custom options, v2 141 | 142 | If you want to customize the set of options, use `blackfriday.WithExtensions`, 143 | `blackfriday.WithRenderer` and `blackfriday.WithRefOverride`. 144 | 145 | ### `blackfriday-tool` 146 | 147 | You can also check out `blackfriday-tool` for a more complete example 148 | of how to use it. Download and install it using: 149 | 150 | go get github.com/russross/blackfriday-tool 151 | 152 | This is a simple command-line tool that allows you to process a 153 | markdown file using a standalone program. You can also browse the 154 | source directly on github if you are just looking for some example 155 | code: 156 | 157 | * 158 | 159 | Note that if you have not already done so, installing 160 | `blackfriday-tool` will be sufficient to download and install 161 | blackfriday in addition to the tool itself. The tool binary will be 162 | installed in `$GOPATH/bin`. This is a statically-linked binary that 163 | can be copied to wherever you need it without worrying about 164 | dependencies and library versions. 165 | 166 | ### Sanitized anchor names 167 | 168 | Blackfriday includes an algorithm for creating sanitized anchor names 169 | corresponding to a given input text. This algorithm is used to create 170 | anchors for headings when `EXTENSION_AUTO_HEADER_IDS` is enabled. The 171 | algorithm has a specification, so that other packages can create 172 | compatible anchor names and links to those anchors. 173 | 174 | The specification is located at https://godoc.org/github.com/russross/blackfriday#hdr-Sanitized_Anchor_Names. 175 | 176 | [`SanitizedAnchorName`](https://godoc.org/github.com/russross/blackfriday#SanitizedAnchorName) exposes this functionality, and can be used to 177 | create compatible links to the anchor names generated by blackfriday. 178 | This algorithm is also implemented in a small standalone package at 179 | [`github.com/shurcooL/sanitized_anchor_name`](https://godoc.org/github.com/shurcooL/sanitized_anchor_name). It can be useful for clients 180 | that want a small package and don't need full functionality of blackfriday. 181 | 182 | 183 | Features 184 | -------- 185 | 186 | All features of Sundown are supported, including: 187 | 188 | * **Compatibility**. The Markdown v1.0.3 test suite passes with 189 | the `--tidy` option. Without `--tidy`, the differences are 190 | mostly in whitespace and entity escaping, where blackfriday is 191 | more consistent and cleaner. 192 | 193 | * **Common extensions**, including table support, fenced code 194 | blocks, autolinks, strikethroughs, non-strict emphasis, etc. 195 | 196 | * **Safety**. Blackfriday is paranoid when parsing, making it safe 197 | to feed untrusted user input without fear of bad things 198 | happening. The test suite stress tests this and there are no 199 | known inputs that make it crash. If you find one, please let me 200 | know and send me the input that does it. 201 | 202 | NOTE: "safety" in this context means *runtime safety only*. In order to 203 | protect yourself against JavaScript injection in untrusted content, see 204 | [this example](https://github.com/russross/blackfriday#sanitize-untrusted-content). 205 | 206 | * **Fast processing**. It is fast enough to render on-demand in 207 | most web applications without having to cache the output. 208 | 209 | * **Thread safety**. You can run multiple parsers in different 210 | goroutines without ill effect. There is no dependence on global 211 | shared state. 212 | 213 | * **Minimal dependencies**. Blackfriday only depends on standard 214 | library packages in Go. The source code is pretty 215 | self-contained, so it is easy to add to any project, including 216 | Google App Engine projects. 217 | 218 | * **Standards compliant**. Output successfully validates using the 219 | W3C validation tool for HTML 4.01 and XHTML 1.0 Transitional. 220 | 221 | 222 | Extensions 223 | ---------- 224 | 225 | In addition to the standard markdown syntax, this package 226 | implements the following extensions: 227 | 228 | * **Intra-word emphasis supression**. The `_` character is 229 | commonly used inside words when discussing code, so having 230 | markdown interpret it as an emphasis command is usually the 231 | wrong thing. Blackfriday lets you treat all emphasis markers as 232 | normal characters when they occur inside a word. 233 | 234 | * **Tables**. Tables can be created by drawing them in the input 235 | using a simple syntax: 236 | 237 | ``` 238 | Name | Age 239 | --------|------ 240 | Bob | 27 241 | Alice | 23 242 | ``` 243 | 244 | * **Fenced code blocks**. In addition to the normal 4-space 245 | indentation to mark code blocks, you can explicitly mark them 246 | and supply a language (to make syntax highlighting simple). Just 247 | mark it like this: 248 | 249 | ``` go 250 | func getTrue() bool { 251 | return true 252 | } 253 | ``` 254 | 255 | You can use 3 or more backticks to mark the beginning of the 256 | block, and the same number to mark the end of the block. 257 | 258 | To preserve classes of fenced code blocks while using the bluemonday 259 | HTML sanitizer, use the following policy: 260 | 261 | ``` go 262 | p := bluemonday.UGCPolicy() 263 | p.AllowAttrs("class").Matching(regexp.MustCompile("^language-[a-zA-Z0-9]+$")).OnElements("code") 264 | html := p.SanitizeBytes(unsafe) 265 | ``` 266 | 267 | * **Definition lists**. A simple definition list is made of a single-line 268 | term followed by a colon and the definition for that term. 269 | 270 | Cat 271 | : Fluffy animal everyone likes 272 | 273 | Internet 274 | : Vector of transmission for pictures of cats 275 | 276 | Terms must be separated from the previous definition by a blank line. 277 | 278 | * **Footnotes**. A marker in the text that will become a superscript number; 279 | a footnote definition that will be placed in a list of footnotes at the 280 | end of the document. A footnote looks like this: 281 | 282 | This is a footnote.[^1] 283 | 284 | [^1]: the footnote text. 285 | 286 | * **Autolinking**. Blackfriday can find URLs that have not been 287 | explicitly marked as links and turn them into links. 288 | 289 | * **Strikethrough**. Use two tildes (`~~`) to mark text that 290 | should be crossed out. 291 | 292 | * **Hard line breaks**. With this extension enabled (it is off by 293 | default in the `MarkdownBasic` and `MarkdownCommon` convenience 294 | functions), newlines in the input translate into line breaks in 295 | the output. 296 | 297 | * **Smart quotes**. Smartypants-style punctuation substitution is 298 | supported, turning normal double- and single-quote marks into 299 | curly quotes, etc. 300 | 301 | * **LaTeX-style dash parsing** is an additional option, where `--` 302 | is translated into `–`, and `---` is translated into 303 | `—`. This differs from most smartypants processors, which 304 | turn a single hyphen into an ndash and a double hyphen into an 305 | mdash. 306 | 307 | * **Smart fractions**, where anything that looks like a fraction 308 | is translated into suitable HTML (instead of just a few special 309 | cases like most smartypant processors). For example, `4/5` 310 | becomes `4⁄5`, which renders as 311 | 4⁄5. 312 | 313 | 314 | Other renderers 315 | --------------- 316 | 317 | Blackfriday is structured to allow alternative rendering engines. Here 318 | are a few of note: 319 | 320 | * [github_flavored_markdown](https://godoc.org/github.com/shurcooL/github_flavored_markdown): 321 | provides a GitHub Flavored Markdown renderer with fenced code block 322 | highlighting, clickable heading anchor links. 323 | 324 | It's not customizable, and its goal is to produce HTML output 325 | equivalent to the [GitHub Markdown API endpoint](https://developer.github.com/v3/markdown/#render-a-markdown-document-in-raw-mode), 326 | except the rendering is performed locally. 327 | 328 | * [markdownfmt](https://github.com/shurcooL/markdownfmt): like gofmt, 329 | but for markdown. 330 | 331 | * [LaTeX output](https://bitbucket.org/ambrevar/blackfriday-latex): 332 | renders output as LaTeX. 333 | 334 | * [bfchroma](https://github.com/Depado/bfchroma/): provides convenience 335 | integration with the [Chroma](https://github.com/alecthomas/chroma) code 336 | highlighting library. bfchroma is only compatible with v2 of Blackfriday and 337 | provides a drop-in renderer ready to use with Blackfriday, as well as 338 | options and means for further customization. 339 | 340 | 341 | TODO 342 | ---- 343 | 344 | * More unit testing 345 | * Improve Unicode support. It does not understand all Unicode 346 | rules (about what constitutes a letter, a punctuation symbol, 347 | etc.), so it may fail to detect word boundaries correctly in 348 | some instances. It is safe on all UTF-8 input. 349 | 350 | 351 | License 352 | ------- 353 | 354 | [Blackfriday is distributed under the Simplified BSD License](LICENSE.txt) 355 | 356 | 357 | [1]: https://daringfireball.net/projects/markdown/ "Markdown" 358 | [2]: https://golang.org/ "Go Language" 359 | [3]: https://github.com/vmg/sundown "Sundown" 360 | [4]: https://godoc.org/gopkg.in/russross/blackfriday.v2#Parse "Parse func" 361 | [5]: https://github.com/microcosm-cc/bluemonday "Bluemonday" 362 | [6]: https://labix.org/gopkg.in "gopkg.in" 363 | [7]: https://github.com/golang/dep/ "dep" 364 | [8]: https://github.com/Masterminds/glide "Glide" 365 | 366 | [BuildSVG]: https://travis-ci.org/russross/blackfriday.svg?branch=master 367 | [BuildURL]: https://travis-ci.org/russross/blackfriday 368 | [GodocV2SVG]: https://godoc.org/gopkg.in/russross/blackfriday.v2?status.svg 369 | [GodocV2URL]: https://godoc.org/gopkg.in/russross/blackfriday.v2 370 | --------------------------------------------------------------------------------