blackfriday/v2/README.md

Blackfriday
[![Build Status][BuildV2SVG]][BuildV2URL]
[![PkgGoDev][PkgGoDevV2SVG]][PkgGoDevV2URL]
===========

Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It
is paranoid about its input (so you can safely feed it user-supplied
data), it is fast, it supports common extensions (tables, smart
punctuation substitutions, etc.), and it is safe for all utf-8
(unicode) input.

HTML output is currently supported, along with Smartypants
extensions.

It started as a translation from C of [Sundown][3].


Installation
------------

Blackfriday is compatible with modern Go releases in module mode.
With Go installed:

    go get github.com/russross/blackfriday/v2

will resolve and add the package to the current development module,
then build and install it. Alternatively, you can achieve the same
if you import it in a package:

    import "github.com/russross/blackfriday/v2"

and `go get` without parameters.

Legacy GOPATH mode is unsupported.


Versions
--------

Currently maintained and recommended version of Blackfriday is `v2`. It's being
developed on its own branch: https://github.com/russross/blackfriday/tree/v2 and the
documentation is available at
https://pkg.go.dev/github.com/russross/blackfriday/v2.

It is `go get`-able in module mode at `github.com/russross/blackfriday/v2`.

Version 2 offers a number of improvements over v1:

* Cleaned up API
* A separate call to [`Parse`][4], which produces an abstract syntax tree for
  the document
* Latest bug fixes
* Flexibility to easily add your own rendering extensions

Potential drawbacks:

* Our benchmarks show v2 to be slightly slower than v1. Currently in the
  ballpark of around 15%.
* API breakage. If you can't afford modifying your code to adhere to the new API
  and don't care too much about the new features, v2 is probably not for you.
* Several bug fixes are trailing behind and still need to be forward-ported to
  v2. See issue [#348](https://github.com/russross/blackfriday/issues/348) for
  tracking.

If you are still interested in the legacy `v1`, you can import it from
`github.com/russross/blackfriday`. Documentation for the legacy v1 can be found
here: https://pkg.go.dev/github.com/russross/blackfriday.


Usage
-----

For the most sensible markdown processing, it is as simple as getting your input
into a byte slice and calling:

```go
output := blackfriday.Run(input)
```

Your input will be parsed and the output rendered with a set of most popular
extensions enabled. If you want the most basic feature set, corresponding with
the bare Markdown specification, use:

```go
output := blackfriday.Run(input, blackfriday.WithNoExtensions())
```

### Sanitize untrusted content

Blackfriday itself does nothing to protect against malicious content. If you are
dealing with user-supplied markdown, we recommend running Blackfriday's output
through HTML sanitizer such as [Bluemonday][5].

Here's an example of simple usage of Blackfriday together with Bluemonday:

```go
import (
    "github.com/microcosm-cc/bluemonday"
    "github.com/russross/blackfriday/v2"
)

// ...
unsafe := blackfriday.Run(input)
html := bluemonday.UGCPolicy().SanitizeBytes(unsafe)
```

### Custom options

If you want to customize the set of options, use `blackfriday.WithExtensions`,
`blackfriday.WithRenderer` and `blackfriday.WithRefOverride`.

### `blackfriday-tool`

You can also check out `blackfriday-tool` for a more complete example
of how to use it. Download and install it using:

    go get github.com/russross/blackfriday-tool

This is a simple command-line tool that allows you to process a
markdown file using a standalone program.  You can also browse the
source directly on github if you are just looking for some example
code:

* <https://github.com/russross/blackfriday-tool>

Note that if you have not already done so, installing
`blackfriday-tool` will be sufficient to download and install
blackfriday in addition to the tool itself. The tool binary will be
installed in `$GOPATH/bin`.  This is a statically-linked binary that
can be copied to wherever you need it without worrying about
dependencies and library versions.

### Sanitized anchor names

Blackfriday includes an algorithm for creating sanitized anchor names
corresponding to a given input text. This algorithm is used to create
anchors for headings when `AutoHeadingIDs` extension is enabled. The
algorithm has a specification, so that other packages can create
compatible anchor names and links to those anchors.

The specification is located at https://pkg.go.dev/github.com/russross/blackfriday/v2#hdr-Sanitized_Anchor_Names.

[`SanitizedAnchorName`](https://pkg.go.dev/github.com/russross/blackfriday/v2#SanitizedAnchorName) exposes this functionality, and can be used to
create compatible links to the anchor names generated by blackfriday.
This algorithm is also implemented in a small standalone package at
[`github.com/shurcooL/sanitized_anchor_name`](https://pkg.go.dev/github.com/shurcooL/sanitized_anchor_name). It can be useful for clients
that want a small package and don't need full functionality of blackfriday.


Features
--------

All features of Sundown are supported, including:

*   **Compatibility**. The Markdown v1.0.3 test suite passes with
    the `--tidy` option.  Without `--tidy`, the differences are
    mostly in whitespace and entity escaping, where blackfriday is
    more consistent and cleaner.

*   **Common extensions**, including table support, fenced code
    blocks, autolinks, strikethroughs, non-strict emphasis, etc.

*   **Safety**. Blackfriday is paranoid when parsing, making it safe
    to feed untrusted user input without fear of bad things
    happening. The test suite stress tests this and there are no
    known inputs that make it crash.  If you find one, please let me
    know and send me the input that does it.

    NOTE: "safety" in this context means *runtime safety only*. In order to
    protect yourself against JavaScript injection in untrusted content, see
    [this example](https://github.com/russross/blackfriday#sanitize-untrusted-content).

*   **Fast processing**. It is fast enough to render on-demand in
    most web applications without having to cache the output.

*   **Thread safety**. You can run multiple parsers in different
    goroutines without ill effect. There is no dependence on global
    shared state.

*   **Minimal dependencies**. Blackfriday only depends on standard
    library packages in Go. The source code is pretty
    self-contained, so it is easy to add to any project, including
    Google App Engine projects.

*   **Standards compliant**. Output successfully validates using the
    W3C validation tool for HTML 4.01 and XHTML 1.0 Transitional.


Extensions
----------

In addition to the standard markdown syntax, this package
implements the following extensions:

*   **Intra-word emphasis supression**. The `_` character is
    commonly used inside words when discussing code, so having
    markdown interpret it as an emphasis command is usually the
    wrong thing. Blackfriday lets you treat all emphasis markers as
    normal characters when they occur inside a word.

*   **Tables**. Tables can be created by drawing them in the input
    using a simple syntax:

    ```
    Name    | Age
    --------|------
    Bob     | 27
    Alice   | 23
    ```

*   **Fenced code blocks**. In addition to the normal 4-space
    indentation to mark code blocks, you can explicitly mark them
    and supply a language (to make syntax highlighting simple). Just
    mark it like this:

        ```go
        func getTrue() bool {
            return true
        }
        ```

    You can use 3 or more backticks to mark the beginning of the
    block, and the same number to mark the end of the block.

    To preserve classes of fenced code blocks while using the bluemonday
    HTML sanitizer, use the following policy:

    ```go
    p := bluemonday.UGCPolicy()
    p.AllowAttrs("class").Matching(regexp.MustCompile("^language-[a-zA-Z0-9]+$")).OnElements("code")
    html := p.SanitizeBytes(unsafe)
    ```

*   **Definition lists**. A simple definition list is made of a single-line
    term followed by a colon and the definition for that term.

        Cat
        : Fluffy animal everyone likes

        Internet
        : Vector of transmission for pictures of cats

    Terms must be separated from the previous definition by a blank line.

*   **Footnotes**. A marker in the text that will become a superscript number;
    a footnote definition that will be placed in a list of footnotes at the
    end of the document. A footnote looks like this:

        This is a footnote.[^1]

        [^1]: the footnote text.

*   **Autolinking**. Blackfriday can find URLs that have not been
    explicitly marked as links and turn them into links.

*   **Strikethrough**. Use two tildes (`~~`) to mark text that
    should be crossed out.

*   **Hard line breaks**. With this extension enabled newlines in the input
    translate into line breaks in the output. This extension is off by default.

*   **Smart quotes**. Smartypants-style punctuation substitution is
    supported, turning normal double- and single-quote marks into
    curly quotes, etc.

*   **LaTeX-style dash parsing** is an additional option, where `--`
    is translated into `&ndash;`, and `---` is translated into
    `&mdash;`. This differs from most smartypants processors, which
    turn a single hyphen into an ndash and a double hyphen into an
    mdash.

*   **Smart fractions**, where anything that looks like a fraction
    is translated into suitable HTML (instead of just a few special
    cases like most smartypant processors). For example, `4/5`
    becomes `<sup>4</sup>&frasl;<sub>5</sub>`, which renders as
    <sup>4</sup>&frasl;<sub>5</sub>.


Other renderers
---------------

Blackfriday is structured to allow alternative rendering engines. Here
are a few of note:

*   [github_flavored_markdown](https://pkg.go.dev/github.com/shurcooL/github_flavored_markdown):
    provides a GitHub Flavored Markdown renderer with fenced code block
    highlighting, clickable heading anchor links.

    It's not customizable, and its goal is to produce HTML output
    equivalent to the [GitHub Markdown API endpoint](https://developer.github.com/v3/markdown/#render-a-markdown-document-in-raw-mode),
    except the rendering is performed locally.

*   [markdownfmt](https://github.com/shurcooL/markdownfmt): like gofmt,
    but for markdown.

*   [LaTeX output](https://gitlab.com/ambrevar/blackfriday-latex):
    renders output as LaTeX.

*   [bfchroma](https://github.com/Depado/bfchroma/): provides convenience
    integration with the [Chroma](https://github.com/alecthomas/chroma) code
    highlighting library. bfchroma is only compatible with v2 of Blackfriday and
    provides a drop-in renderer ready to use with Blackfriday, as well as
    options and means for further customization.

*   [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.

*   [Blackfriday-Slack](https://github.com/karriereat/blackfriday-slack): converts markdown to slack message style


TODO
----

*   More unit testing
*   Improve Unicode support. It does not understand all Unicode
    rules (about what constitutes a letter, a punctuation symbol,
    etc.), so it may fail to detect word boundaries correctly in
    some instances. It is safe on all UTF-8 input.


License
-------

[Blackfriday is distributed under the Simplified BSD License](LICENSE.txt)


   [1]: https://daringfireball.net/projects/markdown/ "Markdown"
   [2]: https://golang.org/ "Go Language"
   [3]: https://github.com/vmg/sundown "Sundown"
   [4]: https://pkg.go.dev/github.com/russross/blackfriday/v2#Parse "Parse func"
   [5]: https://github.com/microcosm-cc/bluemonday "Bluemonday"

   [BuildV2SVG]: https://travis-ci.org/russross/blackfriday.svg?branch=v2
   [BuildV2URL]: https://travis-ci.org/russross/blackfriday
   [PkgGoDevV2SVG]: https://pkg.go.dev/badge/github.com/russross/blackfriday/v2
   [PkgGoDevV2URL]: https://pkg.go.dev/github.com/russross/blackfriday/v2
1	Blackfriday
2	[![Build Status][BuildV2SVG]][BuildV2URL]
3	[![PkgGoDev][PkgGoDevV2SVG]][PkgGoDevV2URL]
4	===========
5
6	Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It
7	is paranoid about its input (so you can safely feed it user-supplied
8	data), it is fast, it supports common extensions (tables, smart
9	punctuation substitutions, etc.), and it is safe for all utf-8
10	(unicode) input.
11
12	HTML output is currently supported, along with Smartypants
13	extensions.
14
15	It started as a translation from C of [Sundown][3].
16
17
18	Installation
19	------------
20
21	Blackfriday is compatible with modern Go releases in module mode.
22	With Go installed:
23
24	go get github.com/russross/blackfriday/v2
25
26	will resolve and add the package to the current development module,
27	then build and install it. Alternatively, you can achieve the same
28	if you import it in a package:
29
30	import "github.com/russross/blackfriday/v2"
31
32	and `go get` without parameters.
33
34	Legacy GOPATH mode is unsupported.
35
36
37	Versions
38	--------
39
40	Currently maintained and recommended version of Blackfriday is `v2`. It's being
41	developed on its own branch: https://github.com/russross/blackfriday/tree/v2 and the
42	documentation is available at
43	https://pkg.go.dev/github.com/russross/blackfriday/v2.
44
45	It is `go get`-able in module mode at `github.com/russross/blackfriday/v2`.
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	If 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
67	here: https://pkg.go.dev/github.com/russross/blackfriday.
68
69
70	Usage
71	-----
72
73	For the most sensible markdown processing, it is as simple as getting your input
74	into a byte slice and calling:
75
76	```go
77	output := blackfriday.Run(input)
78	```
79
80	Your input will be parsed and the output rendered with a set of most popular
81	extensions enabled. If you want the most basic feature set, corresponding with
82	the bare Markdown specification, use:
83
84	```go
85	output := blackfriday.Run(input, blackfriday.WithNoExtensions())
86	```
87
88	### Sanitize untrusted content
89
90	Blackfriday itself does nothing to protect against malicious content. If you are
91	dealing with user-supplied markdown, we recommend running Blackfriday's output
92	through HTML sanitizer such as [Bluemonday][5].
93
94	Here's an example of simple usage of Blackfriday together with Bluemonday:
95
96	```go
97	import (
98	"github.com/microcosm-cc/bluemonday"
99	"github.com/russross/blackfriday/v2"
100	)
101
102	// ...
103	unsafe := blackfriday.Run(input)
104	html := bluemonday.UGCPolicy().SanitizeBytes(unsafe)
105	```
106
107	### Custom options
108
109	If you want to customize the set of options, use `blackfriday.WithExtensions`,
110	`blackfriday.WithRenderer` and `blackfriday.WithRefOverride`.
111
112	### `blackfriday-tool`
113
114	You can also check out `blackfriday-tool` for a more complete example
115	of how to use it. Download and install it using:
116
117	go get github.com/russross/blackfriday-tool
118
119	This is a simple command-line tool that allows you to process a
120	markdown file using a standalone program. You can also browse the
121	source directly on github if you are just looking for some example
122	code:
123
124	* <https://github.com/russross/blackfriday-tool>
125
126	Note that if you have not already done so, installing
127	`blackfriday-tool` will be sufficient to download and install
128	blackfriday in addition to the tool itself. The tool binary will be
129	installed in `$GOPATH/bin`. This is a statically-linked binary that
130	can be copied to wherever you need it without worrying about
131	dependencies and library versions.
132
133	### Sanitized anchor names
134
135	Blackfriday includes an algorithm for creating sanitized anchor names
136	corresponding to a given input text. This algorithm is used to create
137	anchors for headings when `AutoHeadingIDs` extension is enabled. The
138	algorithm has a specification, so that other packages can create
139	compatible anchor names and links to those anchors.
140
141	The 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
144	create compatible links to the anchor names generated by blackfriday.
145	This 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
147	that want a small package and don't need full functionality of blackfriday.
148
149
150	Features
151	--------
152
153	All 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
189	Extensions
190	----------
191
192	In addition to the standard markdown syntax, this package
193	implements 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>&frasl;<sub>5</sub>`, which renders as
276	<sup>4</sup>&frasl;<sub>5</sub>.
277
278
279	Other renderers
280	---------------
281
282	Blackfriday is structured to allow alternative rendering engines. Here
283	are 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
310	TODO
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
320	License
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
nishi@chaotic.ninja	ViewVC Help
Powered by ViewVC 1.3.0-dev