README.md (view raw)
1[](https://travis-ci.org/russross/blackfriday)
2
3Blackfriday
4===========
5
6Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It
7is paranoid about its input (so you can safely feed it user-supplied
8data), it is fast, it supports common extensions (tables, smart
9punctuation substitutions, etc.), and it is safe for all utf-8
10(unicode) input.
11
12HTML output is currently supported, along with Smartypants
13extensions. An experimental LaTeX output engine is also included.
14
15It started as a translation from C of [upskirt][3].
16
17
18Installation
19------------
20
21Blackfriday is compatible with Go 1. If you are using an older
22release of Go, consider using v1.1 of blackfriday, which was based
23on the last stable release of Go prior to Go 1. You can find it as a
24tagged commit on github.
25
26With Go 1 and git installed:
27
28 go get github.com/russross/blackfriday
29
30will download, compile, and install the package into your `$GOPATH`
31directory hierarchy. Alternatively, you can achieve the same if you
32import it into a project:
33
34 import "github.com/russross/blackfriday"
35
36and `go get` without parameters.
37
38Usage
39-----
40
41For basic usage, it is as simple as getting your input into a byte
42slice and calling:
43
44 output := blackfriday.MarkdownBasic(input)
45
46This renders it with no extensions enabled. To get a more useful
47feature set, use this instead:
48
49 output := blackfriday.MarkdownCommon(input)
50
51If you want to customize the set of options, first get a renderer
52(currently either the HTML or LaTeX output engines), then use it to
53call the more general `Markdown` function. For examples, see the
54implementations of `MarkdownBasic` and `MarkdownCommon` in
55`markdown.go`.
56
57You can also check out `blackfriday-tool` for a more complete example
58of how to use it. Download and install it using:
59
60 go get github.com/russross/blackfriday-tool
61
62This is a simple command-line tool that allows you to process a
63markdown file using a standalone program. You can also browse the
64source directly on github if you are just looking for some example
65code:
66
67* <http://github.com/russross/blackfriday-tool>
68
69Note that if you have not already done so, installing
70`blackfriday-tool` will be sufficient to download and install
71blackfriday in addition to the tool itself. The tool binary will be
72installed in `$GOPATH/bin`. This is a statically-linked binary that
73can be copied to wherever you need it without worrying about
74dependencies and library versions.
75
76
77Features
78--------
79
80All features of upskirt are supported, including:
81
82* **Compatibility**. The Markdown v1.0.3 test suite passes with
83 the `--tidy` option. Without `--tidy`, the differences are
84 mostly in whitespace and entity escaping, where blackfriday is
85 more consistent and cleaner.
86
87* **Common extensions**, including table support, fenced code
88 blocks, autolinks, strikethroughs, non-strict emphasis, etc.
89
90* **Safety**. Blackfriday is paranoid when parsing, making it safe
91 to feed untrusted user input without fear of bad things
92 happening. The test suite stress tests this and there are no
93 known inputs that make it crash. If you find one, please let me
94 know and send me the input that does it.
95
96 NOTE: "safety" in this context means *runtime safety only*. It is
97 not bullet proof against JavaScript injections, though we're working
98 on it (https://github.com/russross/blackfriday/issues/11 tracks the
99 progress).
100
101* **Fast processing**. It is fast enough to render on-demand in
102 most web applications without having to cache the output.
103
104* **Thread safety**. You can run multiple parsers in different
105 goroutines without ill effect. There is no dependence on global
106 shared state.
107
108* **Minimal dependencies**. Blackfriday only depends on standard
109 library packages in Go. The source code is pretty
110 self-contained, so it is easy to add to any project, including
111 Google App Engine projects.
112
113* **Standards compliant**. Output successfully validates using the
114 W3C validation tool for HTML 4.01 and XHTML 1.0 Transitional.
115
116
117Extensions
118----------
119
120In addition to the standard markdown syntax, this package
121implements the following extensions:
122
123* **Intra-word emphasis supression**. The `_` character is
124 commonly used inside words when discussing code, so having
125 markdown interpret it as an emphasis command is usually the
126 wrong thing. Blackfriday lets you treat all emphasis markers as
127 normal characters when they occur inside a word.
128
129* **Tables**. Tables can be created by drawing them in the input
130 using a simple syntax:
131
132 ```
133 Name | Age
134 --------|------
135 Bob | 27
136 Alice | 23
137 ```
138
139* **Fenced code blocks**. In addition to the normal 4-space
140 indentation to mark code blocks, you can explicitly mark them
141 and supply a language (to make syntax highlighting simple). Just
142 mark it like this:
143
144 ``` go
145 func getTrue() bool {
146 return true
147 }
148 ```
149
150 You can use 3 or more backticks to mark the beginning of the
151 block, and the same number to mark the end of the block.
152
153* **Autolinking**. Blackfriday can find URLs that have not been
154 explicitly marked as links and turn them into links.
155
156* **Strikethrough**. Use two tildes (`~~`) to mark text that
157 should be crossed out.
158
159* **Hard line breaks**. With this extension enabled (it is off by
160 default in the `MarkdownBasic` and `MarkdownCommon` convenience
161 functions), newlines in the input translate into line breaks in
162 the output.
163
164* **Smart quotes**. Smartypants-style punctuation substitution is
165 supported, turning normal double- and single-quote marks into
166 curly quotes, etc.
167
168* **LaTeX-style dash parsing** is an additional option, where `--`
169 is translated into `–`, and `---` is translated into
170 `—`. This differs from most smartypants processors, which
171 turn a single hyphen into an ndash and a double hyphen into an
172 mdash.
173
174* **Smart fractions**, where anything that looks like a fraction
175 is translated into suitable HTML (instead of just a few special
176 cases like most smartypant processors). For example, `4/5`
177 becomes `<sup>4</sup>⁄<sub>5</sub>`, which renders as
178 <sup>4</sup>⁄<sub>5</sub>.
179
180
181Other renderers
182---------------
183
184Blackfriday is structured to allow alternative rendering engines. Here
185are a few of note:
186
187* [github_flavored_markdown](https://godoc.org/github.com/shurcooL/go/github_flavored_markdown):
188 provides a GitHub Flavored Markdown renderer with fenced code block
189 highlighting, clickable header anchor links.
190
191 It's not customizable, and its goal is to produce HTML output
192 equivalent to the [GitHub Markdown API endpoint](https://developer.github.com/v3/markdown/#render-a-markdown-document-in-raw-mode),
193 except the rendering is performed locally.
194
195* [markdownfmt](https://github.com/shurcooL/markdownfmt): like gofmt,
196 but for markdown.
197
198* LaTeX output: renders output as LaTeX. This is currently part of the
199 main Blackfriday repository, but may be split into its own project
200 in the future. If you are interested in owning and maintaining the
201 LaTeX output component, please be in touch.
202
203 It renders some basic documents, but is only experimental at this
204 point. In particular, it does not do any inline escaping, so input
205 that happens to look like LaTeX code will be passed through without
206 modification.
207
208
209Todo
210----
211
212* More unit testing
213* Markdown pretty-printer output engine
214* Improve unicode support. It does not understand all unicode
215 rules (about what constitutes a letter, a punctuation symbol,
216 etc.), so it may fail to detect word boundaries correctly in
217 some instances. It is safe on all utf-8 input.
218
219
220License
221-------
222
223Blackfriday is distributed under the Simplified BSD License:
224
225> Copyright © 2011 Russ Ross
226> All rights reserved.
227>
228> Redistribution and use in source and binary forms, with or without
229> modification, are permitted provided that the following conditions
230> are met:
231>
232> 1. Redistributions of source code must retain the above copyright
233> notice, this list of conditions and the following disclaimer.
234>
235> 2. Redistributions in binary form must reproduce the above
236> copyright notice, this list of conditions and the following
237> disclaimer in the documentation and/or other materials provided with
238> the distribution.
239>
240> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
241> "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
242> LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
243> FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
244> COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
245> INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
246> BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
247> LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
248> CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
249> LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
250> ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
251> POSSIBILITY OF SUCH DAMAGE.
252
253
254 [1]: http://daringfireball.net/projects/markdown/ "Markdown"
255 [2]: http://golang.org/ "Go Language"
256 [3]: http://github.com/tanoku/upskirt "Upskirt"