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