README.md
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