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
 19Assuming you have recent version of Go installed, along with git:
 20
 21    goinstall github.com/russross/blackfriday
 22
 23will download, compile, and install the package into
 24`$GOROOT/src/pkg/github.com/russross/blackfriday`.
 25
 26For basic usage, it is as simple as getting your input into a byte
 27slice and calling:
 28
 29    output := blackfriday.MarkdownBasic(input)
 30
 31This renders it with no extensions enabled. To get a more useful
 32feature set, use this instead:
 33
 34    output := blackfriday.MarkdownCommon(input)
 35
 36If you want to customize the set of options, first get a renderer
 37(currently either the HTML or LaTeX output engines), then use it to
 38call the more general `Markdown` function. For examples, see the
 39implementations of `MarkdownBasic` and `MarkdownCommon` in
 40`markdown.go`.
 41
 42You can also check out `example/main.go` for a more complete example
 43of how to use it. Run `gomake` in that directory to build a simple
 44command-line markdown tool:
 45
 46    cd $GOROOT/src/pkg/github.com/russross/blackfriday/example
 47    gomake
 48
 49will build the binary `markdown` in the `example` directory.
 50
 51
 52Features
 53--------
 54
 55All features of upskirt are supported, including:
 56
 57*   The Markdown v1.0.3 test suite passes with the `--tidy` option.
 58    Without `--tidy`, the differences appear to be bugs/dubious
 59    features in the original, mostly related to whitespace.
 60
 61*   Common extensions, including table support, fenced code blocks,
 62    autolinks, strikethroughs, non-strict emphasis, etc.
 63
 64*   Paranoid parsing, making it safe to feed untrusted used input
 65    without fear of bad things happening. There are still some
 66    corner cases that are untested, but it is already more strict
 67    than upskirt (bounds checking in Go uncovered a few off-by-one
 68    errors that were present in upskirt).
 69
 70*   Good performance. I have not done rigorous benchmarking, but
 71    informal testing suggests it is around 3--4x slower than upskirt
 72    for general input. It blows away most other markdown processors.
 73
 74*   Thread safe. You can run multiple parsers is different
 75    goroutines without ill effect. There is no dependence on global
 76    shared state.
 77
 78*   Minimal dependencies. Blackfriday only depends on standard
 79    library packages in Go. The source code is pretty
 80    self-contained, so it is easy to add to any project.
 81
 82*   Output successfully validates using the W3C validation tool for
 83    HTML 4.01 and XHTML 1.0 Transitional.
 84
 85
 86Extensions
 87----------
 88
 89In addition to the extensions offered by upskirt, this package
 90implements two additional Smartypants options:
 91
 92*   LaTeX-style dash parsing, where `--` is translated into
 93    `–`, and `---` is translated into `—`
 94*   Generic fractions, where anything that looks like a fraction is
 95    translated into suitable HTML (instead of just a few special
 96    cases).  For example, `4/5` becomes
 97    `<sup>4</sup>&frasl;<sub>5</sub>`, which renders as
 98    <sup>4</sup>&frasl;<sub>5</sub>.
 99
100
101LaTeX Output
102------------
103
104A rudimentary LaTeX rendering backend is also included. To see an
105example of its usage, see `main.go`:
106
107It renders some basic documents, but is only experimental at this
108point. In particular, it does not do any inline escaping, so input
109that happens to look like LaTeX code will be passed through without
110modification.
111
112
113Todo
114----
115
116*   More unit testing
117*   Code cleanup
118*   Better code documentation
119*   Markdown pretty-printer output engine
120*   Improve unicode support. It does not understand all unicode
121    rules (about what constitutes a letter, a punctuation symbol,
122    etc.), so it may fail to detect word boundaries correctly in
123    some instances. It is safe on all utf-8 input.
124
125
126License
127-------
128
129Blackfriday is distributed under the Simplified BSD License:
130
131> Copyright © 2011 Russ Ross. All rights reserved.
132> 
133> Redistribution and use in source and binary forms, with or without modification, are
134> permitted provided that the following conditions are met:
135> 
136>    1. Redistributions of source code must retain the above copyright notice, this list of
137>       conditions and the following disclaimer.
138> 
139>    2. Redistributions in binary form must reproduce the above copyright notice, this list
140>       of conditions and the following disclaimer in the documentation and/or other materials
141>       provided with the distribution.
142> 
143> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER ``AS IS'' AND ANY EXPRESS OR IMPLIED
144> WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
145> FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> OR
146> CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
147> CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
148> SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
149> ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
150> NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
151> ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
152> 
153> The views and conclusions contained in the software and documentation are those of the
154> authors and should not be interpreted as representing official policies, either expressed
155> or implied, of the copyright holder.
156
157
158   [1]: http://daringfireball.net/projects/markdown/ "Markdown"
159   [2]: http://golang.org/ "Go Language"
160   [3]: http://github.com/tanoku/upskirt "Upskirt"