bfchroma

README

bfchroma

Integrating Chroma syntax highlighter as a Blackfriday renderer.

Install and prerequisites

This project requires and uses the v2 version of Blackfriday. After this issue I decided to rollback to the gopkg.in version so the lib can be go gettable.

go get -u github.com/Depado/bfchroma

Features

This renderer integrates chroma to highlight code with triple backtick notation. It will try to use the given language when available otherwise it will try to detect the language. If none of these two method works it will fallback to sane defaults.

Usage

bfchroma uses the functional options approach so you can customize the behavior of the renderer. It uses sane defaults when no option is passed so you can use the renderer simply by doing so :

html := bf.Run([]byte(md), bf.WithRenderer(bfchroma.NewRenderer()))

Options

• Style(s string)
  Define the style used by chroma for the rendering. The full list can be found here
• ChromaStyle(*chroma.Style)
  This option can be used to passe directly a *chroma.Style instead of the string representing the style as with the Style(string) option.
• WithoutAutodetect()
  By default when no language information is written in the code block, this renderer will try to auto-detect the used language. This option disables this behavior and will fallback to a sane default when no language information is avaiable.
• Extend(bf.Renderer)
  This option allows to define the base blackfriday that will be extended.
• ChromaOptions(...html.Option)
  This option allows you to pass Chroma's html options in the renderer. Such options can be found here. There is currently an issue with the html.WithClasses() option as it expects the CSS classes to be written separately. I'll come up with a fix later.

Option examples

Disabling language auto-detection and displaying line numbers

r := bfchroma.NewRenderer(
	bfchroma.WithoutAutodetect(),
	bfchroma.ChromaOptions(html.WithLineNumbers()),
)

Extend a blackfriday renderer

b := bf.NewHTMLRenderer(bf.HTMLRendererParameters{
	Flags: bf.CommonHTMLFlags,
})

r := bfchroma.NewRenderer(bfchroma.Extend(b))

Use a different style

r := bfchroma.NewRenderer(bfchroma.Style("dracula"))
// Or
r = bfchroma.NewRenderer(bfchroma.ChromaStyle(styles.Dracula))

Examples

package main

import (
	"fmt"

	"github.com/Depado/bfchroma"

	bf "gopkg.in/russross/blackfriday.v2"
)

var md = "This is some sample code.\n\n```go\n" +
	`func main() {
	fmt.Println("Hi")
}
` + "```"

func main() {
	html := bf.Run([]byte(md), bf.WithRenderer(bfchroma.NewRenderer()))
	fmt.Println(string(html))
}

Will output :

<p>This is some sample code.</p>
<pre style="color:#f8f8f2;background-color:#272822"><span style="color:#66d9ef">func</span> <span style="color:#a6e22e">main</span>() {
<span style="color:#a6e22e">fmt</span>.<span style="color:#a6e22e">Println</span>(<span style="color:#e6db74">&#34;Hi&#34;</span>)
}
</pre>

Real-life example

In smallblog I'm using bfchroma to render my articles. It's using a combination of both bfchroma's options and blackfriday extensions and flags.

package main

import (
	"github.com/Depado/bfchroma"
	"github.com/alecthomas/chroma/formatters/html"
	bf "github.com/russross/blackfriday"
)

// Defines the extensions that are used
var exts = bf.NoIntraEmphasis | bf.Tables | bf.FencedCode | bf.Autolink |
	bf.Strikethrough | bf.SpaceHeadings | bf.BackslashLineBreak |
	bf.DefinitionLists | bf.Footnotes

// Defines the HTML rendering flags that are used
var flags = bf.UseXHTML | bf.Smartypants | bf.SmartypantsFractions |
	bf.SmartypantsDashes | bf.SmartypantsLatexDashes | bf.TOC

// render will take a []byte input and will render it using a new renderer each
// time because reusing the same can mess with TOC and header IDs
func render(input []byte) []byte {
	return bf.Run(
		input,
		bf.WithRenderer(
			bfchroma.NewRenderer(
				bfchroma.WithoutAutodetect(),
				bfchroma.ChromaOptions(
					html.WithLineNumbers(),
				),
				bfchroma.Extend(
					bf.NewHTMLRenderer(bf.HTMLRendererParameters{
						Flags: flags,
					}),
				),
			),
		),
		bf.WithExtensions(exts),
	)
}

ToDo

• Allow the use of html.WithClasses()

Documentation

Overview

Package bfchroma provides an easy and extensible blackfriday renderer that uses the chroma syntax highlighter to render code blocks.

Index

• type Option
  • func ChromaOptions(options ...html.Option) Option
  • func ChromaStyle(s *chroma.Style) Option
  • func Extend(br bf.Renderer) Option
  • func Style(s string) Option
  • func WithoutAutodetect() Option
• type Renderer
  • func NewRenderer(options ...Option) *Renderer
  • func (r *Renderer) RenderFooter(w io.Writer, ast *bf.Node)
  • func (r *Renderer) RenderHeader(w io.Writer, ast *bf.Node)
  • func (r *Renderer) RenderNode(w io.Writer, node *bf.Node, entering bool) bf.WalkStatus
  • func (r *Renderer) RenderWithChroma(w io.Writer, text []byte, data bf.CodeBlockData) error

Examples

• ChromaOptions
• ChromaStyle
• Extend
• NewRenderer
• Style
• WithoutAutodetect

Types

type Option

type Option func(r *Renderer)

Option defines the functional option type

func ChromaOptions

func ChromaOptions(options ...html.Option) Option

ChromaOptions allows to pass Chroma html.Option such as Standalone() WithClasses(), ClassPrefix(prefix)...

Example

md := "```go\npackage main\n\nfunc main() {\n}\n```"

r := NewRenderer(ChromaOptions(html.WithLineNumbers()))

h := bf.Run([]byte(md), bf.WithRenderer(r))
fmt.Println(string(h))

func ChromaStyle

func ChromaStyle(s *chroma.Style) Option

ChromaStyle is an option to directly set the style of the renderer using a chroma style instead of a string

Example

md := "```go\npackage main\n\nfunc main() {\n}\n```"

r := NewRenderer(ChromaStyle(styles.GitHub))

h := bf.Run([]byte(md), bf.WithRenderer(r))
fmt.Println(string(h))

func Extend

func Extend(br bf.Renderer) Option

Extend allows to specify the blackfriday renderer which is extended

Example

md := "```go\npackage main\n\nfunc main() {\n}\n```"

b := bf.NewHTMLRenderer(bf.HTMLRendererParameters{
	Flags: bf.CommonHTMLFlags,
})
r := NewRenderer(Extend(b))

h := bf.Run([]byte(md), bf.WithRenderer(r))
fmt.Println(string(h))

func Style

func Style(s string) Option

Style is a function option allowing to set the style used by chroma Default : "monokai"

Example

md := "```go\npackage main\n\nfunc main() {\n}\n```"

r := NewRenderer(Style("github"))

h := bf.Run([]byte(md), bf.WithRenderer(r))
fmt.Println(string(h))

func WithoutAutodetect

func WithoutAutodetect() Option

WithoutAutodetect disables chroma's language detection when no codeblock extra information is given. It will fallback to a sane default instead of trying to detect the language.

Example

md := "```\npackage main\n\nfunc main() {\n}\n```"

r := NewRenderer(WithoutAutodetect())

h := bf.Run([]byte(md), bf.WithRenderer(r))
fmt.Println(string(h))

type Renderer

type Renderer struct {
	Base          bf.Renderer
	Autodetect    bool
	ChromaOptions []html.Option
	Style         *chroma.Style
	Formatter     *html.Formatter
}

Renderer is a custom Blackfriday renderer that uses the capabilities of chroma to highlight code with triple backtick notation

func NewRenderer

func NewRenderer(options ...Option) *Renderer

NewRenderer will return a new bfchroma renderer with sane defaults

Example

// Complex example on how to initialize the renderer
md := "```go\npackage main\n\nfunc main() {\n}\n```"

r := NewRenderer(
	Extend(bf.NewHTMLRenderer(bf.HTMLRendererParameters{
		Flags: bf.CommonHTMLFlags,
	})),
	WithoutAutodetect(),
	ChromaStyle(styles.GitHub),
	ChromaOptions(html.WithLineNumbers()),
)

h := bf.Run([]byte(md), bf.WithRenderer(r))
fmt.Println(string(h))

func (*Renderer) RenderFooter

func (r *Renderer) RenderFooter(w io.Writer, ast *bf.Node)

RenderFooter satisfies the Renderer interface

func (*Renderer) RenderHeader

func (r *Renderer) RenderHeader(w io.Writer, ast *bf.Node)

RenderHeader satisfies the Renderer interface

func (*Renderer) RenderNode

func (r *Renderer) RenderNode(w io.Writer, node *bf.Node, entering bool) bf.WalkStatus

RenderNode satisfies the Renderer interface

func (*Renderer) RenderWithChroma

func (r *Renderer) RenderWithChroma(w io.Writer, text []byte, data bf.CodeBlockData) error

RenderWithChroma will render the given text to the w io.Writer