1Black Friday
  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.
 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.5x slower than upskirt.
 56    This is an ugly, direct translation from the C code, so
 57    the difference is unlikely to be related to differences in
 58    coding style. There is a lot of bounds checking that is
 59    duplicated (by user code for the application and again by code
 60    the compiler generates) and there is some additional memory
 61    management overhead, since I allocate and garbage collect
 62    buffers instead of explicitly managing them as upskirt does.
 63
 64*   Minimal dependencies. blackfriday only depends on standard
 65    library packages in Go. The source code is pretty
 66    self-contained, so it is easy to add to any project.
 67
 68
 69Extensions
 70----------
 71
 72In addition to the extensions offered by upskirt, this package
 73implements two additional Smartypants options:
 74
 75*   LaTeX-style dash parsing, where `--` is translated into
 76    `–`, and `---` is translated into `—`
 77*   Generic fractions, where anything that looks like a fraction
 78    is translated into suitable HTML (instead of just a few special
 79    cases). For example, `4/5` becomes `<sup>4</sup>&frasl;<sub>5</sub>`
 80
 81
 82LaTeX Output
 83------------
 84
 85A rudimentary LaTeX rendering backend is also included. To see an
 86example of its usage, comment out this link in `main.go`:
 87
 88    renderer := blackfriday.HtmlRenderer(html_flags)
 89
 90and uncomment this line:
 91
 92    renderer := blackfriday.LatexRenderer(0)
 93
 94It renders some basic documents, but is only experimental at this point.
 95
 96
 97Todo
 98----
 99
100*   Code cleanup
101*   Better code documentation
102*   Markdown pretty-printer output engine
103
104
105   [1]: http://daringfireball.net/projects/markdown/ "Markdown"
106   [2]: http://golang.org/ "Go Language"
107   [3]: http://github.com/tanoku/upskirt "Upskirt"