Transformer API

This page documents the Transformer interface, the BaseTransformer embed pattern, and the built-in transformer constructors in the transformers package. For usage examples, see Transformers and Custom Transformers.

Transformer interface

1
type Transformer interface {
2
    Name() string
3
    Preprocess(code string, opts *CodeToHTMLOptions) string
4
    Tokens(tokens [][]ThemedToken) [][]ThemedToken
5
    Span(el *Element, line, col int, lineEl *Element, tok ThemedToken) *Element
6
    Line(el *Element, line int) *Element
7
    Code(el *Element) *Element
8
    Pre(el *Element) *Element
9
    Root(el *Element) *Element
10
    Postprocess(html string, opts *CodeToHTMLOptions) string
11
}

Hooks are called in the order listed during a single h.CodeToHTML() call.

Span parameters: line is 1-based. col is the UTF-8 byte offset within the line (0-based). lineEl is the containing line element. tok is the themed token being rendered.

Preprocess and Postprocess receive a mutable *CodeToHTMLOptions pointer, allowing transformers to modify options (e.g. appending to HighlightLines).

BaseTransformer

1
type BaseTransformer struct{}

Provides no-op defaults for all Transformer hooks. Embed it in custom transformers to override only the hooks needed:

1
type myTransformer struct {
2
    nuri.BaseTransformer
3
}
4
5
func (t *myTransformer) Name() string { return "my-transformer" }
6
7
func (t *myTransformer) Line(el *nuri.Element, line int) *nuri.Element {
8
    el.SetAttr("data-line", strconv.Itoa(line))
9
    return el
10
}

All BaseTransformer methods return "" (string hooks) or nil (element hooks), signaling no change.

Built-in transformers

transformers.Notation

1
func Notation() ast.Transformer

Parses magic comments in source code and applies CSS classes to the corresponding line elements. The magic comment and any surrounding bare comment markers are stripped from the output.

Annotations:

Comment stripping: After removing the [!code ...] pattern, if the remaining token content is only a bare comment marker (//, #, /*, */, /* */), the token is dropped along with any preceding whitespace-only token. Lines that become entirely whitespace after stripping are eliminated from the output, and subsequent line numbers are renumbered.

Hooks used: Name ("notation"), Tokens, Span (word highlights only), Line, Pre (focus mode).

transformers.Meta

1
func Meta(meta string) ast.Transformer

Applies line highlighting based on a code-fence meta string. Parses meta using ParseMetaRanges and appends the resulting ranges to opts.HighlightLines in the Preprocess hook. The renderer then applies the highlighted class to matching lines.

Parse errors are silently ignored. The transformer becomes a no-op if no valid ranges are found.

Hooks used: Name ("meta"), Preprocess.

1
html, err := h.CodeToHTML(ctx, code, nuri.CodeToHTMLOptions{
2
    Lang:  "go",
3
    Theme: "github-dark",
4
    Transformers: []nuri.Transformer{
5
        transformers.Meta("{1,3-5}"),
6
    },
7
})

transformers.Whitespace

1
func Whitespace() ast.Transformer

Renders whitespace characters as visible symbols. Each tab is replaced with <span class="ws-tab">→</span> and each space with <span class="ws-space">·</span>.

Hooks used: Name ("whitespace"), Span.

transformers.WhitespaceWith

1
func WhitespaceWith(opts WhitespaceOptions) ast.Transformer

Same as transformers.Whitespace() with custom replacement symbols. Zero-valued fields fall back to the defaults.

WhitespaceOptions

1
type WhitespaceOptions struct {
2
    Tab   string
3
    Space string
4
}

transformers.ParseMetaRanges

1
func ParseMetaRanges(meta string) ([]ast.LineRange, error)

Parses a code-fence meta string like "{1,3-5,7}" into a slice of LineRange values. Extracts the content between the first { and last }, splits on ,, and parses each token as either a single line number or a start-end range.

Returns:

• []LineRange, nil on success
• nil, nil for empty input, missing braces, or empty content between braces
• nil, error on non-numeric content

Hook coverage

All built-in transformers use BaseTransformer for hooks not listed above. Code, Root, and Postprocess are not used by any built-in transformer.