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