1Blackfriday
  2===========
  3
  4This is an implementation of John Gruber's [markdown][1] in [Go][2].
  5It is a translation of the [upskirt][3] library written in C with a
  6few minor changes. It retains the paranoia of the original (it is
  7careful not to trust its input, and as such it should be safe to
  8feed it arbitrary user-supplied inputs). It also retains the
  9emphasis on high performance, and the source is almost as ugly as
 10the original.
 11
 12HTML output is currently supported, along with Smartypants
 13extensions. An experimental LaTeX output engine is also included.
 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
 26Check out `example/main.go` for an example of how to use it. Run
 27`gomake` in that directory to build a simple command-line markdown
 28tool:
 29
 30    cd $GOROOT/src/pkg/github.com/russross/blackfriday/example
 31    gomake
 32
 33will build the binary `markdown` in the `example` directory.
 34
 35
 36Features
 37--------
 38
 39All features of upskirt are supported, including:
 40
 41*   The Markdown v1.0.3 test suite passes with the `--tidy` option.
 42    Without `--tidy`, the differences appear to be bugs/dubious
 43    features in the original, mostly related to whitespace.
 44
 45*   Common extensions, including table support, fenced code blocks,
 46    autolinks, strikethroughs, non-strict emphasis, etc.
 47
 48*   Paranoid parsing, making it safe to feed untrusted used input
 49    without fear of bad things happening. There are still some
 50    corner cases that are untested, but it is already more strict
 51    than upskirt (Go's bounds-checking uncovered a few off-by-one
 52    errors that were present in the C code).
 53
 54*   Good performance. I have not done rigorous benchmarking, but
 55    informal testing suggests it is around 3--4x slower than upskirt.
 56
 57*   Minimal dependencies. Blackfriday only depends on standard
 58    library packages in Go. The source code is pretty
 59    self-contained, so it is easy to add to any project.
 60
 61*   Output successfully validates using the W3C validation tool for
 62    HTML 4.01 and XHTML 1.0 Transitional.
 63
 64
 65Extensions
 66----------
 67
 68In addition to the extensions offered by upskirt, this package
 69implements two additional Smartypants options:
 70
 71*   LaTeX-style dash parsing, where `--` is translated into
 72    `–`, and `---` is translated into `—`
 73*   Generic fractions, where anything that looks like a fraction is
 74    translated into suitable HTML (instead of just a few special
 75    cases).  For example, `4/5` becomes
 76    `<sup>4</sup>&frasl;<sub>5</sub>`, which renders as
 77    <sup>4</sup>&frasl;<sub>5</sub>.
 78
 79
 80LaTeX Output
 81------------
 82
 83A rudimentary LaTeX rendering backend is also included. To see an
 84example of its usage, see `main.go`:
 85
 86It renders some basic documents, but is only experimental at this
 87point. In particular, it does not do any inline escaping, so input
 88that happens to look like LaTeX code will be passed through without
 89modification.
 90
 91
 92Todo
 93----
 94
 95*   More unit testing
 96*   Code cleanup
 97*   Better code documentation
 98*   Markdown pretty-printer output engine
 99
100
101License
102-------
103
104Blackfriday is distributed under the Simplified BSD License:
105
106> Copyright © 2011 Russ Ross. All rights reserved.
107> 
108> Redistribution and use in source and binary forms, with or without modification, are
109> permitted provided that the following conditions are met:
110> 
111>    1. Redistributions of source code must retain the above copyright notice, this list of
112>       conditions and the following disclaimer.
113> 
114>    2. Redistributions in binary form must reproduce the above copyright notice, this list
115>       of conditions and the following disclaimer in the documentation and/or other materials
116>       provided with the distribution.
117> 
118> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER ``AS IS'' AND ANY EXPRESS OR IMPLIED
119> WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
120> FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> OR
121> CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
122> CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
123> SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
124> ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
125> NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
126> ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
127> 
128> The views and conclusions contained in the software and documentation are those of the
129> authors and should not be interpreted as representing official policies, either expressed
130> or implied, of the copyright holder.
131
132
133   [1]: http://daringfireball.net/projects/markdown/ "Markdown"
134   [2]: http://golang.org/ "Go Language"
135   [3]: http://github.com/tanoku/upskirt "Upskirt"