codeblocks

Documentation

Overview

Package codeblocks is the contract between whynot's Markdown compiler and code-block plugins, which change how fenced code blocks are shown. A Plugin says which languages it handles, and parses each such block's source into Content: Tokens, spans of the source classified for syntax coloring, or an Image, such as a rendered diagram.

Plugins are given to whynot.Parse with the whynot.WithCodeBlockPlugin option, in priority order. The first plugin that handles a block's language parses it. If it makes an Image, what the next plugin makes of the block is shown while the image loads, or if it fails.

Ready-made plugins are in subpackages: chromahighlight highlights code in every language the chroma library knows, and kroki turns Mermaid diagrams into images.

Writing a plugin

A plugin produces data; whynot turns it into the document and colors it. This one shows the comment lines of shell code blocks in the stylesheet's comment color:

type shellComments struct{}

func (shellComments) Handles(language string) bool {
	return language == "sh"
}

func (shellComments) Parse(language, code string) codeblocks.Content {
	var spans []codeblocks.Span
	for _, line := range strings.SplitAfter(code, "\n") {
		class := "" // the code block's own color
		if strings.HasPrefix(strings.TrimSpace(line), "#") {
			class = codeblocks.ClassComment
		}
		spans = append(spans, codeblocks.Span{Text: line, Class: class})
	}
	return codeblocks.Tokens{Spans: spans}
}

The spans must add up to the block's source exactly. A class is any string: a stylesheet colors the ones it knows, such as ClassComment, and shows the others in the code block's own color.

Index

• Constants
• type Content
• type Image
• type Plugin
• type Span
• type Tokens

Constants

const (
	ClassKeyword = "keyword"
	// ClassType is a type name: a builtin type and a declared type or
	// class name share it.
	ClassType = "type"
	// ClassFunction is a function or method name, at least where the
	// syntax makes it clear (a declaration, often a call).
	ClassFunction = "function"
	ClassString   = "string"
	ClassNumber   = "number"
	ClassComment  = "comment"
)

Conventional Span classes. These are the ones whynot's own stylesheets color; a plugin may use others, which a stylesheet shows in the code block's own color unless it knows them.

Types

type Content

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

Content is what a Plugin makes of a code block: Tokens or an Image. Only this package can define kinds of Content, so new kinds can be added without breaking plugins.

type Image

type Image struct {
	images.AsyncImage
}

Image is a code block shown as an image, e.g. a rendered diagram, loaded in the background.

type Plugin

type Plugin interface {
	// Handles reports whether the plugin parses code blocks in language
	// (the fence's info string, e.g. "go"). It's asked once per language
	// per document.
	Handles(language string) bool

	// Parse makes Content of a code block's source, in a language Handles
	// approved. A nil Content means the plugin declines this block, and
	// the next plugin handling the language is asked instead.
	Parse(language, code string) Content
}

Plugin parses fenced code blocks in the languages it handles.

Several plugins can handle the same language: the first one registered parses the block. If its Content is an Image, what the next one would make of the block is shown while the image loads, or if it fails; plain text if there's no next one.

type Span

type Span struct {
	Text  string
	Class string
}

Span is one classified run of source text. Class is open-ended: a stylesheet colors the classes it knows (see the Class constants) and shows any other class, or none (""), in the code block's own color.

type Tokens

type Tokens struct {
	Spans []Span
}

Tokens is a code block's source split into consecutive spans, each classified for coloring. The spans' Text must concatenate back to the source exactly; if they don't, the tokens are ignored.