1Blackfriday
2[![Build Status][BuildV2SVG]][BuildV2URL]
3[![PkgGoDev][PkgGoDevV2SVG]][PkgGoDevV2URL]
4===========
5
6Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It
7is paranoid about its input (so you can safely feed it user-supplied
8data), it is fast, it supports common extensions (tables, smart
9punctuation substitutions, etc.), and it is safe for all utf-8
10(unicode) input.
11
12HTML output is currently supported, along with Smartypants
13extensions.
14
15It started as a translation from C of [Sundown][3].
16
17
18Installation
19------------
20
21Blackfriday is compatible with modern Go releases in module mode.
22With Go installed:
23
24 go get github.com/russross/blackfriday/v2
25
26will resolve and add the package to the current development module,
27then build and install it. Alternatively, you can achieve the same
28if you import it in a package:
29
30 import "github.com/russross/blackfriday/v2"
31
32and `go get` without parameters.
33
34Legacy GOPATH mode is unsupported.
35
36
37Versions
38--------
39
40Currently maintained and recommended version of Blackfriday is `v2`. It's being
41developed on its own branch: https://github.com/russross/blackfriday/tree/v2 and the
42documentation is available at
43https://pkg.go.dev/github.com/russross/blackfriday/v2.
44
45It is `go get`-able in module mode at `github.com/russross/blackfriday/v2`.
46
47Version 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
55Potential 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
65If you are still interested in the legacy `v1`, you can import it from
66`github.com/russross/blackfriday`. Documentation for the legacy v1 can be found
67here: https://pkg.go.dev/github.com/russross/blackfriday.
68
69
70Usage
71-----
72
73For the most sensible markdown processing, it is as simple as getting your input
74into a byte slice and calling:
75
76```go
77output := blackfriday.Run(input)
78```
79
80Your input will be parsed and the output rendered with a set of most popular
81extensions enabled. If you want the most basic feature set, corresponding with
82the bare Markdown specification, use:
83
84```go
85output := blackfriday.Run(input, blackfriday.WithNoExtensions())
86```
87
88### Sanitize untrusted content
89
90Blackfriday itself does nothing to protect against malicious content. If you are
91dealing with user-supplied markdown, we recommend running Blackfriday's output
92through HTML sanitizer such as [Bluemonday][5].
93
94Here's an example of simple usage of Blackfriday together with Bluemonday:
95
96```go
97import (
98 "github.com/microcosm-cc/bluemonday"
99 "github.com/russross/blackfriday/v2"
100)
101
102// ...
103unsafe := blackfriday.Run(input)
104html := bluemonday.UGCPolicy().SanitizeBytes(unsafe)
105```
106
107### Custom options
108
109If you want to customize the set of options, use `blackfriday.WithExtensions`,
110`blackfriday.WithRenderer` and `blackfriday.WithRefOverride`.
111
112### `blackfriday-tool`
113
114You can also check out `blackfriday-tool` for a more complete example
115of how to use it. Download and install it using:
116
117 go get github.com/russross/blackfriday-tool
118
119This is a simple command-line tool that allows you to process a
120markdown file using a standalone program. You can also browse the
121source directly on github if you are just looking for some example
122code:
123
124* <https://github.com/russross/blackfriday-tool>
125
126Note that if you have not already done so, installing
127`blackfriday-tool` will be sufficient to download and install
128blackfriday in addition to the tool itself. The tool binary will be
129installed in `$GOPATH/bin`. This is a statically-linked binary that
130can be copied to wherever you need it without worrying about
131dependencies and library versions.
132
133### Sanitized anchor names
134
135Blackfriday includes an algorithm for creating sanitized anchor names
136corresponding to a given input text. This algorithm is used to create
137anchors for headings when `AutoHeadingIDs` extension is enabled. The
138algorithm has a specification, so that other packages can create
139compatible anchor names and links to those anchors.
140
141The specification is located at https://pkg.go.dev/github.com/russross/blackfriday/v2#hdr-Sanitized_Anchor_Names.
142
143[`SanitizedAnchorName`](https://pkg.go.dev/github.com/russross/blackfriday/v2#SanitizedAnchorName) exposes this functionality, and can be used to
144create compatible links to the anchor names generated by blackfriday.
145This algorithm is also implemented in a small standalone package at
146[`github.com/shurcooL/sanitized_anchor_name`](https://pkg.go.dev/github.com/shurcooL/sanitized_anchor_name). It can be useful for clients
147that want a small package and don't need full functionality of blackfriday.
148
149
150Features
151--------
152
153All features of Sundown are supported, including:
154
155* **Compatibility**. The Markdown v1.0.3 test suite passes with
156 the `--tidy` option. Without `--tidy`, the differences are
157 mostly in whitespace and entity escaping, where blackfriday is
158 more consistent and cleaner.
159
160* **Common extensions**, including table support, fenced code
161 blocks, autolinks, strikethroughs, non-strict emphasis, etc.
162
163* **Safety**. Blackfriday is paranoid when parsing, making it safe
164 to feed untrusted user input without fear of bad things
165 happening. The test suite stress tests this and there are no
166 known inputs that make it crash. If you find one, please let me
167 know and send me the input that does it.
168
169 NOTE: "safety" in this context means *runtime safety only*. In order to
170 protect yourself against JavaScript injection in untrusted content, see
171 [this example](https://github.com/russross/blackfriday#sanitize-untrusted-content).
172
173* **Fast processing**. It is fast enough to render on-demand in
174 most web applications without having to cache the output.
175
176* **Thread safety**. You can run multiple parsers in different
177 goroutines without ill effect. There is no dependence on global
178 shared state.
179
180* **Minimal dependencies**. Blackfriday only depends on standard
181 library packages in Go. The source code is pretty
182 self-contained, so it is easy to add to any project, including
183 Google App Engine projects.
184
185* **Standards compliant**. Output successfully validates using the
186 W3C validation tool for HTML 4.01 and XHTML 1.0 Transitional.
187
188
189Extensions
190----------
191
192In addition to the standard markdown syntax, this package
193implements the following extensions:
194
195* **Intra-word emphasis supression**. The `_` character is
196 commonly used inside words when discussing code, so having
197 markdown interpret it as an emphasis command is usually the
198 wrong thing. Blackfriday lets you treat all emphasis markers as
199 normal characters when they occur inside a word.
200
201* **Tables**. Tables can be created by drawing them in the input
202 using a simple syntax:
203
204 ```
205 Name | Age
206 --------|------
207 Bob | 27
208 Alice | 23
209 ```
210
211* **Fenced code blocks**. In addition to the normal 4-space
212 indentation to mark code blocks, you can explicitly mark them
213 and supply a language (to make syntax highlighting simple). Just
214 mark it like this:
215
216 ```go
217 func getTrue() bool {
218 return true
219 }
220 ```
221
222 You can use 3 or more backticks to mark the beginning of the
223 block, and the same number to mark the end of the block.
224
225 To preserve classes of fenced code blocks while using the bluemonday
226 HTML sanitizer, use the following policy:
227
228 ```go
229 p := bluemonday.UGCPolicy()
230 p.AllowAttrs("class").Matching(regexp.MustCompile("^language-[a-zA-Z0-9]+$")).OnElements("code")
231 html := p.SanitizeBytes(unsafe)
232 ```
233
234* **Definition lists**. A simple definition list is made of a single-line
235 term followed by a colon and the definition for that term.
236
237 Cat
238 : Fluffy animal everyone likes
239
240 Internet
241 : Vector of transmission for pictures of cats
242
243 Terms must be separated from the previous definition by a blank line.
244
245* **Footnotes**. A marker in the text that will become a superscript number;
246 a footnote definition that will be placed in a list of footnotes at the
247 end of the document. A footnote looks like this:
248
249 This is a footnote.[^1]
250
251 [^1]: the footnote text.
252
253* **Autolinking**. Blackfriday can find URLs that have not been
254 explicitly marked as links and turn them into links.
255
256* **Strikethrough**. Use two tildes (`~~`) to mark text that
257 should be crossed out.
258
259* **Hard line breaks**. With this extension enabled newlines in the input
260 translate into line breaks in the output. This extension is off by default.
261
262* **Smart quotes**. Smartypants-style punctuation substitution is
263 supported, turning normal double- and single-quote marks into
264 curly quotes, etc.
265
266* **LaTeX-style dash parsing** is an additional option, where `--`
267 is translated into `–`, and `---` is translated into
268 `—`. This differs from most smartypants processors, which
269 turn a single hyphen into an ndash and a double hyphen into an
270 mdash.
271
272* **Smart fractions**, where anything that looks like a fraction
273 is translated into suitable HTML (instead of just a few special
274 cases like most smartypant processors). For example, `4/5`
275 becomes `<sup>4</sup>⁄<sub>5</sub>`, which renders as
276 <sup>4</sup>⁄<sub>5</sub>.
277
278
279Other renderers
280---------------
281
282Blackfriday is structured to allow alternative rendering engines. Here
283are a few of note:
284
285* [github_flavored_markdown](https://pkg.go.dev/github.com/shurcooL/github_flavored_markdown):
286 provides a GitHub Flavored Markdown renderer with fenced code block
287 highlighting, clickable heading anchor links.
288
289 It's not customizable, and its goal is to produce HTML output
290 equivalent to the [GitHub Markdown API endpoint](https://developer.github.com/v3/markdown/#render-a-markdown-document-in-raw-mode),
291 except the rendering is performed locally.
292
293* [markdownfmt](https://github.com/shurcooL/markdownfmt): like gofmt,
294 but for markdown.
295
296* [LaTeX output](https://gitlab.com/ambrevar/blackfriday-latex):
297 renders output as LaTeX.
298
299* [bfchroma](https://github.com/Depado/bfchroma/): provides convenience
300 integration with the [Chroma](https://github.com/alecthomas/chroma) code
301 highlighting library. bfchroma is only compatible with v2 of Blackfriday and
302 provides a drop-in renderer ready to use with Blackfriday, as well as
303 options and means for further customization.
304
305* [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.
306
307* [Blackfriday-Slack](https://github.com/karriereat/blackfriday-slack): converts markdown to slack message style
308
309
310TODO
311----
312
313* More unit testing
314* Improve Unicode support. It does not understand all Unicode
315 rules (about what constitutes a letter, a punctuation symbol,
316 etc.), so it may fail to detect word boundaries correctly in
317 some instances. It is safe on all UTF-8 input.
318
319
320License
321-------
322
323[Blackfriday is distributed under the Simplified BSD License](LICENSE.txt)
324
325
326 [1]: https://daringfireball.net/projects/markdown/ "Markdown"
327 [2]: https://golang.org/ "Go Language"
328 [3]: https://github.com/vmg/sundown "Sundown"
329 [4]: https://pkg.go.dev/github.com/russross/blackfriday/v2#Parse "Parse func"
330 [5]: https://github.com/microcosm-cc/bluemonday "Bluemonday"
331
332 [BuildV2SVG]: https://travis-ci.org/russross/blackfriday.svg?branch=v2
333 [BuildV2URL]: https://travis-ci.org/russross/blackfriday
334 [PkgGoDevV2SVG]: https://pkg.go.dev/badge/github.com/russross/blackfriday/v2
335 [PkgGoDevV2URL]: https://pkg.go.dev/github.com/russross/blackfriday/v2
View as plain text