|
| 1 | +Blackfriday [](https://travis-ci.org/russross/blackfriday) [](https://godoc.org/github.com/russross/blackfriday) |
| 2 | +=========== |
| 3 | + |
| 4 | +Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It |
| 5 | +is paranoid about its input (so you can safely feed it user-supplied |
| 6 | +data), it is fast, it supports common extensions (tables, smart |
| 7 | +punctuation substitutions, etc.), and it is safe for all utf-8 |
| 8 | +(unicode) input. |
| 9 | + |
| 10 | +HTML output is currently supported, along with Smartypants |
| 11 | +extensions. An experimental LaTeX output engine is also included. |
| 12 | + |
| 13 | +It started as a translation from C of [Sundown][3]. |
| 14 | + |
| 15 | + |
| 16 | +Installation |
| 17 | +------------ |
| 18 | + |
| 19 | +Blackfriday is compatible with Go 1. If you are using an older |
| 20 | +release of Go, consider using v1.1 of blackfriday, which was based |
| 21 | +on the last stable release of Go prior to Go 1. You can find it as a |
| 22 | +tagged commit on github. |
| 23 | + |
| 24 | +With Go 1 and git installed: |
| 25 | + |
| 26 | + go get github.com/russross/blackfriday |
| 27 | + |
| 28 | +will download, compile, and install the package into your `$GOPATH` |
| 29 | +directory hierarchy. Alternatively, you can achieve the same if you |
| 30 | +import it into a project: |
| 31 | + |
| 32 | + import "github.com/russross/blackfriday" |
| 33 | + |
| 34 | +and `go get` without parameters. |
| 35 | + |
| 36 | +Usage |
| 37 | +----- |
| 38 | + |
| 39 | +For basic usage, it is as simple as getting your input into a byte |
| 40 | +slice and calling: |
| 41 | + |
| 42 | + output := blackfriday.MarkdownBasic(input) |
| 43 | + |
| 44 | +This renders it with no extensions enabled. To get a more useful |
| 45 | +feature set, use this instead: |
| 46 | + |
| 47 | + output := blackfriday.MarkdownCommon(input) |
| 48 | + |
| 49 | +### Sanitize untrusted content |
| 50 | + |
| 51 | +Blackfriday itself does nothing to protect against malicious content. If you are |
| 52 | +dealing with user-supplied markdown, we recommend running blackfriday's output |
| 53 | +through HTML sanitizer such as |
| 54 | +[Bluemonday](https://github.com/microcosm-cc/bluemonday). |
| 55 | + |
| 56 | +Here's an example of simple usage of blackfriday together with bluemonday: |
| 57 | + |
| 58 | +``` go |
| 59 | +import ( |
| 60 | + "github.com/microcosm-cc/bluemonday" |
| 61 | + "github.com/russross/blackfriday" |
| 62 | +) |
| 63 | + |
| 64 | +// ... |
| 65 | +unsafe := blackfriday.MarkdownCommon(input) |
| 66 | +html := bluemonday.UGCPolicy().SanitizeBytes(unsafe) |
| 67 | +``` |
| 68 | + |
| 69 | +### Custom options |
| 70 | + |
| 71 | +If you want to customize the set of options, first get a renderer |
| 72 | +(currently either the HTML or LaTeX output engines), then use it to |
| 73 | +call the more general `Markdown` function. For examples, see the |
| 74 | +implementations of `MarkdownBasic` and `MarkdownCommon` in |
| 75 | +`markdown.go`. |
| 76 | + |
| 77 | +You can also check out `blackfriday-tool` for a more complete example |
| 78 | +of how to use it. Download and install it using: |
| 79 | + |
| 80 | + go get github.com/russross/blackfriday-tool |
| 81 | + |
| 82 | +This is a simple command-line tool that allows you to process a |
| 83 | +markdown file using a standalone program. You can also browse the |
| 84 | +source directly on github if you are just looking for some example |
| 85 | +code: |
| 86 | + |
| 87 | +* <http://github.com/russross/blackfriday-tool> |
| 88 | + |
| 89 | +Note that if you have not already done so, installing |
| 90 | +`blackfriday-tool` will be sufficient to download and install |
| 91 | +blackfriday in addition to the tool itself. The tool binary will be |
| 92 | +installed in `$GOPATH/bin`. This is a statically-linked binary that |
| 93 | +can be copied to wherever you need it without worrying about |
| 94 | +dependencies and library versions. |
| 95 | + |
| 96 | + |
| 97 | +Features |
| 98 | +-------- |
| 99 | + |
| 100 | +All features of Sundown are supported, including: |
| 101 | + |
| 102 | +* **Compatibility**. The Markdown v1.0.3 test suite passes with |
| 103 | + the `--tidy` option. Without `--tidy`, the differences are |
| 104 | + mostly in whitespace and entity escaping, where blackfriday is |
| 105 | + more consistent and cleaner. |
| 106 | + |
| 107 | +* **Common extensions**, including table support, fenced code |
| 108 | + blocks, autolinks, strikethroughs, non-strict emphasis, etc. |
| 109 | + |
| 110 | +* **Safety**. Blackfriday is paranoid when parsing, making it safe |
| 111 | + to feed untrusted user input without fear of bad things |
| 112 | + happening. The test suite stress tests this and there are no |
| 113 | + known inputs that make it crash. If you find one, please let me |
| 114 | + know and send me the input that does it. |
| 115 | + |
| 116 | + NOTE: "safety" in this context means *runtime safety only*. In order to |
| 117 | + protect yourself against JavaScript injection in untrusted content, see |
| 118 | + [this example](https://github.com/russross/blackfriday#sanitize-untrusted-content). |
| 119 | + |
| 120 | +* **Fast processing**. It is fast enough to render on-demand in |
| 121 | + most web applications without having to cache the output. |
| 122 | + |
| 123 | +* **Thread safety**. You can run multiple parsers in different |
| 124 | + goroutines without ill effect. There is no dependence on global |
| 125 | + shared state. |
| 126 | + |
| 127 | +* **Minimal dependencies**. Blackfriday only depends on standard |
| 128 | + library packages in Go. The source code is pretty |
| 129 | + self-contained, so it is easy to add to any project, including |
| 130 | + Google App Engine projects. |
| 131 | + |
| 132 | +* **Standards compliant**. Output successfully validates using the |
| 133 | + W3C validation tool for HTML 4.01 and XHTML 1.0 Transitional. |
| 134 | + |
| 135 | + |
| 136 | +Extensions |
| 137 | +---------- |
| 138 | + |
| 139 | +In addition to the standard markdown syntax, this package |
| 140 | +implements the following extensions: |
| 141 | + |
| 142 | +* **Intra-word emphasis supression**. The `_` character is |
| 143 | + commonly used inside words when discussing code, so having |
| 144 | + markdown interpret it as an emphasis command is usually the |
| 145 | + wrong thing. Blackfriday lets you treat all emphasis markers as |
| 146 | + normal characters when they occur inside a word. |
| 147 | + |
| 148 | +* **Tables**. Tables can be created by drawing them in the input |
| 149 | + using a simple syntax: |
| 150 | + |
| 151 | + ``` |
| 152 | + Name | Age |
| 153 | + --------|------ |
| 154 | + Bob | 27 |
| 155 | + Alice | 23 |
| 156 | + ``` |
| 157 | +
|
| 158 | +* **Fenced code blocks**. In addition to the normal 4-space |
| 159 | + indentation to mark code blocks, you can explicitly mark them |
| 160 | + and supply a language (to make syntax highlighting simple). Just |
| 161 | + mark it like this: |
| 162 | +
|
| 163 | + ``` go |
| 164 | + func getTrue() bool { |
| 165 | + return true |
| 166 | + } |
| 167 | + ``` |
| 168 | +
|
| 169 | + You can use 3 or more backticks to mark the beginning of the |
| 170 | + block, and the same number to mark the end of the block. |
| 171 | +
|
| 172 | + To preserve classes of fenced code blocks while using the bluemonday |
| 173 | + HTML sanitizer, use the following policy: |
| 174 | +
|
| 175 | + ``` go |
| 176 | + p := bluemonday.UGCPolicy() |
| 177 | + p.AllowAttrs("class").Matching(regexp.MustCompile("^language-[a-zA-Z0-9]+$")).OnElements("code") |
| 178 | + html := p.SanitizeBytes(unsafe) |
| 179 | + ``` |
| 180 | +
|
| 181 | +* **Definition lists**. A simple definition list is made of a single-line |
| 182 | + term followed by a colon and the definition for that term. |
| 183 | +
|
| 184 | + Cat |
| 185 | + : Fluffy animal everyone likes |
| 186 | + |
| 187 | + Internet |
| 188 | + : Vector of transmission for pictures of cats |
| 189 | +
|
| 190 | + Terms must be separated from the previous definition by a blank line. |
| 191 | +
|
| 192 | +* **Footnotes**. A marker in the text that will become a superscript number; |
| 193 | + a footnote definition that will be placed in a list of footnotes at the |
| 194 | + end of the document. A footnote looks like this: |
| 195 | +
|
| 196 | + This is a footnote.[^1] |
| 197 | + |
| 198 | + [^1]: the footnote text. |
| 199 | +
|
| 200 | +* **Autolinking**. Blackfriday can find URLs that have not been |
| 201 | + explicitly marked as links and turn them into links. |
| 202 | +
|
| 203 | +* **Strikethrough**. Use two tildes (`~~`) to mark text that |
| 204 | + should be crossed out. |
| 205 | +
|
| 206 | +* **Hard line breaks**. With this extension enabled (it is off by |
| 207 | + default in the `MarkdownBasic` and `MarkdownCommon` convenience |
| 208 | + functions), newlines in the input translate into line breaks in |
| 209 | + the output. |
| 210 | +
|
| 211 | +* **Smart quotes**. Smartypants-style punctuation substitution is |
| 212 | + supported, turning normal double- and single-quote marks into |
| 213 | + curly quotes, etc. |
| 214 | +
|
| 215 | +* **LaTeX-style dash parsing** is an additional option, where `--` |
| 216 | + is translated into `–`, and `---` is translated into |
| 217 | + `—`. This differs from most smartypants processors, which |
| 218 | + turn a single hyphen into an ndash and a double hyphen into an |
| 219 | + mdash. |
| 220 | +
|
| 221 | +* **Smart fractions**, where anything that looks like a fraction |
| 222 | + is translated into suitable HTML (instead of just a few special |
| 223 | + cases like most smartypant processors). For example, `4/5` |
| 224 | + becomes `<sup>4</sup>⁄<sub>5</sub>`, which renders as |
| 225 | + <sup>4</sup>⁄<sub>5</sub>. |
| 226 | +
|
| 227 | +
|
| 228 | +Other renderers |
| 229 | +--------------- |
| 230 | +
|
| 231 | +Blackfriday is structured to allow alternative rendering engines. Here |
| 232 | +are a few of note: |
| 233 | +
|
| 234 | +* [github_flavored_markdown](https://godoc.org/github.com/shurcooL/github_flavored_markdown): |
| 235 | + provides a GitHub Flavored Markdown renderer with fenced code block |
| 236 | + highlighting, clickable header anchor links. |
| 237 | +
|
| 238 | + It's not customizable, and its goal is to produce HTML output |
| 239 | + equivalent to the [GitHub Markdown API endpoint](https://developer.github.com/v3/markdown/#render-a-markdown-document-in-raw-mode), |
| 240 | + except the rendering is performed locally. |
| 241 | +
|
| 242 | +* [markdownfmt](https://github.com/shurcooL/markdownfmt): like gofmt, |
| 243 | + but for markdown. |
| 244 | +
|
| 245 | +* LaTeX output: renders output as LaTeX. This is currently part of the |
| 246 | + main Blackfriday repository, but may be split into its own project |
| 247 | + in the future. If you are interested in owning and maintaining the |
| 248 | + LaTeX output component, please be in touch. |
| 249 | +
|
| 250 | + It renders some basic documents, but is only experimental at this |
| 251 | + point. In particular, it does not do any inline escaping, so input |
| 252 | + that happens to look like LaTeX code will be passed through without |
| 253 | + modification. |
| 254 | + |
| 255 | +* [Md2Vim](https://github.com/FooSoft/md2vim): transforms markdown files into vimdoc format. |
| 256 | +
|
| 257 | +
|
| 258 | +Todo |
| 259 | +---- |
| 260 | +
|
| 261 | +* More unit testing |
| 262 | +* Improve unicode support. It does not understand all unicode |
| 263 | + rules (about what constitutes a letter, a punctuation symbol, |
| 264 | + etc.), so it may fail to detect word boundaries correctly in |
| 265 | + some instances. It is safe on all utf-8 input. |
| 266 | +
|
| 267 | +
|
| 268 | +License |
| 269 | +------- |
| 270 | +
|
| 271 | +[Blackfriday is distributed under the Simplified BSD License](LICENSE.txt) |
| 272 | +
|
| 273 | +
|
| 274 | + [1]: http://daringfireball.net/projects/markdown/ "Markdown" |
| 275 | + [2]: http://golang.org/ "Go Language" |
| 276 | + [3]: https://github.com/vmg/sundown "Sundown" |
0 commit comments