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 `$GOPATH`
 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 `$GOPATH/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    NOTE: "safety" in this context means *runtime safety only*. It is
 93    not bullet proof against JavaScript injections, though we're working
 94    on it (https://github.com/russross/blackfriday/issues/11 tracks the
 95    progress).
 96
 97*   **Fast processing**. It is fast enough to render on-demand in
 98    most web applications without having to cache the output.
 99
100*   **Thread safety**. You can run multiple parsers in different
101    goroutines without ill effect. There is no dependence on global
102    shared state.
103
104*   **Minimal dependencies**. Blackfriday only depends on standard
105    library packages in Go. The source code is pretty
106    self-contained, so it is easy to add to any project, including
107    Google App Engine projects.
108
109*   **Standards compliant**. Output successfully validates using the
110    W3C validation tool for HTML 4.01 and XHTML 1.0 Transitional.
111
112
113Extensions
114----------
115
116In addition to the standard markdown syntax, this package
117implements the following extensions:
118
119*   **Intra-word emphasis supression**. The `_` character is
120    commonly used inside words when discussing code, so having
121    markdown interpret it as an emphasis command is usually the
122    wrong thing. Blackfriday lets you treat all emphasis markers as
123    normal characters when they occur inside a word.
124
125*   **Tables**. Tables can be created by drawing them in the input
126    using a simple syntax:
127
128    ```
129    Name    | Age
130    --------|------
131    Bob     | 27
132    Alice   | 23
133    ```
134
135*   **Fenced code blocks**. In addition to the normal 4-space
136    indentation to mark code blocks, you can explicitly mark them
137    and supply a language (to make syntax highlighting simple). Just
138    mark it like this:
139
140        ``` go
141        func getTrue() bool {
142            return true
143        }
144        ```
145
146    You can use 3 or more backticks to mark the beginning of the
147    block, and the same number to mark the end of the block.
148
149*   **Autolinking**. Blackfriday can find URLs that have not been
150    explicitly marked as links and turn them into links.
151
152*   **Strikethrough**. Use two tildes (`~~`) to mark text that
153    should be crossed out.
154
155*   **Hard line breaks**. With this extension enabled (it is off by
156    default in the `MarkdownBasic` and `MarkdownCommon` convenience
157    functions), newlines in the input translate into line breaks in
158    the output.
159
160*   **Smart quotes**. Smartypants-style punctuation substitution is
161    supported, turning normal double- and single-quote marks into
162    curly quotes, etc.
163
164*   **LaTeX-style dash parsing** is an additional option, where `--`
165    is translated into `&ndash;`, and `---` is translated into
166    `&mdash;`. This differs from most smartypants processors, which
167    turn a single hyphen into an ndash and a double hyphen into an
168    mdash.
169
170*   **Smart fractions**, where anything that looks like a fraction
171    is translated into suitable HTML (instead of just a few special
172    cases like most smartypant processors). For example, `4/5`
173    becomes `<sup>4</sup>&frasl;<sub>5</sub>`, which renders as
174    <sup>4</sup>&frasl;<sub>5</sub>.
175
176
177LaTeX Output
178------------
179
180A rudimentary LaTeX rendering backend is also included. To see an
181example of its usage, see `main.go`:
182
183It renders some basic documents, but is only experimental at this
184point. In particular, it does not do any inline escaping, so input
185that happens to look like LaTeX code will be passed through without
186modification.
187
188
189Todo
190----
191
192*   More unit testing
193*   Markdown pretty-printer output engine
194*   Improve unicode support. It does not understand all unicode
195    rules (about what constitutes a letter, a punctuation symbol,
196    etc.), so it may fail to detect word boundaries correctly in
197    some instances. It is safe on all utf-8 input.
198
199
200License
201-------
202
203Blackfriday is distributed under the Simplified BSD License:
204
205> Copyright © 2011 Russ Ross
206> All rights reserved.
207> 
208> Redistribution and use in source and binary forms, with or without
209> modification, are permitted provided that the following conditions
210> are met:
211> 
212> 1.  Redistributions of source code must retain the above copyright
213>     notice, this list of conditions and the following disclaimer.
214> 
215> 2.  Redistributions in binary form must reproduce the above
216>     copyright notice, this list of conditions and the following
217>     disclaimer in the documentation and/or other materials provided with
218>     the distribution.
219> 
220> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
221> "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
222> LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
223> FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
224> COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
225> INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
226> BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
227> LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
228> CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
229> LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
230> ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
231> POSSIBILITY OF SUCH DAMAGE.
232
233
234   [1]: http://daringfireball.net/projects/markdown/ "Markdown"
235   [2]: http://golang.org/ "Go Language"
236   [3]: http://github.com/tanoku/upskirt "Upskirt"