|
|
|
@ -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][GodocV2SVG]][GodocV2URL]
|
|
|
|
|
===========
|
|
|
|
|
|
|
|
|
|
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,26 +18,71 @@ 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 and git installed:
|
|
|
|
|
|
|
|
|
|
With Go 1 and git 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 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"
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
* 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
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
and `go get` without parameters.
|
|
|
|
|
|
|
|
|
|
Usage
|
|
|
|
|
-----
|
|
|
|
|
|
|
|
|
|
### v1
|
|
|
|
|
|
|
|
|
|
For basic usage, it is as simple as getting your input into a byte
|
|
|
|
|
slice and calling:
|
|
|
|
|
|
|
|
|
@ -46,34 +93,57 @@ 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
|
|
|
|
|
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
|
|
|
|
|
```go
|
|
|
|
|
import (
|
|
|
|
|
"github.com/microcosm-cc/bluemonday"
|
|
|
|
|
"github.com/russross/blackfriday"
|
|
|
|
|
"gopkg.in/russross/blackfriday.v2"
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
// ...
|
|
|
|
|
unsafe := blackfriday.MarkdownCommon(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 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`.
|
|
|
|
|
|
|
|
|
|
### 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:
|
|
|
|
|
|
|
|
|
@ -93,6 +163,22 @@ installed in `$GOPATH/bin`. This is a statically-linked binary that
|
|
|
|
|
can be copied to wherever you need it without worrying about
|
|
|
|
|
dependencies and library versions.
|
|
|
|
|
|
|
|
|
|
### Sanitized anchor names
|
|
|
|
|
|
|
|
|
|
Blackfriday includes an algorithm for creating sanitized anchor names
|
|
|
|
|
corresponding to a given input text. This algorithm is used to create
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
[`SanitizedAnchorName`](https://godoc.org/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
|
|
|
|
|
that want a small package and don't need full functionality of blackfriday.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Features
|
|
|
|
|
--------
|
|
|
|
@ -233,7 +319,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),
|
|
|
|
@ -242,27 +328,18 @@ 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
|
|
|
|
|
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
|
|
|
|
@ -271,6 +348,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"
|
|
|
|
|
[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
|
|
|
|
|