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