Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README: make a definitive decision on v2 import path #674

Merged
merged 1 commit into from
Oct 27, 2020
Merged

README: make a definitive decision on v2 import path #674

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 37 additions & 46 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
Blackfriday
[![Build Status][BuildSVG]][BuildURL]
[![Godoc][GodocV2SVG]][GodocV2URL]
[![Build Status][BuildV2SVG]][BuildV2URL]
[![PkgGoDev][PkgGoDevV2SVG]][PkgGoDevV2URL]
===========

Blackfriday is a [Markdown][1] processor implemented in [Go][2]. It
Expand All @@ -18,12 +18,21 @@ It started as a translation from C of [Sundown][3].
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
hierarchy.
will resolve and add the package to the current development module,
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
Expand All @@ -32,13 +41,9 @@ Versions
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
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`,
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.
It is `go get`-able in module mode at `github.com/russross/blackfriday/v2`.

Version 2 offers a number of improvements over v1:

Expand All @@ -60,22 +65,7 @@ Potential drawbacks:

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.
here: https://pkg.go.dev/github.com/russross/blackfriday.


Usage
Expand Down Expand Up @@ -125,7 +115,7 @@ Here's an example of simple usage of Blackfriday together with Bluemonday:
```go
import (
"github.com/microcosm-cc/bluemonday"
"gopkg.in/russross/blackfriday.v2"
"github.com/russross/blackfriday"
)

// ...
Expand Down Expand Up @@ -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
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.
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.


Expand Down Expand Up @@ -250,7 +240,7 @@ implements the following extensions:
and supply a language (to make syntax highlighting simple). Just
mark it like this:

``` go
```go
func getTrue() bool {
return true
}
Expand All @@ -262,7 +252,7 @@ implements the following extensions:
To preserve classes of fenced code blocks while using the bluemonday
HTML sanitizer, use the following policy:

``` go
```go
p := bluemonday.UGCPolicy()
p.AllowAttrs("class").Matching(regexp.MustCompile("^language-[a-zA-Z0-9]+$")).OnElements("code")
html := p.SanitizeBytes(unsafe)
Expand All @@ -273,7 +263,7 @@ implements the following extensions:

Cat
: Fluffy animal everyone likes

Internet
: Vector of transmission for pictures of cats

Expand All @@ -284,7 +274,7 @@ implements the following extensions:
end of the document. A footnote looks like this:

This is a footnote.[^1]

[^1]: the footnote text.

* **Autolinking**. Blackfriday can find URLs that have not been
Expand Down Expand Up @@ -321,7 +311,7 @@ Other renderers
Blackfriday is structured to allow alternative rendering engines. Here
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
highlighting, clickable heading anchor links.

Expand All @@ -341,6 +331,10 @@ are a few of note:
provides a drop-in renderer ready to use with Blackfriday, as well as
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
----
Expand All @@ -361,13 +355,10 @@ License
[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"
[4]: https://pkg.go.dev/github.com/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
[GodocV2SVG]: https://godoc.org/gopkg.in/russross/blackfriday.v2?status.svg
[GodocV2URL]: https://godoc.org/gopkg.in/russross/blackfriday.v2

[BuildV2SVG]: https://travis-ci.org/russross/blackfriday.svg?branch=v2
[BuildV2URL]: https://travis-ci.org/russross/blackfriday
[PkgGoDevV2SVG]: https://pkg.go.dev/badge/github.com/russross/blackfriday/v2
[PkgGoDevV2URL]: https://pkg.go.dev/github.com/russross/blackfriday/v2