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