README.md (view raw)
1Blackfriday [](https://travis-ci.org/russross/blackfriday)
2===========
3
4Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It
5is paranoid about its input (so you can safely feed it user-supplied
6data), it is fast, it supports common extensions (tables, smart
7punctuation substitutions, etc.), and it is safe for all utf-8
8(unicode) input.
9
10HTML output is currently supported, along with Smartypants
11extensions.
12
13It started as a translation from C of [Sundown][3].
14
15
16Installation
17------------
18
19Blackfriday is compatible with any modern Go release. With Go 1.7 and git
20installed:
21
22 go get gopkg.in/russross/blackfriday.v2
23
24will download, compile, and install the package into your `$GOPATH`
25directory hierarchy. Alternatively, you can achieve the same if you
26import it into a project:
27
28 import "gopkg.in/russross/blackfriday.v2"
29
30and `go get` without parameters.
31
32
33Versions
34--------
35
36Currently maintained and recommended version of Blackfriday is `v2`. It's being
37developed on its own branch: https://github.com/russross/blackfriday/v2. You
38should install and import it via [gopkg.in][6] at
39`gopkg.in/russross/blackfriday.v2`.
40
41Version 2 offers a number of improvements over v1:
42
43* Cleaned up API
44* A separate call to [`Parse`][4], which produces an abstract syntax tree for
45 the document
46* Latest bug fixes
47* Flexibility to easily add your own rendering extensions
48
49Potential drawbacks:
50
51* Our benchmarks show v2 to be slightly slower than v1. Currently in the
52 ballpark of around 15%.
53* API breakage. If you can't afford modifying your code to adhere to the new API
54 and don't care too much about the new features, v2 is probably not for you.
55* Several bug fixes are trailing behind and still need to be forward-ported to
56 v2. See issue [#348](https://github.com/russross/blackfriday/issues/348) for
57 tracking.
58
59Usage
60-----
61
62For the most sensible markdown processing, it is as simple as getting your input
63into a byte slice and calling:
64
65```go
66output := blackfriday.Run(input)
67```
68
69Your input will be parsed and the output rendered with a set of most popular
70extensions enabled. If you want the most basic feature set, corresponding with
71the bare Markdown specification, use:
72
73```go
74output := blackfriday.Run(input, blackfriday.WithNoExtensions())
75```
76
77### Sanitize untrusted content
78
79Blackfriday itself does nothing to protect against malicious content. If you are
80dealing with user-supplied markdown, we recommend running Blackfriday's output
81through HTML sanitizer such as [Bluemonday][5].
82
83Here's an example of simple usage of Blackfriday together with Bluemonday:
84
85```go
86import (
87 "github.com/microcosm-cc/bluemonday"
88 "github.com/russross/blackfriday"
89)
90
91// ...
92unsafe := blackfriday.Run(input)
93html := bluemonday.UGCPolicy().SanitizeBytes(unsafe)
94```
95
96### Custom options
97
98If you want to customize the set of options, use `blackfriday.WithExtensions`,
99`blackfriday.WithRenderer` and `blackfriday.WithRefOverride`.
100
101You can also check out `blackfriday-tool` for a more complete example
102of how to use it. Download and install it using:
103
104 go get github.com/russross/blackfriday-tool
105
106This is a simple command-line tool that allows you to process a
107markdown file using a standalone program. You can also browse the
108source directly on github if you are just looking for some example
109code:
110
111* <http://github.com/russross/blackfriday-tool>
112
113Note that if you have not already done so, installing
114`blackfriday-tool` will be sufficient to download and install
115blackfriday in addition to the tool itself. The tool binary will be
116installed in `$GOPATH/bin`. This is a statically-linked binary that
117can be copied to wherever you need it without worrying about
118dependencies and library versions.
119
120
121Features
122--------
123
124All features of Sundown are supported, including:
125
126* **Compatibility**. The Markdown v1.0.3 test suite passes with
127 the `--tidy` option. Without `--tidy`, the differences are
128 mostly in whitespace and entity escaping, where blackfriday is
129 more consistent and cleaner.
130
131* **Common extensions**, including table support, fenced code
132 blocks, autolinks, strikethroughs, non-strict emphasis, etc.
133
134* **Safety**. Blackfriday is paranoid when parsing, making it safe
135 to feed untrusted user input without fear of bad things
136 happening. The test suite stress tests this and there are no
137 known inputs that make it crash. If you find one, please let me
138 know and send me the input that does it.
139
140 NOTE: "safety" in this context means *runtime safety only*. In order to
141 protect yourself against JavaScript injection in untrusted content, see
142 [this example](https://github.com/russross/blackfriday#sanitize-untrusted-content).
143
144* **Fast processing**. It is fast enough to render on-demand in
145 most web applications without having to cache the output.
146
147* **Thread safety**. You can run multiple parsers in different
148 goroutines without ill effect. There is no dependence on global
149 shared state.
150
151* **Minimal dependencies**. Blackfriday only depends on standard
152 library packages in Go. The source code is pretty
153 self-contained, so it is easy to add to any project, including
154 Google App Engine projects.
155
156* **Standards compliant**. Output successfully validates using the
157 W3C validation tool for HTML 4.01 and XHTML 1.0 Transitional.
158
159
160Extensions
161----------
162
163In addition to the standard markdown syntax, this package
164implements the following extensions:
165
166* **Intra-word emphasis supression**. The `_` character is
167 commonly used inside words when discussing code, so having
168 markdown interpret it as an emphasis command is usually the
169 wrong thing. Blackfriday lets you treat all emphasis markers as
170 normal characters when they occur inside a word.
171
172* **Tables**. Tables can be created by drawing them in the input
173 using a simple syntax:
174
175 ```
176 Name | Age
177 --------|------
178 Bob | 27
179 Alice | 23
180 ```
181
182* **Fenced code blocks**. In addition to the normal 4-space
183 indentation to mark code blocks, you can explicitly mark them
184 and supply a language (to make syntax highlighting simple). Just
185 mark it like this:
186
187 ```go
188 func getTrue() bool {
189 return true
190 }
191 ```
192
193 You can use 3 or more backticks to mark the beginning of the
194 block, and the same number to mark the end of the block.
195
196* **Definition lists**. A simple definition list is made of a single-line
197 term followed by a colon and the definition for that term.
198
199 Cat
200 : Fluffy animal everyone likes
201
202 Internet
203 : Vector of transmission for pictures of cats
204
205 Terms must be separated from the previous definition by a blank line.
206
207* **Footnotes**. A marker in the text that will become a superscript number;
208 a footnote definition that will be placed in a list of footnotes at the
209 end of the document. A footnote looks like this:
210
211 This is a footnote.[^1]
212
213 [^1]: the footnote text.
214
215* **Autolinking**. Blackfriday can find URLs that have not been
216 explicitly marked as links and turn them into links.
217
218* **Strikethrough**. Use two tildes (`~~`) to mark text that
219 should be crossed out.
220
221* **Hard line breaks**. With this extension enabled newlines in the input
222 translate into line breaks in the output. This extension is off by default.
223
224* **Smart quotes**. Smartypants-style punctuation substitution is
225 supported, turning normal double- and single-quote marks into
226 curly quotes, etc.
227
228* **LaTeX-style dash parsing** is an additional option, where `--`
229 is translated into `–`, and `---` is translated into
230 `—`. This differs from most smartypants processors, which
231 turn a single hyphen into an ndash and a double hyphen into an
232 mdash.
233
234* **Smart fractions**, where anything that looks like a fraction
235 is translated into suitable HTML (instead of just a few special
236 cases like most smartypant processors). For example, `4/5`
237 becomes `<sup>4</sup>⁄<sub>5</sub>`, which renders as
238 <sup>4</sup>⁄<sub>5</sub>.
239
240
241Other renderers
242---------------
243
244Blackfriday is structured to allow alternative rendering engines. Here
245are a few of note:
246
247* [github_flavored_markdown](https://godoc.org/github.com/shurcooL/github_flavored_markdown):
248 provides a GitHub Flavored Markdown renderer with fenced code block
249 highlighting, clickable heading anchor links.
250
251 It's not customizable, and its goal is to produce HTML output
252 equivalent to the [GitHub Markdown API endpoint](https://developer.github.com/v3/markdown/#render-a-markdown-document-in-raw-mode),
253 except the rendering is performed locally.
254
255* [markdownfmt](https://github.com/shurcooL/markdownfmt): like gofmt,
256 but for markdown.
257
258* [LaTeX output](https://github.com/Ambrevar/Blackfriday-LaTeX):
259 renders output as LaTeX.
260
261
262Todo
263----
264
265* More unit testing
266* Improve unicode support. It does not understand all unicode
267 rules (about what constitutes a letter, a punctuation symbol,
268 etc.), so it may fail to detect word boundaries correctly in
269 some instances. It is safe on all utf-8 input.
270
271
272License
273-------
274
275[Blackfriday is distributed under the Simplified BSD License](LICENSE.txt)
276
277
278 [1]: https://daringfireball.net/projects/markdown/ "Markdown"
279 [2]: https://golang.org/ "Go Language"
280 [3]: https://github.com/vmg/sundown "Sundown"
281 [4]: https://godoc.org/gopkg.in/russross/blackfriday.v2#Parse "Parse func"
282 [5]: https://github.com/microcosm-cc/bluemonday "Bluemonday"
283 [6]: https://labix.org/gopkg.in "gopkg.in"