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
180LaTeX Output
181------------
182
183A rudimentary LaTeX rendering backend is also included. To see an
184example of its usage, see `main.go`:
185
186It renders some basic documents, but is only experimental at this
187point. In particular, it does not do any inline escaping, so input
188that happens to look like LaTeX code will be passed through without
189modification.
190
191
192Todo
193----
194
195*   More unit testing
196*   Markdown pretty-printer output engine
197*   Improve unicode support. It does not understand all unicode
198    rules (about what constitutes a letter, a punctuation symbol,
199    etc.), so it may fail to detect word boundaries correctly in
200    some instances. It is safe on all utf-8 input.
201
202
203License
204-------
205
206Blackfriday is distributed under the Simplified BSD License:
207
208> Copyright © 2011 Russ Ross
209> All rights reserved.
210> 
211> Redistribution and use in source and binary forms, with or without
212> modification, are permitted provided that the following conditions
213> are met:
214> 
215> 1.  Redistributions of source code must retain the above copyright
216>     notice, this list of conditions and the following disclaimer.
217> 
218> 2.  Redistributions in binary form must reproduce the above
219>     copyright notice, this list of conditions and the following
220>     disclaimer in the documentation and/or other materials provided with
221>     the distribution.
222> 
223> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
224> "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
225> LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
226> FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
227> COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
228> INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
229> BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
230> LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
231> CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
232> LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
233> ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
234> POSSIBILITY OF SUCH DAMAGE.
235
236
237   [1]: http://daringfireball.net/projects/markdown/ "Markdown"
238   [2]: http://golang.org/ "Go Language"
239   [3]: http://github.com/tanoku/upskirt "Upskirt"