1Blackfriday 2[![Build Status][BuildSVG]][BuildURL] 3[![Godoc][GodocV2SVG]][GodocV2URL] 4=========== 5 6Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It 7is paranoid about its input (so you can safely feed it user-supplied 8data), it is fast, it supports common extensions (tables, smart 9punctuation substitutions, etc.), and it is safe for all utf-8 10(unicode) input. 11 12HTML output is currently supported, along with Smartypants 13extensions. 14 15It started as a translation from C of [Sundown][3]. 16 17 18Installation 19------------ 20 21Blackfriday is compatible with any modern Go release. With Go and git installed: 22 23 go get -u gopkg.in/russross/blackfriday.v2 24 25will download, compile, and install the package into your `$GOPATH` directory 26hierarchy. 27 28 29Versions 30-------- 31 32Currently maintained and recommended version of Blackfriday is `v2`. It's being 33developed on its own branch: https://github.com/russross/blackfriday/tree/v2 and the 34documentation is available at 35https://godoc.org/gopkg.in/russross/blackfriday.v2. 36 37It is `go get`-able via [gopkg.in][6] at `gopkg.in/russross/blackfriday.v2`, 38but we highly recommend using package management tool like [dep][7] or 39[Glide][8] and make use of semantic versioning. With package management you 40should import `github.com/russross/blackfriday` and specify that you're using 41version 2.0.0. 42 43Version 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 51Potential 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 61If 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 63here: https://godoc.org/github.com/russross/blackfriday 64 65### Known issue with `dep` 66 67There is a known problem with using Blackfriday v1 _transitively_ and `dep`. 68Currently `dep` prioritizes semver versions over anything else, and picks the 69latest one, plus it does not apply a `[[constraint]]` specifier to transitively 70pulled in packages. So if you're using something that uses Blackfriday v1, but 71that something does not use `dep` yet, you will get Blackfriday v2 pulled in and 72your first dependency will fail to build. 73 74There are couple of fixes for it, documented here: 75https://github.com/golang/dep/blob/master/docs/FAQ.md#how-do-i-constrain-a-transitive-dependencys-version 76 77Meanwhile, `dep` team is working on a more general solution to the constraints 78on transitive dependencies problem: https://github.com/golang/dep/issues/1124. 79 80 81Usage 82----- 83 84### v1 85 86For basic usage, it is as simple as getting your input into a byte 87slice and calling: 88 89```go 90output := blackfriday.MarkdownBasic(input) 91``` 92 93This renders it with no extensions enabled. To get a more useful 94feature set, use this instead: 95 96```go 97output := blackfriday.MarkdownCommon(input) 98``` 99 100### v2 101 102For the most sensible markdown processing, it is as simple as getting your input 103into a byte slice and calling: 104 105```go 106output := blackfriday.Run(input) 107``` 108 109Your input will be parsed and the output rendered with a set of most popular 110extensions enabled. If you want the most basic feature set, corresponding with 111the bare Markdown specification, use: 112 113```go 114output := blackfriday.Run(input, blackfriday.WithNoExtensions()) 115``` 116 117### Sanitize untrusted content 118 119Blackfriday itself does nothing to protect against malicious content. If you are 120dealing with user-supplied markdown, we recommend running Blackfriday's output 121through HTML sanitizer such as [Bluemonday][5]. 122 123Here's an example of simple usage of Blackfriday together with Bluemonday: 124 125```go 126import ( 127 "github.com/microcosm-cc/bluemonday" 128 "gopkg.in/russross/blackfriday.v2" 129) 130 131// ... 132unsafe := blackfriday.Run(input) 133html := bluemonday.UGCPolicy().SanitizeBytes(unsafe) 134``` 135 136### Custom options, v1 137 138If you want to customize the set of options, first get a renderer 139(currently only the HTML output engine), then use it to 140call the more general `Markdown` function. For examples, see the 141implementations of `MarkdownBasic` and `MarkdownCommon` in 142`markdown.go`. 143 144### Custom options, v2 145 146If you want to customize the set of options, use `blackfriday.WithExtensions`, 147`blackfriday.WithRenderer` and `blackfriday.WithRefOverride`. 148 149### `blackfriday-tool` 150 151You can also check out `blackfriday-tool` for a more complete example 152of how to use it. Download and install it using: 153 154 go get github.com/russross/blackfriday-tool 155 156This is a simple command-line tool that allows you to process a 157markdown file using a standalone program. You can also browse the 158source directly on github if you are just looking for some example 159code: 160 161* <http://github.com/russross/blackfriday-tool> 162 163Note that if you have not already done so, installing 164`blackfriday-tool` will be sufficient to download and install 165blackfriday in addition to the tool itself. The tool binary will be 166installed in `$GOPATH/bin`. This is a statically-linked binary that 167can be copied to wherever you need it without worrying about 168dependencies and library versions. 169 170### Sanitized anchor names 171 172Blackfriday includes an algorithm for creating sanitized anchor names 173corresponding to a given input text. This algorithm is used to create 174anchors for headings when `EXTENSION_AUTO_HEADER_IDS` is enabled. The 175algorithm has a specification, so that other packages can create 176compatible anchor names and links to those anchors. 177 178The specification is located at https://godoc.org/github.com/russross/blackfriday#hdr-Sanitized_Anchor_Names. 179 180[`SanitizedAnchorName`](https://godoc.org/github.com/russross/blackfriday#SanitizedAnchorName) exposes this functionality, and can be used to 181create compatible links to the anchor names generated by blackfriday. 182This algorithm is also implemented in a small standalone package at 183[`github.com/shurcooL/sanitized_anchor_name`](https://godoc.org/github.com/shurcooL/sanitized_anchor_name). It can be useful for clients 184that want a small package and don't need full functionality of blackfriday. 185 186 187Features 188-------- 189 190All features of Sundown are supported, including: 191 192* **Compatibility**. The Markdown v1.0.3 test suite passes with 193 the `--tidy` option. Without `--tidy`, the differences are 194 mostly in whitespace and entity escaping, where blackfriday is 195 more consistent and cleaner. 196 197* **Common extensions**, including table support, fenced code 198 blocks, autolinks, strikethroughs, non-strict emphasis, etc. 199 200* **Safety**. Blackfriday is paranoid when parsing, making it safe 201 to feed untrusted user input without fear of bad things 202 happening. The test suite stress tests this and there are no 203 known inputs that make it crash. If you find one, please let me 204 know and send me the input that does it. 205 206 NOTE: "safety" in this context means *runtime safety only*. In order to 207 protect yourself against JavaScript injection in untrusted content, see 208 [this example](https://github.com/russross/blackfriday#sanitize-untrusted-content). 209 210* **Fast processing**. It is fast enough to render on-demand in 211 most web applications without having to cache the output. 212 213* **Thread safety**. You can run multiple parsers in different 214 goroutines without ill effect. There is no dependence on global 215 shared state. 216 217* **Minimal dependencies**. Blackfriday only depends on standard 218 library packages in Go. The source code is pretty 219 self-contained, so it is easy to add to any project, including 220 Google App Engine projects. 221 222* **Standards compliant**. Output successfully validates using the 223 W3C validation tool for HTML 4.01 and XHTML 1.0 Transitional. 224 225 226Extensions 227---------- 228 229In addition to the standard markdown syntax, this package 230implements the following extensions: 231 232* **Intra-word emphasis supression**. The `_` character is 233 commonly used inside words when discussing code, so having 234 markdown interpret it as an emphasis command is usually the 235 wrong thing. Blackfriday lets you treat all emphasis markers as 236 normal characters when they occur inside a word. 237 238* **Tables**. Tables can be created by drawing them in the input 239 using a simple syntax: 240 241 ``` 242 Name | Age 243 --------|------ 244 Bob | 27 245 Alice | 23 246 ``` 247 248* **Fenced code blocks**. In addition to the normal 4-space 249 indentation to mark code blocks, you can explicitly mark them 250 and supply a language (to make syntax highlighting simple). Just 251 mark it like this: 252 253 ``` go 254 func getTrue() bool { 255 return true 256 } 257 ``` 258 259 You can use 3 or more backticks to mark the beginning of the 260 block, and the same number to mark the end of the block. 261 262 To preserve classes of fenced code blocks while using the bluemonday 263 HTML sanitizer, use the following policy: 264 265 ``` go 266 p := bluemonday.UGCPolicy() 267 p.AllowAttrs("class").Matching(regexp.MustCompile("^language-[a-zA-Z0-9]+$")).OnElements("code") 268 html := p.SanitizeBytes(unsafe) 269 ``` 270 271* **Definition lists**. A simple definition list is made of a single-line 272 term followed by a colon and the definition for that term. 273 274 Cat 275 : Fluffy animal everyone likes 276 277 Internet 278 : Vector of transmission for pictures of cats 279 280 Terms must be separated from the previous definition by a blank line. 281 282* **Footnotes**. A marker in the text that will become a superscript number; 283 a footnote definition that will be placed in a list of footnotes at the 284 end of the document. A footnote looks like this: 285 286 This is a footnote.[^1] 287 288 [^1]: the footnote text. 289 290* **Autolinking**. Blackfriday can find URLs that have not been 291 explicitly marked as links and turn them into links. 292 293* **Strikethrough**. Use two tildes (`~~`) to mark text that 294 should be crossed out. 295 296* **Hard line breaks**. With this extension enabled (it is off by 297 default in the `MarkdownBasic` and `MarkdownCommon` convenience 298 functions), newlines in the input translate into line breaks in 299 the output. 300 301* **Smart quotes**. Smartypants-style punctuation substitution is 302 supported, turning normal double- and single-quote marks into 303 curly quotes, etc. 304 305* **LaTeX-style dash parsing** is an additional option, where `--` 306 is translated into `–`, and `---` is translated into 307 `—`. This differs from most smartypants processors, which 308 turn a single hyphen into an ndash and a double hyphen into an 309 mdash. 310 311* **Smart fractions**, where anything that looks like a fraction 312 is translated into suitable HTML (instead of just a few special 313 cases like most smartypant processors). For example, `4/5` 314 becomes `<sup>4</sup>⁄<sub>5</sub>`, which renders as 315 <sup>4</sup>⁄<sub>5</sub>. 316 317 318Other renderers 319--------------- 320 321Blackfriday is structured to allow alternative rendering engines. Here 322are a few of note: 323 324* [github_flavored_markdown](https://godoc.org/github.com/shurcooL/github_flavored_markdown): 325 provides a GitHub Flavored Markdown renderer with fenced code block 326 highlighting, clickable heading anchor links. 327 328 It's not customizable, and its goal is to produce HTML output 329 equivalent to the [GitHub Markdown API endpoint](https://developer.github.com/v3/markdown/#render-a-markdown-document-in-raw-mode), 330 except the rendering is performed locally. 331 332* [markdownfmt](https://github.com/shurcooL/markdownfmt): like gofmt, 333 but for markdown. 334 335* [LaTeX output](https://bitbucket.org/ambrevar/blackfriday-latex): 336 renders output as LaTeX. 337 338* [bfchroma](https://github.com/Depado/bfchroma/): provides convenience 339 integration with the [Chroma](https://github.com/alecthomas/chroma) code 340 highlighting library. bfchroma is only compatible with v2 of Blackfriday and 341 provides a drop-in renderer ready to use with Blackfriday, as well as 342 options and means for further customization. 343 344 345TODO 346---- 347 348* More unit testing 349* Improve Unicode support. It does not understand all Unicode 350 rules (about what constitutes a letter, a punctuation symbol, 351 etc.), so it may fail to detect word boundaries correctly in 352 some instances. It is safe on all UTF-8 input. 353 354 355License 356------- 357 358[Blackfriday is distributed under the Simplified BSD License](LICENSE.txt) 359 360 361 [1]: https://daringfireball.net/projects/markdown/ "Markdown" 362 [2]: https://golang.org/ "Go Language" 363 [3]: https://github.com/vmg/sundown "Sundown" 364 [4]: https://godoc.org/gopkg.in/russross/blackfriday.v2#Parse "Parse func" 365 [5]: https://github.com/microcosm-cc/bluemonday "Bluemonday" 366 [6]: https://labix.org/gopkg.in "gopkg.in" 367 [7]: https://github.com/golang/dep/ "dep" 368 [8]: https://github.com/Masterminds/glide "Glide" 369 370 [BuildSVG]: https://travis-ci.org/russross/blackfriday.svg?branch=master 371 [BuildURL]: https://travis-ci.org/russross/blackfriday 372 [GodocV2SVG]: https://godoc.org/gopkg.in/russross/blackfriday.v2?status.svg 373 [GodocV2URL]: https://godoc.org/gopkg.in/russross/blackfriday.v2 374