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/v2. You

    38 should install and import it via [gopkg.in][6] at

    39 `gopkg.in/russross/blackfriday.v2`.

    40 

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

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

    59 Usage

    60 -----

    61 

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

    63 into a byte slice and calling:

    64 

    65 ```go

    66 output := blackfriday.Run(input)

    67 ```

    68 

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

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

    71 the bare Markdown specification, use:

    72 

    73 ```go

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

    75 ```

    76 

    77 ### Sanitize untrusted content

    78 

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

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

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

    82 

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

    84 

    85 ```go

    86 import (

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

    88     "github.com/russross/blackfriday"

    89 )

    90 

    91 // ...

    92 unsafe := blackfriday.Run(input)

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

    94 ```

    95 

    96 ### Custom options

    97 

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

    99 `blackfriday.WithRenderer` and `blackfriday.WithRefOverride`.

   100 

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

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

   103 

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

   105 

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

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

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

   109 code:

   110 

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

   112 

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

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

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

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

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

   118 dependencies and library versions.

   119 

   120 

   121 Features

   122 --------

   123 

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

   160 Extensions

   161 ----------

   162 

   163 In addition to the standard markdown syntax, this package

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

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

   241 Other renderers

   242 ---------------

   243 

   244 Blackfriday is structured to allow alternative rendering engines. Here

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

   262 Todo

   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 

   272 License

   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"