highlighting

package module
v3.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 16 Imported by: 1

README

goldmark-highlighting

goldmark-highlighting is an extension for the goldmark that adds syntax-highlighting to the fenced code blocks.

goldmark-highlighting uses chroma as a syntax highlighter.

Compatibility

  • goldmark-highlighting/v3 uses goldmark/v2, chroma/v3, json/v2
    • minimum Go version: 1.27
    • you can build goldmark-highlighting/v3 with goldmark_v1_attribute build tag to use goldmark/v1 compatible attribute parsing.
  • For goldmark/v1, please use goldmark-highlighting/v2.

Breaking changes from v2 to v3

  • WithCSSWriter(w io.Writer) is removed. Use WithCSSMap(rc renderer.Context, m map[string]string) instead.
  • WithFormatOptions(opts ...chromahtml.Option) is renamed to WithFormatterOptions(opts ...chromahtml.Option).
  • WithWrapperRenderer(w WrapperRenderer) Option is removed. Use goldmark/v2 NodeRendererDecorator instead.

Installation

go get github.com/yuin/goldmark-highlighting/v3

Usage

package main

import (
	"bytes"
	"fmt"

	"github.com/yuin/goldmark/v2"

	chromahtml "github.com/alecthomas/chroma/v3/formatters/html"
	highlighting "github.com/yuin/goldmark-highlighting/v3"
)

func main() {
	mdsrc := `
		Title
		=======
		` + "```go {hl_lines=2}" + `
		func main() {
		    fmt.Println("ok")
		}
		` + "```" + `
	`

	// Simple usage
	p := parser.New(parser.WithExtensions(highlighting.NewParser()))
	r := html.New(html.WithExtensions(highlighting.NewHTMLRenderer()))
	node := p.Parse([]byte(mdsrc))
	var buf bytes.Buffer
	if err := r.Render([]byte(mdsrc), &buf, node); err != nil {
		panic(err)
	}
	title := buf.String()
	fmt.Print(title)

	// Custom configuration
	r := html.New(html.WithExtensions(
		highlighting.NewHTMLRenderer(
			highlighting.WithStyle("monokai"),
			highlighting.WithFormatterOptions(
				chromahtml.WithClasses(true),
				chromahtml.WithLineNumbers(false),
			),
			highlighting.WithCodeBlockFormatterOptions(
				func(n *ast.CodeBlock, source []byte, _ renderer.Context) []chromahtml.Option {
					if language, ok := n.Language(source); ok && language == "go" {
						return []chromahtml.Option{
							chromahtml.WithLineNumbers(true),
						}
					}
					return nil
				}),
		),
	),
	)
	var buf2 bytes.Buffer
	if err := r.Render([]byte(mdsrc), &buf2, node); err != nil {
		panic(err)
	}
	title2 := buf2.String()
	fmt.Print(title2)
}

Use goldmark-highlighting with other code block extensions

This extension is implemented using NodeRendererDecorator. You can skip this extension and use other code block extensions by using the WithExcludeLanguages or WithExcludeFunc options.

r := html.New(html.WithExtensions(highlighting.NewHTMLRenderer(
	highlighting.WithExcludeLanguages("mermaid"), // exclude mermaid code blocks( to render mermaid code as diagrams)
)))

License

MIT

Author

Yusuke Inuzuka

Documentation

Overview

package highlighting is a extension for the goldmark(http://github.com/yuin/goldmark).

This extension adds syntax-highlighting to the fenced code blocks using chroma(https://github.com/alecthomas/chroma).

Index

Constants

This section is empty.

Variables

View Source
var HTMLRenderer = NewHTMLRenderer()

HTMLRenderer is a default html.Extension for highlighted fenced code blocks.

Deprecated: use NewHTMLRenderer instead.

View Source
var Parser = NewParser()

Parser is a default parser.Extension for highlighted fenced code blocks.

Deprecated: use NewParser instead.

Functions

func NewHTMLRenderer

func NewHTMLRenderer(opts ...HTMLRendererOption) html.Extension

NewHTMLRenderer returns a new html.Extension .

func NewParser

func NewParser() parser.Extension

NewParser returns a new parser.Extension for highlighted fenced code blocks.

func WithCSSMap

func WithCSSMap(rc renderer.Context, m map[string]string) renderer.Context

WithCssMap sets `map[string]string` reference for CSS data in the renderer.Context.

If `WithClasses()`(FormatterOption) is enabled, renderer will write CSS data corresponds to the style to the given map. Keys are style names, and values are CSS data.

Types

type ExcludeFunc added in v3.1.0

type ExcludeFunc func(n *ast.CodeBlock, source []byte, rc renderer.Context) bool

ExcludeFunc is a function type that can be used to exclude certain code blocks from being highlighted.

type HTMLRendererOption

type HTMLRendererOption func(*htmlRendererConfig)

HTMLRendererOption is a functional option for HTMLRenderer.

func WithCodeBlockFormatterOptions

func WithCodeBlockFormatterOptions(f func(*ast.CodeBlock, []byte,
	renderer.Context) []chromahtml.Option) HTMLRendererOption

WithCodeBlockFormatterOptions is a functional option that allows set Chroma options per code block.

func WithCustomStyle

func WithCustomStyle(style *chroma.Style) HTMLRendererOption

WithCustomStyle is a functional option that changes highlighting style.

Pass in a custom Chroma style. If this is not nil, the Style string will be ignored.

func WithExcludeFunc added in v3.1.0

func WithExcludeFunc(f ExcludeFunc) HTMLRendererOption

WithExcludeFunc is a functional option that sets a function to exclude certain code blocks from being highlighted.

func WithExcludeLanguages added in v3.1.0

func WithExcludeLanguages(langs ...string) HTMLRendererOption

WithExcludeLanguages is a functional option that sets a list of languages to exclude from being highlighted.

func WithFormatterOptions

func WithFormatterOptions(opts ...chromahtml.Option) HTMLRendererOption

WithFormatterOptions is a functional option that wraps chroma HTML formatter options.

See https://github.com/alecthomas/chroma#the-html-formatter for details.

func WithGuessLanguage

func WithGuessLanguage(b ...bool) HTMLRendererOption

WithGuessLanguage is a functional option that toggles language guessing if none provided.

If the guessing fails, we will fall back to a text lexer. Note that while Chroma's API supports language guessing, the implementation is not there yet, so you will currently always get the basic text lexer.

func WithStyle

func WithStyle(style string) HTMLRendererOption

WithStyle is a functional option that changes highlighting style.

Supported styles are defined under https://github.com/alecthomas/chroma/tree/master/formatters.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址