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