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 [upskirt][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 upskirt 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* **Autolinking**. Blackfriday can find URLs that have not been
173 explicitly marked as links and turn them into links.
174
175* **Strikethrough**. Use two tildes (`~~`) to mark text that
176 should be crossed out.
177
178* **Hard line breaks**. With this extension enabled (it is off by
179 default in the `MarkdownBasic` and `MarkdownCommon` convenience
180 functions), newlines in the input translate into line breaks in
181 the output.
182
183* **Smart quotes**. Smartypants-style punctuation substitution is
184 supported, turning normal double- and single-quote marks into
185 curly quotes, etc.
186
187* **LaTeX-style dash parsing** is an additional option, where `--`
188 is translated into `–`, and `---` is translated into
189 `—`. This differs from most smartypants processors, which
190 turn a single hyphen into an ndash and a double hyphen into an
191 mdash.
192
193* **Smart fractions**, where anything that looks like a fraction
194 is translated into suitable HTML (instead of just a few special
195 cases like most smartypant processors). For example, `4/5`
196 becomes `<sup>4</sup>⁄<sub>5</sub>`, which renders as
197 <sup>4</sup>⁄<sub>5</sub>.
198
199
200Other renderers
201---------------
202
203Blackfriday is structured to allow alternative rendering engines. Here
204are a few of note:
205
206* [github_flavored_markdown](https://godoc.org/github.com/shurcooL/go/github_flavored_markdown):
207 provides a GitHub Flavored Markdown renderer with fenced code block
208 highlighting, clickable header anchor links.
209
210 It's not customizable, and its goal is to produce HTML output
211 equivalent to the [GitHub Markdown API endpoint](https://developer.github.com/v3/markdown/#render-a-markdown-document-in-raw-mode),
212 except the rendering is performed locally.
213
214* [markdownfmt](https://github.com/shurcooL/markdownfmt): like gofmt,
215 but for markdown.
216
217* LaTeX output: renders output as LaTeX. This is currently part of the
218 main Blackfriday repository, but may be split into its own project
219 in the future. If you are interested in owning and maintaining the
220 LaTeX output component, please be in touch.
221
222 It renders some basic documents, but is only experimental at this
223 point. In particular, it does not do any inline escaping, so input
224 that happens to look like LaTeX code will be passed through without
225 modification.
226
227
228Todo
229----
230
231* More unit testing
232* Improve unicode support. It does not understand all unicode
233 rules (about what constitutes a letter, a punctuation symbol,
234 etc.), so it may fail to detect word boundaries correctly in
235 some instances. It is safe on all utf-8 input.
236
237
238License
239-------
240
241Blackfriday is distributed under the Simplified BSD License:
242
243> Copyright © 2011 Russ Ross
244> All rights reserved.
245>
246> Redistribution and use in source and binary forms, with or without
247> modification, are permitted provided that the following conditions
248> are met:
249>
250> 1. Redistributions of source code must retain the above copyright
251> notice, this list of conditions and the following disclaimer.
252>
253> 2. Redistributions in binary form must reproduce the above
254> copyright notice, this list of conditions and the following
255> disclaimer in the documentation and/or other materials provided with
256> the distribution.
257>
258> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
259> "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
260> LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
261> FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
262> COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
263> INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
264> BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
265> LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
266> CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
267> LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
268> ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
269> POSSIBILITY OF SUCH DAMAGE.
270
271
272 [1]: http://daringfireball.net/projects/markdown/ "Markdown"
273 [2]: http://golang.org/ "Go Language"
274 [3]: http://github.com/tanoku/upskirt "Upskirt"