highlighting

Documentation

Overview

https://github.com/yuin/goldmark-highlighting/tree/v2

MIT License

Copyright (c) 2019 Yusuke Inuzuka

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Index

• Variables
• func NewHTMLRenderer(opts ...Option) renderer.NodeRenderer
• func NewHighlighting(opts ...Option) goldmark.Extender
• type CodeBlockContext
• type CodeBlockOptions
• type Config
  • func NewConfig() Config
  • func (c *Config) SetOption(name renderer.OptionName, value interface{})
• type HTMLRenderer
  • func (r *HTMLRenderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer)
• type ImmutableAttributes
• type Option
  • func WithCSSWriter(w io.Writer) Option
  • func WithCodeBlockOptions(c CodeBlockOptions) Option
  • func WithCustomStyle(style *chroma.Style) Option
  • func WithFormatOptions(opts ...chromahtml.Option) Option
  • func WithGuessLanguage(b bool) Option
  • func WithHTMLOptions(opts ...html.Option) Option
  • func WithStyle(style string) Option
  • func WithWrapperRenderer(w WrapperRenderer) Option
• type WrapperRenderer

Variables

var Highlighting = &highlighting{
	options: []Option{},
}

Highlighting is a goldmark.Extender implementation.

Functions

func NewHTMLRenderer

func NewHTMLRenderer(opts ...Option) renderer.NodeRenderer

NewHTMLRenderer builds a new HTMLRenderer with given options and returns it.

func NewHighlighting

func NewHighlighting(opts ...Option) goldmark.Extender

NewHighlighting returns a new extension with given options.

Types

type CodeBlockContext

type CodeBlockContext interface {
	// Language returns (language, true) if specified, otherwise (nil, false).
	Language() ([]byte, bool)

	// Highlighted returns true if this code block can be highlighted, otherwise false.
	Highlighted() bool

	// Attributes return attributes of the code block.
	Attributes() ImmutableAttributes
}

CodeBlockContext holds contextual information of code highlighting.

type CodeBlockOptions

type CodeBlockOptions func(ctx CodeBlockContext) []chromahtml.Option

CodeBlockOptions creates Chroma options per code block.

type Config

type Config struct {
	html.Config

	// Style is a highlighting style.
	// Supported styles are defined under https://github.com/alecthomas/chroma/tree/master/formatters.
	Style string

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

	// If set, will try to guess language 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.
	GuessLanguage bool

	// FormatOptions is a option related to output formats.
	// See https://github.com/alecthomas/chroma#the-html-formatter for details.
	FormatOptions []chromahtml.Option

	// CSSWriter is an io.Writer that will be used as CSS data output buffer.
	// If WithClasses() is enabled, you can get CSS data corresponds to the style.
	CSSWriter io.Writer

	// CodeBlockOptions allows set Chroma options per code block.
	CodeBlockOptions CodeBlockOptions

	// WrapperRenderer allows you to change wrapper elements.
	WrapperRenderer WrapperRenderer
}

Config struct holds options for the extension.

func NewConfig

func NewConfig() Config

NewConfig returns a new Config with defaults.

func (*Config) SetOption

func (c *Config) SetOption(name renderer.OptionName, value interface{})

SetOption implements renderer.SetOptioner.

type HTMLRenderer

type HTMLRenderer struct {
	Config
}

HTMLRenderer struct is a renderer.NodeRenderer implementation for the extension.

func (*HTMLRenderer) RegisterFuncs

func (r *HTMLRenderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer)

RegisterFuncs implements NodeRenderer.RegisterFuncs.

type ImmutableAttributes

type ImmutableAttributes interface {
	// Get returns (value, true) if an attribute associated with given
	// name exists, otherwise (nil, false)
	Get(name []byte) (interface{}, bool)

	// GetString returns (value, true) if an attribute associated with given
	// name exists, otherwise (nil, false)
	GetString(name string) (interface{}, bool)

	// All returns all attributes.
	All() []ast.Attribute
}

ImmutableAttributes is a read-only interface for ast.Attributes.

type Option

type Option interface {
	renderer.Option
	// SetHighlightingOption sets given option to the extension.
	SetHighlightingOption(*Config)
}

Option interface is a functional option interface for the extension.

func WithCSSWriter

func WithCSSWriter(w io.Writer) Option

WithCSSWriter is a functional option that sets io.Writer for CSS data.

func WithCodeBlockOptions

func WithCodeBlockOptions(c CodeBlockOptions) Option

WithCodeBlockOptions is a functional option that sets CodeBlockOptions that allows setting Chroma options per code block.

func WithCustomStyle

func WithCustomStyle(style *chroma.Style) Option

WithStyle is a functional option that changes highlighting style.

func WithFormatOptions

func WithFormatOptions(opts ...chromahtml.Option) Option

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

func WithGuessLanguage

func WithGuessLanguage(b bool) Option

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

func WithHTMLOptions

func WithHTMLOptions(opts ...html.Option) Option

WithHTMLOptions is functional option that wraps goldmark HTMLRenderer options.

func WithStyle

func WithStyle(style string) Option

WithStyle is a functional option that changes highlighting style.

func WithWrapperRenderer

func WithWrapperRenderer(w WrapperRenderer) Option

WithWrapperRenderer is a functional option that sets WrapperRenderer that renders wrapper elements like div, pre, etc.

type WrapperRenderer

type WrapperRenderer func(w util.BufWriter, context CodeBlockContext, entering bool)

WrapperRenderer renders wrapper elements like div, pre, etc.