github.com/insionng/yougam@v0.0.0-20170714101924-2bc18d833463/libraries/russross/blackfriday/README.md (about) 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 * **Definition lists**. A simple definition list is made of a single-line 173 term followed by a colon and the definition for that term. 174 175 Cat 176 : Fluffy animal everyone likes 177 178 Internet 179 : Vector of transmission for pictures of cats 180 181 Terms must be separated from the previous definition by a blank line. 182 183 * **Footnotes**. A marker in the text that will become a superscript number; 184 a footnote definition that will be placed in a list of footnotes at the 185 end of the document. A footnote looks like this: 186 187 This is a footnote.[^1] 188 189 [^1]: the footnote text. 190 191 * **Autolinking**. Blackfriday can find URLs that have not been 192 explicitly marked as links and turn them into links. 193 194 * **Strikethrough**. Use two tildes (`~~`) to mark text that 195 should be crossed out. 196 197 * **Hard line breaks**. With this extension enabled (it is off by 198 default in the `MarkdownBasic` and `MarkdownCommon` convenience 199 functions), newlines in the input translate into line breaks in 200 the output. 201 202 * **Smart quotes**. Smartypants-style punctuation substitution is 203 supported, turning normal double- and single-quote marks into 204 curly quotes, etc. 205 206 * **LaTeX-style dash parsing** is an additional option, where `--` 207 is translated into `–`, and `---` is translated into 208 `—`. This differs from most smartypants processors, which 209 turn a single hyphen into an ndash and a double hyphen into an 210 mdash. 211 212 * **Smart fractions**, where anything that looks like a fraction 213 is translated into suitable HTML (instead of just a few special 214 cases like most smartypant processors). For example, `4/5` 215 becomes `<sup>4</sup>⁄<sub>5</sub>`, which renders as 216 <sup>4</sup>⁄<sub>5</sub>. 217 218 219 Other renderers 220 --------------- 221 222 Blackfriday is structured to allow alternative rendering engines. Here 223 are a few of note: 224 225 * [github_flavored_markdown](https://godoc.org/github.com/shurcooL/github_flavored_markdown): 226 provides a GitHub Flavored Markdown renderer with fenced code block 227 highlighting, clickable header anchor links. 228 229 It's not customizable, and its goal is to produce HTML output 230 equivalent to the [GitHub Markdown API endpoint](https://developer.github.com/v3/markdown/#render-a-markdown-document-in-raw-mode), 231 except the rendering is performed locally. 232 233 * [markdownfmt](https://github.com/shurcooL/markdownfmt): like gofmt, 234 but for markdown. 235 236 * LaTeX output: renders output as LaTeX. This is currently part of the 237 main Blackfriday repository, but may be split into its own project 238 in the future. If you are interested in owning and maintaining the 239 LaTeX output component, please be in touch. 240 241 It renders some basic documents, but is only experimental at this 242 point. In particular, it does not do any inline escaping, so input 243 that happens to look like LaTeX code will be passed through without 244 modification. 245 246 * [Md2Vim](https://github.com/FooSoft/md2vim): transforms markdown files into vimdoc format. 247 248 249 Todo 250 ---- 251 252 * More unit testing 253 * Improve unicode support. It does not understand all unicode 254 rules (about what constitutes a letter, a punctuation symbol, 255 etc.), so it may fail to detect word boundaries correctly in 256 some instances. It is safe on all utf-8 input. 257 258 259 License 260 ------- 261 262 [Blackfriday is distributed under the Simplified BSD License](LICENSE.txt) 263 264 265 [1]: http://daringfireball.net/projects/markdown/ "Markdown" 266 [2]: http://golang.org/ "Go Language" 267 [3]: https://github.com/vmg/sundown "Sundown"