From 74be510331a2f1a189bb441a61e86cd6c9868e97 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vytautas=20=C5=A0altenis?= Date: Sat, 6 May 2017 19:52:33 +0300 Subject: [PATCH 1/6] Document V2 in master README --- README.md | 81 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 52 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 0d1ac9a..9913b3b 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -Blackfriday [![Build Status](https://travis-ci.org/russross/blackfriday.svg?branch=master)](https://travis-ci.org/russross/blackfriday) [![GoDoc](https://godoc.org/github.com/russross/blackfriday?status.svg)](https://godoc.org/github.com/russross/blackfriday) +Blackfriday [![Build Status][BuildSVG]][BuildURL] +[![Godoc][GodocV1SVG]][GodocV1URL] (V1) +[![Godoc][GodocV2SVG]][GodocV2URL] (V2) =========== Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It @@ -8,7 +10,7 @@ punctuation substitutions, etc.), and it is safe for all utf-8 (unicode) input. HTML output is currently supported, along with Smartypants -extensions. An experimental LaTeX output engine is also included. +extensions. It started as a translation from C of [Sundown][3]. @@ -16,23 +18,44 @@ It started as a translation from C of [Sundown][3]. Installation ------------ -Blackfriday is compatible with Go 1. If you are using an older -release of Go, consider using v1.1 of blackfriday, which was based -on the last stable release of Go prior to Go 1. You can find it as a -tagged commit on github. +Blackfriday is compatible with any modern Go release. With Go 1.7 and git +installed: -With Go 1 and git installed: - - go get github.com/russross/blackfriday + go get gopkg.in/russross/blackfriday.v2 will download, compile, and install the package into your `$GOPATH` directory hierarchy. Alternatively, you can achieve the same if you import it into a project: - import "github.com/russross/blackfriday" + import "gopkg.in/russross/blackfriday.v2" and `go get` without parameters. + +Versions +-------- + +Currently maintained and recommended version of Blackfriday is `v2`. It's being +developed on its own branch: https://github.com/russross/blackfriday/v2. You +should install and import it via [gopkg.in][6] at +`gopkg.in/russross/blackfriday.v2`. + +Version 2 offers a number of improvements over v1: + +* Cleaned up API +* A separate call to [`Parse`][4], which produces an abstract syntax tree for + the document +* Latest bug fixes +* Flexibility to easily add your own rendering extensions + +Potential drawbacks: + +* Our benchmarks show v2 to be slightly slower than v1. Currently in the + ballpark of around 15%. +* API breakage. If you can't afford modifying your code to adhere to the new API + and don't care too much about the new features, v2 is probably not for you. + + Usage ----- @@ -49,11 +72,10 @@ feature set, use this instead: ### Sanitize untrusted content Blackfriday itself does nothing to protect against malicious content. If you are -dealing with user-supplied markdown, we recommend running blackfriday's output -through HTML sanitizer such as -[Bluemonday](https://github.com/microcosm-cc/bluemonday). +dealing with user-supplied markdown, we recommend running Blackfriday's output +through HTML sanitizer such as [Bluemonday][5]. -Here's an example of simple usage of blackfriday together with bluemonday: +Here's an example of simple usage of Blackfriday together with Bluemonday: ``` go import ( @@ -69,7 +91,7 @@ html := bluemonday.UGCPolicy().SanitizeBytes(unsafe) ### Custom options If you want to customize the set of options, first get a renderer -(currently either the HTML or LaTeX output engines), then use it to +(currently only the HTML output engine), then use it to call the more general `Markdown` function. For examples, see the implementations of `MarkdownBasic` and `MarkdownCommon` in `markdown.go`. @@ -249,7 +271,7 @@ are a few of note: * [github_flavored_markdown](https://godoc.org/github.com/shurcooL/github_flavored_markdown): provides a GitHub Flavored Markdown renderer with fenced code block - highlighting, clickable header anchor links. + highlighting, clickable heading anchor links. It's not customizable, and its goal is to produce HTML output equivalent to the [GitHub Markdown API endpoint](https://developer.github.com/v3/markdown/#render-a-markdown-document-in-raw-mode), @@ -258,17 +280,8 @@ are a few of note: * [markdownfmt](https://github.com/shurcooL/markdownfmt): like gofmt, but for markdown. -* LaTeX output: renders output as LaTeX. This is currently part of the - main Blackfriday repository, but may be split into its own project - in the future. If you are interested in owning and maintaining the - LaTeX output component, please be in touch. - - It renders some basic documents, but is only experimental at this - point. In particular, it does not do any inline escaping, so input - that happens to look like LaTeX code will be passed through without - modification. - -* [Md2Vim](https://github.com/FooSoft/md2vim): transforms markdown files into vimdoc format. +* [LaTeX output](https://bitbucket.org/ambrevar/blackfriday-latex): + renders output as LaTeX. Todo @@ -287,6 +300,16 @@ License [Blackfriday is distributed under the Simplified BSD License](LICENSE.txt) - [1]: http://daringfireball.net/projects/markdown/ "Markdown" - [2]: http://golang.org/ "Go Language" + [1]: https://daringfireball.net/projects/markdown/ "Markdown" + [2]: https://golang.org/ "Go Language" [3]: https://github.com/vmg/sundown "Sundown" + [4]: https://godoc.org/gopkg.in/russross/blackfriday.v2#Parse "Parse func" + [5]: https://github.com/microcosm-cc/bluemonday "Bluemonday" + [6]: https://labix.org/gopkg.in "gopkg.in" + + [BuildSVG]: https://travis-ci.org/russross/blackfriday.svg?branch=master + [BuildURL]: https://travis-ci.org/russross/blackfriday + [GodocV1SVG]: https://godoc.org/github.com/russross/blackfriday?status.svg + [GodocV1URL]: https://godoc.org/github.com/russross/blackfriday + [GodocV2SVG]: https://godoc.org/gopkg.in/russross/blackfriday.v2?status.svg + [GodocV2URL]: https://godoc.org/gopkg.in/russross/blackfriday.v2 From ad4c953876ab2a00a455904e9f17c0144a93771e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vytautas=20=C5=A0altenis?= Date: Sat, 6 May 2017 19:59:25 +0300 Subject: [PATCH 2/6] Put row of badges above the top level heading --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 9913b3b..d9afcdf 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ -Blackfriday [![Build Status][BuildSVG]][BuildURL] +[![Build Status][BuildSVG]][BuildURL] [![Godoc][GodocV1SVG]][GodocV1URL] (V1) [![Godoc][GodocV2SVG]][GodocV2URL] (V2) + +Blackfriday =========== Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It From 52dd06192f86c8944e3e6b0b075580bd4a40b74e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vytautas=20=C5=A0altenis?= Date: Sat, 6 May 2017 20:18:15 +0300 Subject: [PATCH 3/6] Badges back to heading, reference v1 docs explicitly --- README.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index d9afcdf..075466e 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ -[![Build Status][BuildSVG]][BuildURL] -[![Godoc][GodocV1SVG]][GodocV1URL] (V1) -[![Godoc][GodocV2SVG]][GodocV2URL] (V2) - Blackfriday +[![Build Status][BuildSVG]][BuildURL] +[![Godoc][GodocV2SVG]][GodocV2URL] =========== Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It @@ -57,6 +55,9 @@ Potential drawbacks: * API breakage. If you can't afford modifying your code to adhere to the new API and don't care too much about the new features, v2 is probably not for you. +Documentation for the legacy v1 can be found here: +https://godoc.org/github.com/russross/blackfriday + Usage ----- @@ -311,7 +312,5 @@ License [BuildSVG]: https://travis-ci.org/russross/blackfriday.svg?branch=master [BuildURL]: https://travis-ci.org/russross/blackfriday - [GodocV1SVG]: https://godoc.org/github.com/russross/blackfriday?status.svg - [GodocV1URL]: https://godoc.org/github.com/russross/blackfriday [GodocV2SVG]: https://godoc.org/gopkg.in/russross/blackfriday.v2?status.svg [GodocV2URL]: https://godoc.org/gopkg.in/russross/blackfriday.v2 From a03b7ee643bdbb6346f21949a06a276bc9dd7e09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vytautas=20=C5=A0altenis?= Date: Sat, 6 May 2017 20:35:48 +0300 Subject: [PATCH 4/6] Add v1 import path, fix Bluemonday code snippet --- README.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 075466e..f947a61 100644 --- a/README.md +++ b/README.md @@ -21,15 +21,10 @@ Installation Blackfriday is compatible with any modern Go release. With Go 1.7 and git installed: - go get gopkg.in/russross/blackfriday.v2 + go get -u gopkg.in/russross/blackfriday.v2 will download, compile, and install the package into your `$GOPATH` -directory hierarchy. Alternatively, you can achieve the same if you -import it into a project: - - import "gopkg.in/russross/blackfriday.v2" - -and `go get` without parameters. +directory hierarchy. Versions @@ -55,8 +50,9 @@ Potential drawbacks: * API breakage. If you can't afford modifying your code to adhere to the new API and don't care too much about the new features, v2 is probably not for you. -Documentation for the legacy v1 can be found here: -https://godoc.org/github.com/russross/blackfriday +If you are still interested in the legacy `v1`, you can import it from +`github.com/russross/blackfriday`. Documentation for the legacy v1 can be found +here: https://godoc.org/github.com/russross/blackfriday Usage @@ -83,11 +79,11 @@ Here's an example of simple usage of Blackfriday together with Bluemonday: ``` go import ( "github.com/microcosm-cc/bluemonday" - "github.com/russross/blackfriday" + "gopkg.in/russross/blackfriday.v2" ) // ... -unsafe := blackfriday.MarkdownCommon(input) +unsafe := blackfriday.Markdown(input) html := bluemonday.UGCPolicy().SanitizeBytes(unsafe) ``` From 8ad7e40db09b1885469035bbf0345f11e7173883 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vytautas=20=C5=A0altenis?= Date: Fri, 11 Aug 2017 22:47:52 +0300 Subject: [PATCH 5/6] Update README with the latest changes from v2 --- README.md | 35 ++++++++++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f947a61..b73d35b 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,9 @@ Potential drawbacks: ballpark of around 15%. * API breakage. If you can't afford modifying your code to adhere to the new API and don't care too much about the new features, v2 is probably not for you. +* Several bug fixes are trailing behind and still need to be forward-ported to + v2. See issue [#348](https://github.com/russross/blackfriday/issues/348) for + tracking. If you are still interested in the legacy `v1`, you can import it from `github.com/russross/blackfriday`. Documentation for the legacy v1 can be found @@ -58,6 +61,8 @@ here: https://godoc.org/github.com/russross/blackfriday Usage ----- +### v1 + For basic usage, it is as simple as getting your input into a byte slice and calling: @@ -68,6 +73,23 @@ feature set, use this instead: output := blackfriday.MarkdownCommon(input) +### v2 + +For the most sensible markdown processing, it is as simple as getting your input +into a byte slice and calling: + +```go +output := blackfriday.Run(input) +``` + +Your input will be parsed and the output rendered with a set of most popular +extensions enabled. If you want the most basic feature set, corresponding with +the bare Markdown specification, use: + +```go +output := blackfriday.Run(input, blackfriday.WithNoExtensions()) +``` + ### Sanitize untrusted content Blackfriday itself does nothing to protect against malicious content. If you are @@ -76,18 +98,18 @@ through HTML sanitizer such as [Bluemonday][5]. Here's an example of simple usage of Blackfriday together with Bluemonday: -``` go +```go import ( "github.com/microcosm-cc/bluemonday" "gopkg.in/russross/blackfriday.v2" ) // ... -unsafe := blackfriday.Markdown(input) +unsafe := blackfriday.Run(input) html := bluemonday.UGCPolicy().SanitizeBytes(unsafe) ``` -### Custom options +### Custom options, v1 If you want to customize the set of options, first get a renderer (currently only the HTML output engine), then use it to @@ -95,6 +117,13 @@ call the more general `Markdown` function. For examples, see the implementations of `MarkdownBasic` and `MarkdownCommon` in `markdown.go`. +### Custom options, v2 + +If you want to customize the set of options, use `blackfriday.WithExtensions`, +`blackfriday.WithRenderer` and `blackfriday.WithRefOverride`. + +### `blackfriday-tool` + You can also check out `blackfriday-tool` for a more complete example of how to use it. Download and install it using: From 8249792ba80f9c15f6e21eb22b7d0acd884b930e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vytautas=20=C5=A0altenis?= Date: Sat, 7 Oct 2017 12:41:58 +0300 Subject: [PATCH 6/6] Update on import paths and dep transitive import FAQ Update usage and import paths with and without package management. Document the dep transitive dependency issue and how to get around it. Couple more minor edits. --- README.md | 42 ++++++++++++++++++++++++++++++++---------- 1 file changed, 32 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index b73d35b..ad9e5ee 100644 --- a/README.md +++ b/README.md @@ -18,22 +18,27 @@ It started as a translation from C of [Sundown][3]. Installation ------------ -Blackfriday is compatible with any modern Go release. With Go 1.7 and git -installed: +Blackfriday is compatible with any modern Go release. With Go and git installed: go get -u gopkg.in/russross/blackfriday.v2 -will download, compile, and install the package into your `$GOPATH` -directory hierarchy. +will download, compile, and install the package into your `$GOPATH` directory +hierarchy. Versions -------- Currently maintained and recommended version of Blackfriday is `v2`. It's being -developed on its own branch: https://github.com/russross/blackfriday/v2. You -should install and import it via [gopkg.in][6] at -`gopkg.in/russross/blackfriday.v2`. +developed on its own branch: https://github.com/russross/blackfriday/v2 and the +documentation is available at +https://godoc.org/gopkg.in/russross/blackfriday.v2. + +It is `go get`-able via via [gopkg.in][6] at `gopkg.in/russross/blackfriday.v2`, +but we highly recommend using package management tool like [dep][7] or +[Glide][8] and make use of semantic versioning. With package management you +should import `github.com/russross/blackfriday` and specify that you're using +version 2.0.0. Version 2 offers a number of improvements over v1: @@ -57,6 +62,21 @@ If you are still interested in the legacy `v1`, you can import it from `github.com/russross/blackfriday`. Documentation for the legacy v1 can be found here: https://godoc.org/github.com/russross/blackfriday +### Known issue with `dep` + +There is a known problem with using Blackfriday v1 _transitively_ and `dep`. +Currently `dep` prioritizes semver versions over anything else, and picks the +latest one, plus it does not apply a `[[constraint]]` specifier to transitively +pulled in packages. So if you're using something that uses Blackfriday v1, but +that something does not use `dep` yet, you will get Blackfriday v2 pulled in and +your first dependency will fail to build. + +There are couple of fixes for it, documented here: +https://github.com/golang/dep/blob/master/docs/FAQ.md#how-do-i-constrain-a-transitive-dependencys-version + +Meanwhile, `dep` team is working on a more general solution to the constraints +on transitive dependencies problem: https://github.com/golang/dep/issues/1124. + Usage ----- @@ -312,14 +332,14 @@ are a few of note: renders output as LaTeX. -Todo +TODO ---- * More unit testing -* Improve unicode support. It does not understand all unicode +* Improve Unicode support. It does not understand all Unicode rules (about what constitutes a letter, a punctuation symbol, etc.), so it may fail to detect word boundaries correctly in - some instances. It is safe on all utf-8 input. + some instances. It is safe on all UTF-8 input. License @@ -334,6 +354,8 @@ License [4]: https://godoc.org/gopkg.in/russross/blackfriday.v2#Parse "Parse func" [5]: https://github.com/microcosm-cc/bluemonday "Bluemonday" [6]: https://labix.org/gopkg.in "gopkg.in" + [7]: https://github.com/golang/dep/ "dep" + [8]: https://github.com/Masterminds/glide "Glide" [BuildSVG]: https://travis-ci.org/russross/blackfriday.svg?branch=master [BuildURL]: https://travis-ci.org/russross/blackfriday