blackfriday

Blackfriday: a markdown processor for Go

5,423

598

5,423

218

View on GitHub

Top Related Projects

goldmark

3,563

:trophy: A markdown parser written in Go. Easy to extend, standard(CommonMark) compliant, well structured.

markdown

1,371

markdown parser and HTML renderer for Go

commonmark.js

1,436

CommonMark parser and renderer in JavaScript

marked

32,981

A markdown parser and compiler. Built for speed.

showdown

14,258

A bidirectional Markdown to HTML to Markdown converter written in Javascript

Quick Overview

Blackfriday is a Markdown processor implemented in Go. It is fast, safe, and produces HTML that is largely compatible with the output of standard Markdown processors. The library is designed to be extensible and customizable, making it suitable for a wide range of applications.

Pros

High performance and efficiency
Extensive feature set, including tables, fenced code blocks, and autolinks
Customizable through various options and extensions
Well-maintained and actively developed

Cons

Some deviations from the CommonMark specification
Limited support for advanced Markdown features like task lists
Occasional inconsistencies in parsing edge cases
Steeper learning curve compared to simpler Markdown libraries

Code Examples

Basic Markdown to HTML conversion:

import "github.com/russross/blackfriday/v2"

markdown := []byte("# Hello, World!\n\nThis is a **bold** statement.")
html := blackfriday.Run(markdown)
fmt.Println(string(html))

Using custom options:

import "github.com/russross/blackfriday/v2"

markdown := []byte("# Hello\n\nThis is a [link](https://example.com)")
html := blackfriday.Run(markdown, blackfriday.WithExtensions(blackfriday.CommonExtensions))
fmt.Println(string(html))

Creating a custom renderer:

import (
    "github.com/russross/blackfriday/v2"
    "bytes"
)

type customRenderer struct {
    blackfriday.Renderer
}

func (r *customRenderer) RenderNode(w io.Writer, node *blackfriday.Node, entering bool) blackfriday.WalkStatus {
    if node.Type == blackfriday.Heading && entering {
        fmt.Fprintf(w, "<h%d style=\"color: blue;\">", node.Level)
        return blackfriday.GoToNext
    }
    return r.Renderer.RenderNode(w, node, entering)
}

markdown := []byte("# Blue Heading\n\nNormal paragraph")
renderer := &customRenderer{blackfriday.NewHTMLRenderer(blackfriday.HTMLRendererParameters{})}
html := blackfriday.Run(markdown, blackfriday.WithRenderer(renderer))
fmt.Println(string(html))

Getting Started

To use Blackfriday in your Go project, first install it:

go get github.com/russross/blackfriday/v2

Then, import and use it in your code:

import "github.com/russross/blackfriday/v2"

func main() {
    markdown := []byte("# Hello, Blackfriday!\n\nThis is a simple example.")
    html := blackfriday.Run(markdown)
    fmt.Println(string(html))
}

This will convert the Markdown input to HTML output. You can customize the behavior by passing additional options to the Run function.

Competitor Comparisons

goldmark

3,563

:trophy: A markdown parser written in Go. Easy to extend, standard(CommonMark) compliant, well structured.

Pros of Goldmark

Faster parsing and rendering performance
More compliant with CommonMark specification
Extensible architecture allowing for custom extensions

Cons of Goldmark

Newer project with potentially less community support
May lack some features present in Blackfriday

Code Comparison

Blackfriday:

import "github.com/russross/blackfriday/v2"

output := blackfriday.Run(input)

Goldmark:

import "github.com/yuin/goldmark"

var markdown goldmark.Markdown
var buf bytes.Buffer
if err := markdown.Convert(input, &buf); err != nil {
    panic(err)
}

Both Goldmark and Blackfriday are popular Markdown parsers for Go. Goldmark offers improved performance and better CommonMark compliance, making it a strong choice for newer projects. However, Blackfriday has been around longer and may have more extensive community support.

The code comparison shows that Goldmark requires slightly more setup but offers more flexibility in its usage. Blackfriday's API is simpler for basic use cases.

When choosing between the two, consider factors such as performance requirements, CommonMark compliance needs, and the desire for extensibility in your project.

markdown

1,371

markdown parser and HTML renderer for Go

Pros of markdown

More actively maintained with frequent updates
Better support for CommonMark specification
Offers a wider range of extension options

Cons of markdown

Slightly slower performance in some benchmarks
Less widespread adoption compared to blackfriday
May require more configuration for advanced features

Code Comparison

markdown:

md := goldmark.New(
    goldmark.WithExtensions(extension.GFM),
    goldmark.WithParserOptions(
        parser.WithAutoHeadingID(),
    ),
    goldmark.WithRendererOptions(
        html.WithHardWraps(),
        html.WithXHTML(),
    ),
)

blackfriday:

output := blackfriday.Run(input,
    blackfriday.WithExtensions(blackfriday.CommonExtensions),
    blackfriday.WithRenderer(blackfriday.NewHTMLRenderer(blackfriday.HTMLRendererParameters{
        Flags: blackfriday.CommonHTMLFlags,
    })),
)

Both libraries offer similar functionality for parsing and rendering Markdown, but markdown (gomarkdown) provides more granular control over extensions and rendering options. blackfriday's API is slightly more concise, which may be preferable for simpler use cases.

commonmark.js

1,436

CommonMark parser and renderer in JavaScript

Pros of commonmark.js

Written in JavaScript, making it ideal for web-based applications and Node.js environments
Strictly adheres to the CommonMark specification, ensuring consistent parsing across platforms
Provides a live demo and extensive documentation for easy implementation

Cons of commonmark.js

May have slower performance compared to Blackfriday, which is written in Go
Limited feature set beyond the CommonMark specification, whereas Blackfriday offers additional extensions

Code Comparison

commonmark.js:

var reader = new commonmark.Parser();
var writer = new commonmark.HtmlRenderer();
var parsed = reader.parse("Hello *world*");
var result = writer.render(parsed);

Blackfriday:

markdown := blackfriday.Run([]byte("Hello *world*"))

While commonmark.js requires separate parsing and rendering steps, Blackfriday offers a more streamlined approach with a single function call. However, this simplicity may come at the cost of flexibility in some cases.

Both libraries are well-maintained and widely used in their respective ecosystems. The choice between them often depends on the specific project requirements, such as the programming language used, performance needs, and desired Markdown feature set.

marked

32,981

A markdown parser and compiler. Built for speed.

Pros of marked

Written in JavaScript, making it ideal for Node.js and browser environments
Extensive customization options and plugin system
Faster parsing speed for most common use cases

Cons of marked

Less comprehensive CommonMark compliance
May require additional setup for advanced features
Limited built-in security features compared to Blackfriday

Code Comparison

marked:

import { marked } from 'marked';

const html = marked.parse('# Heading\n\nParagraph text');
console.log(html);

Blackfriday:

import (
    "github.com/russross/blackfriday/v2"
)

markdown := []byte("# Heading\n\nParagraph text")
html := blackfriday.Run(markdown)
fmt.Println(string(html))

Both libraries offer straightforward APIs for converting Markdown to HTML, but marked provides a more JavaScript-friendly interface, while Blackfriday is designed for Go applications. marked's extensive configuration options allow for greater flexibility, whereas Blackfriday focuses on providing a robust, secure implementation out of the box.

showdown

14,258

A bidirectional Markdown to HTML to Markdown converter written in Javascript

Pros of Showdown

Written in JavaScript, making it ideal for browser-based applications
Extensive configuration options for customizing output
Active community with frequent updates and contributions

Cons of Showdown

Generally slower performance compared to Blackfriday
Less comprehensive CommonMark compliance
Larger file size, which may impact load times in web applications

Code Comparison

Blackfriday (Go):

import "github.com/russross/blackfriday/v2"

markdown := []byte("# Hello, World!")
html := blackfriday.Run(markdown)

Showdown (JavaScript):

var showdown = require('showdown');
var converter = new showdown.Converter();
var html = converter.makeHtml('# Hello, World!');

Both libraries provide simple APIs for converting Markdown to HTML, but Blackfriday's approach is more straightforward with a single function call. Showdown requires creating a converter instance before processing the Markdown.

Blackfriday is generally faster and more memory-efficient, making it suitable for server-side applications. Showdown's JavaScript implementation allows for easy integration in client-side web applications and offers more customization options.

While both libraries support standard Markdown syntax, Blackfriday has better CommonMark compliance. Showdown provides more flexibility in terms of extension support and configuration options.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Blackfriday

Blackfriday is a Markdown processor implemented in Go. It is paranoid about its input (so you can safely feed it user-supplied data), it is fast, it supports common extensions (tables, smart punctuation substitutions, etc.), and it is safe for all utf-8 (unicode) input.

HTML output is currently supported, along with Smartypants extensions.

It started as a translation from C of Sundown.

Installation

Blackfriday is compatible with modern Go releases in module mode. With Go installed:

go get github.com/russross/blackfriday

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

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

It is go get-able in module mode at github.com/russross/blackfriday/v2.

Version 2 offers a number of improvements over v1:

Cleaned up API
A separate call to Parse, 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 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://pkg.go.dev/github.com/russross/blackfriday.

Usage

v1

For basic usage, it is as simple as getting your input into a byte slice and calling:

output := blackfriday.MarkdownBasic(input)

This renders it with no extensions enabled. To get a more useful 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:

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:

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.

Here's an example of simple usage of Blackfriday together with Bluemonday:

import (
    "github.com/microcosm-cc/bluemonday"
    "github.com/russross/blackfriday"
)

// ...
unsafe := blackfriday.Run(input)
html := bluemonday.UGCPolicy().SanitizeBytes(unsafe)

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 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:

go get github.com/russross/blackfriday-tool

This is a simple command-line tool that allows you to process a markdown file using a standalone program. You can also browse the source directly on github if you are just looking for some example code:

https://github.com/russross/blackfriday-tool

Note that if you have not already done so, installing blackfriday-tool will be sufficient to download and install blackfriday in addition to the tool itself. The tool binary will be 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://pkg.go.dev/github.com/russross/blackfriday#hdr-Sanitized_Anchor_Names.

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. It can be useful for clients that want a small package and don't need full functionality of blackfriday.

Features

All features of Sundown are supported, including:

Compatibility. The Markdown v1.0.3 test suite passes with the --tidy option. Without --tidy, the differences are mostly in whitespace and entity escaping, where blackfriday is more consistent and cleaner.
Common extensions, including table support, fenced code blocks, autolinks, strikethroughs, non-strict emphasis, etc.
Safety. Blackfriday is paranoid when parsing, making it safe to feed untrusted user input without fear of bad things happening. The test suite stress tests this and there are no known inputs that make it crash. If you find one, please let me know and send me the input that does it.

NOTE: "safety" in this context means runtime safety only. In order to protect yourself against JavaScript injection in untrusted content, see this example.
Fast processing. It is fast enough to render on-demand in most web applications without having to cache the output.
Thread safety. You can run multiple parsers in different goroutines without ill effect. There is no dependence on global shared state.
Minimal dependencies. Blackfriday only depends on standard library packages in Go. The source code is pretty self-contained, so it is easy to add to any project, including Google App Engine projects.
Standards compliant. Output successfully validates using the W3C validation tool for HTML 4.01 and XHTML 1.0 Transitional.

Extensions

In addition to the standard markdown syntax, this package implements the following extensions:

Intra-word emphasis supression. The _ character is commonly used inside words when discussing code, so having markdown interpret it as an emphasis command is usually the wrong thing. Blackfriday lets you treat all emphasis markers as normal characters when they occur inside a word.
Tables. Tables can be created by drawing them in the input using a simple syntax:
```
Name    | Age
--------|------
Bob     | 27
Alice   | 23
```
Fenced code blocks. In addition to the normal 4-space indentation to mark code blocks, you can explicitly mark them and supply a language (to make syntax highlighting simple). Just mark it like this:
```
```go
func getTrue() bool {
    return true
}
```
```
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.

To preserve classes of fenced code blocks while using the bluemonday HTML sanitizer, use the following policy:
```
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 term followed by a colon and the definition for that term.
```
Cat
: Fluffy animal everyone likes

Internet
: Vector of transmission for pictures of cats
```
Terms must be separated from the previous definition by a blank line.
Footnotes. A marker in the text that will become a superscript number; a footnote definition that will be placed in a list of footnotes at the 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 explicitly marked as links and turn them into links.
Strikethrough. Use two tildes (~~) to mark text that should be crossed out.
Hard line breaks. With this extension enabled (it is off by default in the MarkdownBasic and MarkdownCommon convenience functions), newlines in the input translate into line breaks in the output.
Smart quotes. Smartypants-style punctuation substitution is supported, turning normal double- and single-quote marks into curly quotes, etc.
LaTeX-style dash parsing is an additional option, where -- is translated into –, and --- is translated into —. This differs from most smartypants processors, which turn a single hyphen into an ndash and a double hyphen into an mdash.
Smart fractions, where anything that looks like a fraction is translated into suitable HTML (instead of just a few special cases like most smartypant processors). For example, 4/5 becomes <sup>4</sup>&frasl;<sub>5</sub>, which renders as ⁴⁄₅.

Other renderers

Blackfriday is structured to allow alternative rendering engines. Here are a few of note:

github_flavored_markdown: provides a GitHub Flavored Markdown renderer with fenced code block highlighting, clickable heading anchor links.

It's not customizable, and its goal is to produce HTML output equivalent to the GitHub Markdown API endpoint, except the rendering is performed locally.
markdownfmt: like gofmt, but for markdown.
LaTeX output: renders output as LaTeX.
bfchroma: provides convenience integration with the 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: provides a Confluence Wiki Markup renderer.
Blackfriday-Slack: converts markdown to slack message style

TODO

More unit testing
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.

License

Blackfriday is distributed under the Simplified BSD License

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot