1Blackfriday
  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 [upskirt][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 import it into a
 30project:
 31
 32    import "github.com/russross/blackfriday"
 33
 34and when you build that project with `go build`, blackfriday will be
 35downloaded and installed automatically.
 36
 37Usage
 38-----
 39
 40For basic usage, it is as simple as getting your input into a byte
 41slice and calling:
 42
 43    output := blackfriday.MarkdownBasic(input)
 44
 45This renders it with no extensions enabled. To get a more useful
 46feature set, use this instead:
 47
 48    output := blackfriday.MarkdownCommon(input)
 49
 50If you want to customize the set of options, first get a renderer
 51(currently either the HTML or LaTeX output engines), then use it to
 52call the more general `Markdown` function. For examples, see the
 53implementations of `MarkdownBasic` and `MarkdownCommon` in
 54`markdown.go`.
 55
 56You can also check out `blackfriday-tool` for a more complete example
 57of how to use it. Download and install it using:
 58
 59    go get github.com/russross/blackfriday-tool
 60
 61This is a simple command-line tool that allows you to process a
 62markdown file using a standalone program.  You can also browse the
 63source directly on github if you are just looking for some example
 64code:
 65
 66* <http://github.com/russross/blackfriday-tool>
 67
 68Note that if you have not already done so, installing
 69`blackfriday-tool` will be sufficient to download and install
 70blackfriday in addition to the tool itself. The tool binary will be
 71installed in `$GOPATH/bin`.  This is a statically-linked binary that
 72can be copied to wherever you need it without worrying about
 73dependencies and library versions.
 74
 75
 76Features
 77--------
 78
 79All features of upskirt are supported, including:
 80
 81*   **Compatibility**. The Markdown v1.0.3 test suite passes with
 82    the `--tidy` option.  Without `--tidy`, the differences are
 83    mostly in whitespace and entity escaping, where blackfriday is
 84    more consistent and cleaner.
 85
 86*   **Common extensions**, including table support, fenced code
 87    blocks, autolinks, strikethroughs, non-strict emphasis, etc.
 88
 89*   **Safety**. Blackfriday is paranoid when parsing, making it safe
 90    to feed untrusted user input without fear of bad things
 91    happening. The test suite stress tests this and there are no
 92    known inputs that make it crash.  If you find one, please let me
 93    know and send me the input that does it.
 94
 95    NOTE: "safety" in this context means *runtime safety only*. It is
 96    not bullet proof against JavaScript injections, though we're working
 97    on it (https://github.com/russross/blackfriday/issues/11 tracks the
 98    progress).
 99
100*   **Fast processing**. It is fast enough to render on-demand in
101    most web applications without having to cache the output.
102
103*   **Thread safety**. You can run multiple parsers in different
104    goroutines without ill effect. There is no dependence on global
105    shared state.
106
107*   **Minimal dependencies**. Blackfriday only depends on standard
108    library packages in Go. The source code is pretty
109    self-contained, so it is easy to add to any project, including
110    Google App Engine projects.
111
112*   **Standards compliant**. Output successfully validates using the
113    W3C validation tool for HTML 4.01 and XHTML 1.0 Transitional.
114
115
116Extensions
117----------
118
119In addition to the standard markdown syntax, this package
120implements the following extensions:
121
122*   **Intra-word emphasis supression**. The `_` character is
123    commonly used inside words when discussing code, so having
124    markdown interpret it as an emphasis command is usually the
125    wrong thing. Blackfriday lets you treat all emphasis markers as
126    normal characters when they occur inside a word.
127
128*   **Tables**. Tables can be created by drawing them in the input
129    using a simple syntax:
130
131    ```
132    Name    | Age
133    --------|------
134    Bob     | 27
135    Alice   | 23
136    ```
137
138*   **Fenced code blocks**. In addition to the normal 4-space
139    indentation to mark code blocks, you can explicitly mark them
140    and supply a language (to make syntax highlighting simple). Just
141    mark it like this:
142
143        ``` go
144        func getTrue() bool {
145            return true
146        }
147        ```
148
149    You can use 3 or more backticks to mark the beginning of the
150    block, and the same number to mark the end of the block.
151
152*   **Autolinking**. Blackfriday can find URLs that have not been
153    explicitly marked as links and turn them into links.
154
155*   **Strikethrough**. Use two tildes (`~~`) to mark text that
156    should be crossed out.
157
158*   **Hard line breaks**. With this extension enabled (it is off by
159    default in the `MarkdownBasic` and `MarkdownCommon` convenience
160    functions), newlines in the input translate into line breaks in
161    the output.
162
163*   **Smart quotes**. Smartypants-style punctuation substitution is
164    supported, turning normal double- and single-quote marks into
165    curly quotes, etc.
166
167*   **LaTeX-style dash parsing** is an additional option, where `--`
168    is translated into `&ndash;`, and `---` is translated into
169    `&mdash;`. This differs from most smartypants processors, which
170    turn a single hyphen into an ndash and a double hyphen into an
171    mdash.
172
173*   **Smart fractions**, where anything that looks like a fraction
174    is translated into suitable HTML (instead of just a few special
175    cases like most smartypant processors). For example, `4/5`
176    becomes `<sup>4</sup>&frasl;<sub>5</sub>`, which renders as
177    <sup>4</sup>&frasl;<sub>5</sub>.
178
179
180Other renderers
181---------------
182
183Blackfriday is structured to allow alternative rendering engines. Here
184are a few of note:
185
186*   [github_flavored_markdown](https://godoc.org/github.com/shurcooL/go/github_flavored_markdown):
187    provides a GitHub Flavored Markdown renderer with fenced code block
188    highlighting, clickable header anchor links.
189
190    It's not customizable, and its goal is to produce HTML output
191    equivalent to the [GitHub Markdown API endpoint](https://developer.github.com/v3/markdown/#render-a-markdown-document-in-raw-mode),
192    except the rendering is performed locally.
193
194*   [markdownfmt](https://github.com/shurcooL/markdownfmt): like gofmt,
195    but for markdown.
196
197*   LaTeX output: renders output as LaTeX. This is currently part of the
198    main Blackfriday repository, but may be split into its own project
199    in the future. If you are interested in owning and maintaining the
200    LaTeX output component, please be in touch.
201
202    It renders some basic documents, but is only experimental at this
203    point. In particular, it does not do any inline escaping, so input
204    that happens to look like LaTeX code will be passed through without
205    modification.
206
207
208Todo
209----
210
211*   More unit testing
212*   Markdown pretty-printer output engine
213*   Improve unicode support. It does not understand all unicode
214    rules (about what constitutes a letter, a punctuation symbol,
215    etc.), so it may fail to detect word boundaries correctly in
216    some instances. It is safe on all utf-8 input.
217
218
219License
220-------
221
222Blackfriday is distributed under the Simplified BSD License:
223
224> Copyright © 2011 Russ Ross
225> All rights reserved.
226> 
227> Redistribution and use in source and binary forms, with or without
228> modification, are permitted provided that the following conditions
229> are met:
230> 
231> 1.  Redistributions of source code must retain the above copyright
232>     notice, this list of conditions and the following disclaimer.
233> 
234> 2.  Redistributions in binary form must reproduce the above
235>     copyright notice, this list of conditions and the following
236>     disclaimer in the documentation and/or other materials provided with
237>     the distribution.
238> 
239> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
240> "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
241> LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
242> FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
243> COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
244> INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
245> BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
246> LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
247> CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
248> LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
249> ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
250> POSSIBILITY OF SUCH DAMAGE.
251
252
253   [1]: http://daringfireball.net/projects/markdown/ "Markdown"
254   [2]: http://golang.org/ "Go Language"
255   [3]: http://github.com/tanoku/upskirt "Upskirt"