1 Blackfriday [![Build Status](https://travis-ci.org/russross/blackfriday.svg?branch=master)](https://travis-ci.org/russross/blackfriday)

     2 ===========

     3 

     4 Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It

     5 is paranoid about its input (so you can safely feed it user-supplied

     6 data), it is fast, it supports common extensions (tables, smart

     7 punctuation substitutions, etc.), and it is safe for all utf-8

     8 (unicode) input.

     9 

    10 HTML output is currently supported, along with Smartypants

    11 extensions.

    12 

    13 It started as a translation from C of [Sundown][3].

    14 

    15 

    16 Installation

    17 ------------

    18 

    19 Blackfriday is compatible with any modern Go release. With Go 1.7 and git

    20 installed:

    21 

    22     go get gopkg.in/russross/blackfriday.v2

    23 

    24 will download, compile, and install the package into your `$GOPATH`

    25 directory hierarchy. Alternatively, you can achieve the same if you

    26 import it into a project:

    27 

    28     import "gopkg.in/russross/blackfriday.v2"

    29 

    30 and `go get` without parameters.

    31 

    32 

    33 Versions

    34 --------

    35 

    36 Currently maintained and recommended version of Blackfriday is `v2`. It's being

    37 developed on its own branch: https://github.com/russross/blackfriday/tree/v2 and the

    38 documentation is available at

    39 https://godoc.org/gopkg.in/russross/blackfriday.v2.

    40 

    41 It is `go get`-able via via [gopkg.in][6] at `gopkg.in/russross/blackfriday.v2`,

    42 but we highly recommend using package management tool like [dep][7] or

    43 [Glide][8] and make use of semantic versioning. With package management you

    44 should import `github.com/russross/blackfriday` and specify that you're using

    45 version 2.0.0.

    46 

    47 Version 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 

    55 Potential 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 

    65 Usage

    66 -----

    67 

    68 For the most sensible markdown processing, it is as simple as getting your input

    69 into a byte slice and calling:

    70 

    71 ```go

    72 output := blackfriday.Run(input)

    73 ```

    74 

    75 Your input will be parsed and the output rendered with a set of most popular

    76 extensions enabled. If you want the most basic feature set, corresponding with

    77 the bare Markdown specification, use:

    78 

    79 ```go

    80 output := blackfriday.Run(input, blackfriday.WithNoExtensions())

    81 ```

    82 

    83 ### Sanitize untrusted content

    84 

    85 Blackfriday itself does nothing to protect against malicious content. If you are

    86 dealing with user-supplied markdown, we recommend running Blackfriday's output

    87 through HTML sanitizer such as [Bluemonday][5].

    88 

    89 Here's an example of simple usage of Blackfriday together with Bluemonday:

    90 

    91 ```go

    92 import (

    93     "github.com/microcosm-cc/bluemonday"

    94     "github.com/russross/blackfriday"

    95 )

    96 

    97 // ...

    98 unsafe := blackfriday.Run(input)

    99 html := bluemonday.UGCPolicy().SanitizeBytes(unsafe)

   100 ```

   101 

   102 ### Custom options

   103 

   104 If you want to customize the set of options, use `blackfriday.WithExtensions`,

   105 `blackfriday.WithRenderer` and `blackfriday.WithRefOverride`.

   106 

   107 You can also check out `blackfriday-tool` for a more complete example

   108 of how to use it. Download and install it using:

   109 

   110     go get github.com/russross/blackfriday-tool

   111 

   112 This is a simple command-line tool that allows you to process a

   113 markdown file using a standalone program.  You can also browse the

   114 source directly on github if you are just looking for some example

   115 code:

   116 

   117 * <http://github.com/russross/blackfriday-tool>

   118 

   119 Note that if you have not already done so, installing

   120 `blackfriday-tool` will be sufficient to download and install

   121 blackfriday in addition to the tool itself. The tool binary will be

   122 installed in `$GOPATH/bin`.  This is a statically-linked binary that

   123 can be copied to wherever you need it without worrying about

   124 dependencies and library versions.

   125 

   126 

   127 Features

   128 --------

   129 

   130 All 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 

   166 Extensions

   167 ----------

   168 

   169 In addition to the standard markdown syntax, this package

   170 implements 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 `–`, and `---` is translated into

   236     `—`. 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 

   247 Other renderers

   248 ---------------

   249 

   250 Blackfriday is structured to allow alternative rendering engines. Here

   251 are 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 

   270 Todo

   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 

   280 License

   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"