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
107You can also check out `blackfriday-tool` for a more complete example
108of how to use it. Download and install it using:
109
110    go get github.com/russross/blackfriday-tool
111
112This is a simple command-line tool that allows you to process a
113markdown file using a standalone program.  You can also browse the
114source directly on github if you are just looking for some example
115code:
116
117* <http://github.com/russross/blackfriday-tool>
118
119Note that if you have not already done so, installing
120`blackfriday-tool` will be sufficient to download and install
121blackfriday in addition to the tool itself. The tool binary will be
122installed in `$GOPATH/bin`.  This is a statically-linked binary that
123can be copied to wherever you need it without worrying about
124dependencies and library versions.
125
126
127Features
128--------
129
130All features of Sundown are supported, including:
131
132*   **Compatibility**. The Markdown v1.0.3 test suite passes with
133    the `--tidy` option.  Without `--tidy`, the differences are
134    mostly in whitespace and entity escaping, where blackfriday is
135    more consistent and cleaner.
136
137*   **Common extensions**, including table support, fenced code
138    blocks, autolinks, strikethroughs, non-strict emphasis, etc.
139
140*   **Safety**. Blackfriday is paranoid when parsing, making it safe
141    to feed untrusted user input without fear of bad things
142    happening. The test suite stress tests this and there are no
143    known inputs that make it crash.  If you find one, please let me
144    know and send me the input that does it.
145
146    NOTE: "safety" in this context means *runtime safety only*. In order to
147    protect yourself against JavaScript injection in untrusted content, see
148    [this example](https://github.com/russross/blackfriday#sanitize-untrusted-content).
149
150*   **Fast processing**. It is fast enough to render on-demand in
151    most web applications without having to cache the output.
152
153*   **Thread safety**. You can run multiple parsers in different
154    goroutines without ill effect. There is no dependence on global
155    shared state.
156
157*   **Minimal dependencies**. Blackfriday only depends on standard
158    library packages in Go. The source code is pretty
159    self-contained, so it is easy to add to any project, including
160    Google App Engine projects.
161
162*   **Standards compliant**. Output successfully validates using the
163    W3C validation tool for HTML 4.01 and XHTML 1.0 Transitional.
164
165
166Extensions
167----------
168
169In addition to the standard markdown syntax, this package
170implements the following extensions:
171
172*   **Intra-word emphasis supression**. The `_` character is
173    commonly used inside words when discussing code, so having
174    markdown interpret it as an emphasis command is usually the
175    wrong thing. Blackfriday lets you treat all emphasis markers as
176    normal characters when they occur inside a word.
177
178*   **Tables**. Tables can be created by drawing them in the input
179    using a simple syntax:
180
181    ```
182    Name    | Age
183    --------|------
184    Bob     | 27
185    Alice   | 23
186    ```
187
188*   **Fenced code blocks**. In addition to the normal 4-space
189    indentation to mark code blocks, you can explicitly mark them
190    and supply a language (to make syntax highlighting simple). Just
191    mark it like this:
192
193        ```go
194        func getTrue() bool {
195            return true
196        }
197        ```
198
199    You can use 3 or more backticks to mark the beginning of the
200    block, and the same number to mark the end of the block.
201
202*   **Definition lists**. A simple definition list is made of a single-line
203    term followed by a colon and the definition for that term.
204
205        Cat
206        : Fluffy animal everyone likes
207
208        Internet
209        : Vector of transmission for pictures of cats
210
211    Terms must be separated from the previous definition by a blank line.
212
213*   **Footnotes**. A marker in the text that will become a superscript number;
214    a footnote definition that will be placed in a list of footnotes at the
215    end of the document. A footnote looks like this:
216
217        This is a footnote.[^1]
218
219        [^1]: the footnote text.
220
221*   **Autolinking**. Blackfriday can find URLs that have not been
222    explicitly marked as links and turn them into links.
223
224*   **Strikethrough**. Use two tildes (`~~`) to mark text that
225    should be crossed out.
226
227*   **Hard line breaks**. With this extension enabled newlines in the input
228    translate into line breaks in the output. This extension is off by default.
229
230*   **Smart quotes**. Smartypants-style punctuation substitution is
231    supported, turning normal double- and single-quote marks into
232    curly quotes, etc.
233
234*   **LaTeX-style dash parsing** is an additional option, where `--`
235    is translated into `&ndash;`, and `---` is translated into
236    `&mdash;`. This differs from most smartypants processors, which
237    turn a single hyphen into an ndash and a double hyphen into an
238    mdash.
239
240*   **Smart fractions**, where anything that looks like a fraction
241    is translated into suitable HTML (instead of just a few special
242    cases like most smartypant processors). For example, `4/5`
243    becomes `<sup>4</sup>&frasl;<sub>5</sub>`, which renders as
244    <sup>4</sup>&frasl;<sub>5</sub>.
245
246
247Other renderers
248---------------
249
250Blackfriday is structured to allow alternative rendering engines. Here
251are a few of note:
252
253*   [github_flavored_markdown](https://godoc.org/github.com/shurcooL/github_flavored_markdown):
254    provides a GitHub Flavored Markdown renderer with fenced code block
255    highlighting, clickable heading anchor links.
256
257    It's not customizable, and its goal is to produce HTML output
258    equivalent to the [GitHub Markdown API endpoint](https://developer.github.com/v3/markdown/#render-a-markdown-document-in-raw-mode),
259    except the rendering is performed locally.
260
261*   [markdownfmt](https://github.com/shurcooL/markdownfmt): like gofmt,
262    but for markdown.
263
264*   [LaTeX output](https://github.com/Ambrevar/Blackfriday-LaTeX):
265    renders output as LaTeX.
266
267*   [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.
268
269
270Todo
271----
272
273*   More unit testing
274*   Improve unicode support. It does not understand all unicode
275    rules (about what constitutes a letter, a punctuation symbol,
276    etc.), so it may fail to detect word boundaries correctly in
277    some instances. It is safe on all utf-8 input.
278
279
280License
281-------
282
283[Blackfriday is distributed under the Simplified BSD License](LICENSE.txt)
284
285
286   [1]: https://daringfireball.net/projects/markdown/ "Markdown"
287   [2]: https://golang.org/ "Go Language"
288   [3]: https://github.com/vmg/sundown "Sundown"
289   [4]: https://godoc.org/gopkg.in/russross/blackfriday.v2#Parse "Parse func"
290   [5]: https://github.com/microcosm-cc/bluemonday "Bluemonday"
291   [6]: https://labix.org/gopkg.in "gopkg.in"