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 `&ndash;`, and `---` is translated into
268    `&mdash;`. 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
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