README: make a definitive decision on v2 import path
This change makes it clear that the v2 import path is github.com/russross/blackfriday/v2, and updates various links accordingly. See https://github.com/russross/blackfriday/issues/587#issuecomment-703393820 for details. This change also converges the README for v1 and v2 to be consistent, as they've started to drift apart. (See PR #675 for the equivalent change to the README on v2 branch.) For #587. GitHub-Pull-Request: #674master v1.6.0
parent
abb995c466
commit
e96880f42b
81
README.md
81
README.md
|
@ -1,6 +1,6 @@
|
||||||
Blackfriday
|
Blackfriday
|
||||||
[![Build Status][BuildSVG]][BuildURL]
|
[![Build Status][BuildV2SVG]][BuildV2URL]
|
||||||
[![Godoc][GodocV2SVG]][GodocV2URL]
|
[![PkgGoDev][PkgGoDevV2SVG]][PkgGoDevV2URL]
|
||||||
===========
|
===========
|
||||||
|
|
||||||
Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It
|
Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It
|
||||||
|
@ -18,12 +18,21 @@ It started as a translation from C of [Sundown][3].
|
||||||
Installation
|
Installation
|
||||||
------------
|
------------
|
||||||
|
|
||||||
Blackfriday is compatible with any modern Go release. With Go and git installed:
|
Blackfriday is compatible with modern Go releases in module mode.
|
||||||
|
With Go installed:
|
||||||
|
|
||||||
go get -u gopkg.in/russross/blackfriday.v2
|
go get github.com/russross/blackfriday
|
||||||
|
|
||||||
will download, compile, and install the package into your `$GOPATH` directory
|
will resolve and add the package to the current development module,
|
||||||
hierarchy.
|
then build and install it. Alternatively, you can achieve the same
|
||||||
|
if you import it in a package:
|
||||||
|
|
||||||
|
import "github.com/russross/blackfriday"
|
||||||
|
|
||||||
|
and `go get` without parameters.
|
||||||
|
|
||||||
|
Old versions of Go and legacy GOPATH mode might work,
|
||||||
|
but no effort is made to keep them working.
|
||||||
|
|
||||||
|
|
||||||
Versions
|
Versions
|
||||||
|
@ -32,13 +41,9 @@ Versions
|
||||||
Currently maintained and recommended version of Blackfriday is `v2`. It's being
|
Currently maintained and recommended version of Blackfriday is `v2`. It's being
|
||||||
developed on its own branch: https://github.com/russross/blackfriday/tree/v2 and the
|
developed on its own branch: https://github.com/russross/blackfriday/tree/v2 and the
|
||||||
documentation is available at
|
documentation is available at
|
||||||
https://godoc.org/gopkg.in/russross/blackfriday.v2.
|
https://pkg.go.dev/github.com/russross/blackfriday/v2.
|
||||||
|
|
||||||
It is `go get`-able via [gopkg.in][6] at `gopkg.in/russross/blackfriday.v2`,
|
It is `go get`-able in module mode at `github.com/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:
|
Version 2 offers a number of improvements over v1:
|
||||||
|
|
||||||
|
@ -60,22 +65,7 @@ Potential drawbacks:
|
||||||
|
|
||||||
If you are still interested in the legacy `v1`, you can import it from
|
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
|
`github.com/russross/blackfriday`. Documentation for the legacy v1 can be found
|
||||||
here: https://godoc.org/github.com/russross/blackfriday
|
here: https://pkg.go.dev/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
|
Usage
|
||||||
|
@ -125,7 +115,7 @@ Here's an example of simple usage of Blackfriday together with Bluemonday:
|
||||||
```go
|
```go
|
||||||
import (
|
import (
|
||||||
"github.com/microcosm-cc/bluemonday"
|
"github.com/microcosm-cc/bluemonday"
|
||||||
"gopkg.in/russross/blackfriday.v2"
|
"github.com/russross/blackfriday"
|
||||||
)
|
)
|
||||||
|
|
||||||
// ...
|
// ...
|
||||||
|
@ -175,12 +165,12 @@ anchors for headings when `EXTENSION_AUTO_HEADER_IDS` is enabled. The
|
||||||
algorithm has a specification, so that other packages can create
|
algorithm has a specification, so that other packages can create
|
||||||
compatible anchor names and links to those anchors.
|
compatible anchor names and links to those anchors.
|
||||||
|
|
||||||
The specification is located at https://godoc.org/github.com/russross/blackfriday#hdr-Sanitized_Anchor_Names.
|
The specification is located at https://pkg.go.dev/github.com/russross/blackfriday#hdr-Sanitized_Anchor_Names.
|
||||||
|
|
||||||
[`SanitizedAnchorName`](https://godoc.org/github.com/russross/blackfriday#SanitizedAnchorName) exposes this functionality, and can be used to
|
[`SanitizedAnchorName`](https://pkg.go.dev/github.com/russross/blackfriday#SanitizedAnchorName) exposes this functionality, and can be used to
|
||||||
create compatible links to the anchor names generated by blackfriday.
|
create compatible links to the anchor names generated by blackfriday.
|
||||||
This algorithm is also implemented in a small standalone package at
|
This algorithm is also implemented in a small standalone package at
|
||||||
[`github.com/shurcooL/sanitized_anchor_name`](https://godoc.org/github.com/shurcooL/sanitized_anchor_name). It can be useful for clients
|
[`github.com/shurcooL/sanitized_anchor_name`](https://pkg.go.dev/github.com/shurcooL/sanitized_anchor_name). It can be useful for clients
|
||||||
that want a small package and don't need full functionality of blackfriday.
|
that want a small package and don't need full functionality of blackfriday.
|
||||||
|
|
||||||
|
|
||||||
|
@ -250,7 +240,7 @@ implements the following extensions:
|
||||||
and supply a language (to make syntax highlighting simple). Just
|
and supply a language (to make syntax highlighting simple). Just
|
||||||
mark it like this:
|
mark it like this:
|
||||||
|
|
||||||
``` go
|
```go
|
||||||
func getTrue() bool {
|
func getTrue() bool {
|
||||||
return true
|
return true
|
||||||
}
|
}
|
||||||
|
@ -262,7 +252,7 @@ implements the following extensions:
|
||||||
To preserve classes of fenced code blocks while using the bluemonday
|
To preserve classes of fenced code blocks while using the bluemonday
|
||||||
HTML sanitizer, use the following policy:
|
HTML sanitizer, use the following policy:
|
||||||
|
|
||||||
``` go
|
```go
|
||||||
p := bluemonday.UGCPolicy()
|
p := bluemonday.UGCPolicy()
|
||||||
p.AllowAttrs("class").Matching(regexp.MustCompile("^language-[a-zA-Z0-9]+$")).OnElements("code")
|
p.AllowAttrs("class").Matching(regexp.MustCompile("^language-[a-zA-Z0-9]+$")).OnElements("code")
|
||||||
html := p.SanitizeBytes(unsafe)
|
html := p.SanitizeBytes(unsafe)
|
||||||
|
@ -273,7 +263,7 @@ implements the following extensions:
|
||||||
|
|
||||||
Cat
|
Cat
|
||||||
: Fluffy animal everyone likes
|
: Fluffy animal everyone likes
|
||||||
|
|
||||||
Internet
|
Internet
|
||||||
: Vector of transmission for pictures of cats
|
: Vector of transmission for pictures of cats
|
||||||
|
|
||||||
|
@ -284,7 +274,7 @@ implements the following extensions:
|
||||||
end of the document. A footnote looks like this:
|
end of the document. A footnote looks like this:
|
||||||
|
|
||||||
This is a footnote.[^1]
|
This is a footnote.[^1]
|
||||||
|
|
||||||
[^1]: the footnote text.
|
[^1]: the footnote text.
|
||||||
|
|
||||||
* **Autolinking**. Blackfriday can find URLs that have not been
|
* **Autolinking**. Blackfriday can find URLs that have not been
|
||||||
|
@ -321,7 +311,7 @@ Other renderers
|
||||||
Blackfriday is structured to allow alternative rendering engines. Here
|
Blackfriday is structured to allow alternative rendering engines. Here
|
||||||
are a few of note:
|
are a few of note:
|
||||||
|
|
||||||
* [github_flavored_markdown](https://godoc.org/github.com/shurcooL/github_flavored_markdown):
|
* [github_flavored_markdown](https://pkg.go.dev/github.com/shurcooL/github_flavored_markdown):
|
||||||
provides a GitHub Flavored Markdown renderer with fenced code block
|
provides a GitHub Flavored Markdown renderer with fenced code block
|
||||||
highlighting, clickable heading anchor links.
|
highlighting, clickable heading anchor links.
|
||||||
|
|
||||||
|
@ -341,6 +331,10 @@ are a few of note:
|
||||||
provides a drop-in renderer ready to use with Blackfriday, as well as
|
provides a drop-in renderer ready to use with Blackfriday, as well as
|
||||||
options and means for further customization.
|
options and means for further customization.
|
||||||
|
|
||||||
|
* [Blackfriday-Confluence](https://github.com/kentaro-m/blackfriday-confluence): provides a [Confluence Wiki Markup](https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html) renderer.
|
||||||
|
|
||||||
|
* [Blackfriday-Slack](https://github.com/karriereat/blackfriday-slack): converts markdown to slack message style
|
||||||
|
|
||||||
|
|
||||||
TODO
|
TODO
|
||||||
----
|
----
|
||||||
|
@ -361,13 +355,10 @@ License
|
||||||
[1]: https://daringfireball.net/projects/markdown/ "Markdown"
|
[1]: https://daringfireball.net/projects/markdown/ "Markdown"
|
||||||
[2]: https://golang.org/ "Go Language"
|
[2]: https://golang.org/ "Go Language"
|
||||||
[3]: https://github.com/vmg/sundown "Sundown"
|
[3]: https://github.com/vmg/sundown "Sundown"
|
||||||
[4]: https://godoc.org/gopkg.in/russross/blackfriday.v2#Parse "Parse func"
|
[4]: https://pkg.go.dev/github.com/russross/blackfriday/v2#Parse "Parse func"
|
||||||
[5]: https://github.com/microcosm-cc/bluemonday "Bluemonday"
|
[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
|
[BuildV2SVG]: https://travis-ci.org/russross/blackfriday.svg?branch=v2
|
||||||
[BuildURL]: https://travis-ci.org/russross/blackfriday
|
[BuildV2URL]: https://travis-ci.org/russross/blackfriday
|
||||||
[GodocV2SVG]: https://godoc.org/gopkg.in/russross/blackfriday.v2?status.svg
|
[PkgGoDevV2SVG]: https://pkg.go.dev/badge/github.com/russross/blackfriday/v2
|
||||||
[GodocV2URL]: https://godoc.org/gopkg.in/russross/blackfriday.v2
|
[PkgGoDevV2URL]: https://pkg.go.dev/github.com/russross/blackfriday/v2
|
||||||
|
|
Loading…
Reference in New Issue