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