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