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*   **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 in 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    ```
124    Name    | Age
125    --------|------
126    Bob     | 27
127    Alice   | 23
128    ```
129
130*   **Fenced code blocks**. In addition to the normal 4-space
131    indentation to mark code blocks, you can explicitly mark them
132    and supply a language (to make syntax highlighting simple). Just
133    mark it like this:
134
135        ``` go
136        func getTrue() bool {
137            return true
138        }
139        ```
140
141    You can use 3 or more backticks to mark the beginning of the
142    block, and the same number to mark the end of the block.
143
144*   **Autolinking**. Blackfriday can find URLs that have not been
145    explicitly marked as links and turn them into links.
146
147*   **Strikethrough**. Use two tildes (`~~`) to mark text that
148    should be crossed out.
149
150*   **Hard line breaks**. With this extension enabled (it is off by
151    default in the `MarkdownBasic` and `MarkdownCommon` convenience
152    functions), newlines in the input translate into line breaks in
153    the output.
154
155*   **Smart quotes**. Smartypants-style punctuation substitution is
156    supported, turning normal double- and single-quote marks into
157    curly quotes, etc.
158
159*   **LaTeX-style dash parsing** is an additional option, where `--`
160    is translated into `&ndash;`, and `---` is translated into
161    `&mdash;`. This differs from most smartypants processors, which
162    turn a single hyphen into an ndash and a double hyphen into an
163    mdash.
164
165*   **Smart fractions**, where anything that looks like a fraction
166    is translated into suitable HTML (instead of just a few special
167    cases like most smartypant processors). For example, `4/5`
168    becomes `<sup>4</sup>&frasl;<sub>5</sub>`, which renders as
169    <sup>4</sup>&frasl;<sub>5</sub>.
170
171
172LaTeX Output
173------------
174
175A rudimentary LaTeX rendering backend is also included. To see an
176example of its usage, see `main.go`:
177
178It renders some basic documents, but is only experimental at this
179point. In particular, it does not do any inline escaping, so input
180that happens to look like LaTeX code will be passed through without
181modification.
182
183
184Todo
185----
186
187*   More unit testing
188*   Markdown pretty-printer output engine
189*   Improve unicode support. It does not understand all unicode
190    rules (about what constitutes a letter, a punctuation symbol,
191    etc.), so it may fail to detect word boundaries correctly in
192    some instances. It is safe on all utf-8 input.
193
194
195License
196-------
197
198Blackfriday is distributed under the Simplified BSD License:
199
200> Copyright © 2011 Russ Ross
201> All rights reserved.
202> 
203> Redistribution and use in source and binary forms, with or without
204> modification, are permitted provided that the following conditions
205> are met:
206> 
207> 1.  Redistributions of source code must retain the above copyright
208>     notice, this list of conditions and the following disclaimer.
209> 
210> 2.  Redistributions in binary form must reproduce the above
211>     copyright notice, this list of conditions and the following
212>     disclaimer in the documentation and/or other materials provided with
213>     the distribution.
214> 
215> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
216> "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
217> LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
218> FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
219> COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
220> INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
221> BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
222> LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
223> CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
224> LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
225> ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
226> POSSIBILITY OF SUCH DAMAGE.
227
228
229   [1]: http://daringfireball.net/projects/markdown/ "Markdown"
230   [2]: http://golang.org/ "Go Language"
231   [3]: http://github.com/tanoku/upskirt "Upskirt"