danog/blackfriday
1
0
Fork 0
mirror of https://github.com/danog/blackfriday.git synced 2024-11-30 04:29:13 +01:00
Code Issues Projects Releases Wiki Activity

v2/README: make a definitive decision on v2 import path

Browse Source 
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.

For #587.

GitHub-Pull-Request: #675
This commit is contained in:
Dmitri Shuralyov 2020-10-26 23:47:54 -04:00 committed by GitHub
parent acedacffef
commit 4c9bf95126
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 51 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
README.md
View File

@ -1,4 +1,6 @@
Blackfriday [![Build Status](https://travis-ci.org/russross/blackfriday.svg?branch=master)](https://travis-ci.org/russross/blackfriday) Blackfriday
[![Build Status][BuildV2SVG]][BuildV2URL]
[![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
@ -16,19 +18,21 @@ It started as a translation from C of [Sundown][3].
Installation Installation
------------ ------------
Blackfriday is compatible with any modern Go release. With Go 1.7 and git Blackfriday is compatible with modern Go releases in module mode.
installed: With Go installed:
go get gopkg.in/russross/blackfriday.v2 go get github.com/russross/blackfriday/v2
will download, compile, and install the package into your `$GOPATH` will resolve and add the package to the current development module,
directory hierarchy. Alternatively, you can achieve the same if you then build and install it. Alternatively, you can achieve the same
import it into a project: if you import it in a package:
import "gopkg.in/russross/blackfriday.v2" import "github.com/russross/blackfriday/v2"
and `go get` without parameters. and `go get` without parameters.
Legacy GOPATH mode is unsupported.
Versions Versions
-------- --------
@ -36,13 +40,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 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:
@ -62,6 +62,11 @@ Potential drawbacks:
v2. See issue [#348](https://github.com/russross/blackfriday/issues/348) for v2. See issue [#348](https://github.com/russross/blackfriday/issues/348) for
tracking. 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
here: https://pkg.go.dev/github.com/russross/blackfriday.
Usage Usage
----- -----
@ -91,7 +96,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"
"github.com/russross/blackfriday" "github.com/russross/blackfriday/v2"
) )
// ... // ...
@ -116,7 +121,7 @@ markdown file using a standalone program. You can also browse the
source directly on github if you are just looking for some example source directly on github if you are just looking for some example
code: code:
* <http://github.com/russross/blackfriday-tool> * <https://github.com/russross/blackfriday-tool>
Note that if you have not already done so, installing Note that if you have not already done so, installing
`blackfriday-tool` will be sufficient to download and install `blackfriday-tool` will be sufficient to download and install
@ -133,12 +138,12 @@ anchors for headings when `AutoHeadingIDs` extension 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/gopkg.in/russross/blackfriday.v2#hdr-Sanitized_Anchor_Names. The specification is located at https://pkg.go.dev/github.com/russross/blackfriday/v2#hdr-Sanitized_Anchor_Names.
[`SanitizedAnchorName`](https://godoc.org/gopkg.in/russross/blackfriday.v2#SanitizedAnchorName) exposes this functionality, and can be used to [`SanitizedAnchorName`](https://pkg.go.dev/github.com/russross/blackfriday/v2#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.
@ -217,6 +222,15 @@ implements the following extensions:
You can use 3 or more backticks to mark the beginning of the You can use 3 or more backticks to mark the beginning of the
block, and the same number to mark the end of the block. block, and the same number to mark the end of the block.
To preserve classes of fenced code blocks while using the bluemonday
HTML sanitizer, use the following policy:
```go
p := bluemonday.UGCPolicy()
p.AllowAttrs("class").Matching(regexp.MustCompile("^language-[a-zA-Z0-9]+$")).OnElements("code")
html := p.SanitizeBytes(unsafe)
```
* **Definition lists**. A simple definition list is made of a single-line * **Definition lists**. A simple definition list is made of a single-line
term followed by a colon and the definition for that term. term followed by a colon and the definition for that term.
@ -268,7 +282,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.
@ -279,21 +293,28 @@ are a few of note:
* [markdownfmt](https://github.com/shurcooL/markdownfmt): like gofmt, * [markdownfmt](https://github.com/shurcooL/markdownfmt): like gofmt,
but for markdown. but for markdown.
* [LaTeX output](https://github.com/Ambrevar/Blackfriday-LaTeX): * [LaTeX output](https://gitlab.com/ambrevar/blackfriday-latex):
renders output as LaTeX. renders output as LaTeX.
* [bfchroma](https://github.com/Depado/bfchroma/): provides convenience
integration with the [Chroma](https://github.com/alecthomas/chroma) code
highlighting library. bfchroma is only compatible with v2 of Blackfriday and
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-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 * [Blackfriday-Slack](https://github.com/karriereat/blackfriday-slack): converts markdown to slack message style
Todo
TODO
---- ----
* More unit testing * 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, rules (about what constitutes a letter, a punctuation symbol,
etc.), so it may fail to detect word boundaries correctly in 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 License
@ -305,6 +326,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"
[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