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 output := blackfriday.MarkdownBasic(input) 90 91This renders it with no extensions enabled. To get a more useful 92feature set, use this instead: 93 94 output := blackfriday.MarkdownCommon(input) 95 96### v2 97 98For the most sensible markdown processing, it is as simple as getting your input 99into a byte slice and calling: 100 101```go 102output := blackfriday.Run(input) 103``` 104 105Your input will be parsed and the output rendered with a set of most popular 106extensions enabled. If you want the most basic feature set, corresponding with 107the bare Markdown specification, use: 108 109```go 110output := blackfriday.Run(input, blackfriday.WithNoExtensions()) 111``` 112 113### Sanitize untrusted content 114 115Blackfriday itself does nothing to protect against malicious content. If you are 116dealing with user-supplied markdown, we recommend running Blackfriday's output 117through HTML sanitizer such as [Bluemonday][5]. 118 119Here's an example of simple usage of Blackfriday together with Bluemonday: 120 121```go 122import ( 123 "github.com/microcosm-cc/bluemonday" 124 "gopkg.in/russross/blackfriday.v2" 125) 126 127// ... 128unsafe := blackfriday.Run(input) 129html := bluemonday.UGCPolicy().SanitizeBytes(unsafe) 130``` 131 132### Custom options, v1 133 134If you want to customize the set of options, first get a renderer 135(currently only the HTML output engine), then use it to 136call the more general `Markdown` function. For examples, see the 137implementations of `MarkdownBasic` and `MarkdownCommon` in 138`markdown.go`. 139 140### Custom options, v2 141 142If you want to customize the set of options, use `blackfriday.WithExtensions`, 143`blackfriday.WithRenderer` and `blackfriday.WithRefOverride`. 144 145### `blackfriday-tool` 146 147You can also check out `blackfriday-tool` for a more complete example 148of how to use it. Download and install it using: 149 150 go get github.com/russross/blackfriday-tool 151 152This is a simple command-line tool that allows you to process a 153markdown file using a standalone program. You can also browse the 154source directly on github if you are just looking for some example 155code: 156 157* <http://github.com/russross/blackfriday-tool> 158 159Note that if you have not already done so, installing 160`blackfriday-tool` will be sufficient to download and install 161blackfriday in addition to the tool itself. The tool binary will be 162installed in `$GOPATH/bin`. This is a statically-linked binary that 163can be copied to wherever you need it without worrying about 164dependencies and library versions. 165 166### Sanitized anchor names 167 168Blackfriday includes an algorithm for creating sanitized anchor names 169corresponding to a given input text. This algorithm is used to create 170anchors for headings when `EXTENSION_AUTO_HEADER_IDS` is enabled. The 171algorithm has a specification, so that other packages can create 172compatible anchor names and links to those anchors. 173 174The 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 177create compatible links to the anchor names generated by blackfriday. 178This 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 180that want a small package and don't need full functionality of blackfriday. 181 182 183Features 184-------- 185 186All 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 222Extensions 223---------- 224 225In addition to the standard markdown syntax, this package 226implements 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 `<sup>4</sup>⁄<sub>5</sub>`, which renders as 311 <sup>4</sup>⁄<sub>5</sub>. 312 313 314Other renderers 315--------------- 316 317Blackfriday is structured to allow alternative rendering engines. Here 318are 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 341TODO 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 351License 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