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. This is
 50a statically-linked binary that can be copied to wherever you need
 51it without worrying about dependencies and library versions.
 52
 53
 54Features
 55--------
 56
 57All features of upskirt are supported, including:
 58
 59*   **Compatibility**. The Markdown v1.0.3 test suite passes with
 60    the `--tidy` option.  Without `--tidy`, the differences are
 61    mostly in whitespace and entity escaping, where blackfriday is
 62    more consistent and cleaner.
 63
 64*   **Common extensions**, including table support, fenced code
 65    blocks, autolinks, strikethroughs, non-strict emphasis, etc.
 66
 67*   **Safety**. Blackfriday is paranoid when parsing, making it safe
 68    to feed untrusted user input without fear of bad things
 69    happening. The test suite stress tests this and there are no
 70    known inputs that make it crash.  If you find one, please let me
 71    know and send me the input that does it.
 72
 73*   **Fast processing**. It is fast enough to render on-demand in
 74    most web applications without having to cache the output.
 75
 76*   **Thread safety**. You can run multiple parsers is different
 77    goroutines without ill effect. There is no dependence on global
 78    shared state.
 79
 80*   **Minimal dependencies**. Blackfriday only depends on standard
 81    library packages in Go. The source code is pretty
 82    self-contained, so it is easy to add to any project, including
 83    Google App Engine projects.
 84
 85*   **Standards compliant**. Output successfully validates using the
 86    W3C validation tool for HTML 4.01 and XHTML 1.0 Transitional.
 87
 88
 89Extensions
 90----------
 91
 92In addition to the standard markdown syntax, this package
 93implements the following extensions:
 94
 95*   **Intra-word emphasis supression**. The `_` character is
 96    commonly used inside words when discussing code, so having
 97    markdown interpret it as an emphasis command is usually the
 98    wrong thing. Blackfriday lets you treat all emphasis markers as
 99    normal characters when they occur inside a word.
100
101*   **Tables**. Tables can be created by drawing them in the input
102    using a simple syntax:
103
104        Name    | Age
105        --------|------
106        Bob     | 27
107        Alice   | 23
108
109*   **Fenced code blocks**. In addition to the normal 4-space
110    indentation to mark code blocks, you can explicitly mark them
111    and supply a language (to make syntax highlighting simple). Just
112    mark it like this:
113
114        ``` go
115        func getTrue() bool {
116            return true
117        }
118        ```
119
120    You can use 3 or more backticks to mark the beginning of the
121    block, and the same number to mark the end of the block.
122
123*   **Autolinking**. Blackfriday can find URLs that have not been
124    explicitly marked as links and turn them into links.
125
126*   **Strikethrough**. Use two tildes (`~~`) to mark text that
127    should be crossed out.
128
129*   **Hard line breaks**. With this extension enabled (it is off by
130    default in the `MarkdownBasic` and `MarkdownCommon` convenience
131    functions), newlines in the input translate into line breaks in
132    the output.
133
134*   **Smart quotes**. Smartypants-style punctuation substitution is
135    supported, turning normal double- and single-quote marks into
136    curly quotes, etc.
137
138*   **LaTeX-style dash parsing** is an additional option, where `--`
139    is translated into `–`, and `---` is translated into
140    `—`. This differs from most smartypants processors, which
141    turn a single hyphen into an ndash and a double hyphen into an
142    mdash.
143
144*   **Smart fractions**, where anything that looks like a fraction
145    is translated into suitable HTML (instead of just a few special
146    cases like most smartypant processors). For example, `4/5`
147    becomes `<sup>4</sup>&frasl;<sub>5</sub>`, which renders as
148    <sup>4</sup>&frasl;<sub>5</sub>.
149
150
151LaTeX Output
152------------
153
154A rudimentary LaTeX rendering backend is also included. To see an
155example of its usage, see `main.go`:
156
157It renders some basic documents, but is only experimental at this
158point. In particular, it does not do any inline escaping, so input
159that happens to look like LaTeX code will be passed through without
160modification.
161
162
163Todo
164----
165
166*   More unit testing
167*   Markdown pretty-printer output engine
168*   Improve unicode support. It does not understand all unicode
169    rules (about what constitutes a letter, a punctuation symbol,
170    etc.), so it may fail to detect word boundaries correctly in
171    some instances. It is safe on all utf-8 input.
172
173
174License
175-------
176
177Blackfriday is distributed under the Simplified BSD License:
178
179> Copyright © 2011 Russ Ross. All rights reserved.
180> 
181> Redistribution and use in source and binary forms, with or without modification, are
182> permitted provided that the following conditions are met:
183> 
184>    1. Redistributions of source code must retain the above copyright notice, this list of
185>       conditions and the following disclaimer.
186> 
187>    2. Redistributions in binary form must reproduce the above copyright notice, this list
188>       of conditions and the following disclaimer in the documentation and/or other materials
189>       provided with the distribution.
190> 
191> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER ``AS IS'' AND ANY EXPRESS OR IMPLIED
192> WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
193> FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> OR
194> CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
195> CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
196> SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
197> ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
198> NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
199> ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
200> 
201> The views and conclusions contained in the software and documentation are those of the
202> authors and should not be interpreted as representing official policies, either expressed
203> or implied, of the copyright holder.
204
205
206   [1]: http://daringfireball.net/projects/markdown/ "Markdown"
207   [2]: http://golang.org/ "Go Language"
208   [3]: http://github.com/tanoku/upskirt "Upskirt"