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