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