highlight

package highlight

import "go.abhg.dev/doc2go/internal/highlight"

Package highlight provides support to highlight source code blocks. It uses the Chroma library to do this work.

Source code blocks are represented as Code values, which are comprised of multiple [Span]s. Spans represent special rendering instructions, such as highlighting a region of code, or linking to another entity.

Index

• Variables
• type AnchorSpan
• type Code
• type ErrorSpan
• type Highlighter
  • func (h *Highlighter) Highlight(code *Code) string
  • func (h *Highlighter) WriteCSS(w io.Writer) error
• type Lexer
• type LinkSpan
• type Span
• type TextSpan
• type TokenIndex
  • func NewTokenIndex(src []byte, tokens []chroma.Token) *TokenIndex
  • func (ts *TokenIndex) Interval(start, end int) (tokens []chroma.Token, lead, trail []byte)
• type TokenSpan

Variables

var GoLexer = &chromaLexer{l: chroma.Coalesce(lexers.Go)}

GoLexer is a Lexer that recognizes Go.

var PlainStyle = chroma.MustNewStyle("plain", map[chroma.TokenType]string{
	chroma.Comment:    "#666666",
	chroma.PreWrapper: "bg:#eeeeee",
	chroma.Background: "bg:#eeeeee",
})

PlainStyle is a minimal syntax highlighting style for Chroma. It leaves most text as-is, and fades comments ever so slightly.

Types

type AnchorSpan

type AnchorSpan struct {
	Spans []Span
	ID    string
}

AnchorSpan renders as an addressable anchor point.

type Code

type Code struct {
	Spans []Span
}

Code is a code block comprised of multiple text nodes.

type ErrorSpan

type ErrorSpan struct {
	Msg string
	Err error
}

ErrorSpan is a special span that represents a failure operation.

This renders in HTML in a visible way to avoid failing silently.

type Highlighter

type Highlighter struct {
	// Style used for syntax highlighting of code.
	Style *chroma.Style

	// UseClasses specifies whether the highlighter
	// uses inline 'style' attributes for highlighting,
	// or classes, assumign use of an appropriate style sheet.
	UseClasses bool
	// contains filtered or unexported fields
}

Highlighter turns Code into HTML.

func (*Highlighter) Highlight

func (h *Highlighter) Highlight(code *Code) string

Highlight renders the given code block into HTML.

func (*Highlighter) WriteCSS

func (h *Highlighter) WriteCSS(w io.Writer) error

WriteCSS writes the style classes for this highlighter to writer. If this highlighter is not using classes, WriteCSS is a no-op.

type Lexer

type Lexer interface {
	Lex(src []byte) ([]chroma.Token, error)
}

Lexer analyzes source code and generates a stream of tokens.

type LinkSpan

type LinkSpan struct {
	Spans []Span
	Dest  string
}

LinkSpan renders as a link with a specific destination.

type Span

type Span interface {
	// contains filtered or unexported methods
}

Span is a part of a code block.

type TextSpan

type TextSpan struct {
	Text []byte
}

TextSpan is a span rendered as-is.

type TokenIndex

type TokenIndex struct {
	// contains filtered or unexported fields
}

TokenIndex is a searchable collection of tokens.

func NewTokenIndex

func NewTokenIndex(src []byte, tokens []chroma.Token) *TokenIndex

NewTokenIndex builds a token index given source code and its tokens.

func (*TokenIndex) Interval

func (ts *TokenIndex) Interval(start, end int) (tokens []chroma.Token, lead, trail []byte)

Interval returns a list of tokens that are in the range [start, end). If the token boundaries aren't exactly matching, intervals also returns the leading and trailing text, if any.

type TokenSpan

type TokenSpan struct {
	Tokens []chroma.Token
}

TokenSpan is a span of code that is highlighted with chroma.