Custom Transformers

Implement the Transformer interface to hook into the HTML rendering pipeline at nine lifecycle points.

The 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
}

Return conventions:

• Preprocess / Postprocess: return "" to leave unchanged, non-empty string to replace
• Tokens: return nil to leave unchanged, non-nil slice to replace
• Span / Line / Code / Pre / Root: return nil to leave unchanged, non-nil *Element to replace

Hook execution order

1. Preprocess -- before tokenization. Receives the raw source and a pointer to the merged options. Can modify code (by returning a non-empty string) and mutate opts (the pointer allows side effects).
2. Tokenization runs on the (possibly replaced) source.
3. Tokens -- after tokenization. Receives the 2-D token grid ([][]ThemedToken, outer = lines, inner = tokens per line).
4. Span -- per token <span>, left-to-right within each line. line is 1-based. col is the UTF-8 byte offset within the line (0-based). lineEl is the containing <span class="line">.
5. Line -- per <span class="line">, after all its span hooks. line is 1-based.
6. Code -- once, on the <code> element.
7. Pre -- once, on the <pre> element.
8. Root -- once, on the top-level element (currently <pre>).
9. Serialization writes the tree to an HTML string.
10. Postprocess -- after serialization. Receives the final HTML string.

When multiple transformers are passed, each hook runs all transformers in slice order. For element hooks (Span through Root), the last non-nil return wins.

BaseTransformer

Embed nuri.BaseTransformer to get no-op defaults for all hooks, then override only the hooks needed:

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

Use it in the Transformers slice:

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

Each <span class="line"> in the output now carries a data-line attribute.

The HTML AST

Transformer hooks receive and return *nuri.Element nodes. The AST has two node types:

Element

1
type Element struct {
2
  Tag      string
3
  Classes  []string
4
  Styles   map[string]string
5
  Attrs    map[string]string
6
  Children []Node
7
}

Helper methods:

• el.AddClass(class) -- appends a CSS class if not already present
• el.SetAttr(key, val) -- sets an HTML attribute (initializes the map if nil)

Styles and Attrs maps are emitted in sorted key order for deterministic output.

Text

1
type Text struct {
2
  Content string
3
}

Content is HTML-escaped (<, >, &) on write.

Node

1
type Node interface {
2
  WriteTo(w io.Writer) (int64, error)
3
}

Both *Element and *Text satisfy Node and io.WriterTo.

Example: wrapping in a container

The Root hook runs after the tree is fully built. Use it to wrap the output in a container element:

1
type codeBlock struct {
2
  nuri.BaseTransformer
3
}
4
5
func (codeBlock) Name() string { return "code-block" }
6
7
func (codeBlock) Root(el *nuri.Element) *nuri.Element {
8
  return &nuri.Element{
9
    Tag:      "div",
10
    Classes:  []string{"code-block"},
11
    Children: []nuri.Node{el},
12
  }
13
}

The output becomes <div class="code-block"><pre class="nuri ...">...</pre></div>.

Example: modifying tokens

The Tokens hook runs after tokenization but before tree building. Use it to filter or transform the raw token data:

1
type trimTrailing struct {
2
  nuri.BaseTransformer
3
}
4
5
func (trimTrailing) Name() string { return "trim-trailing" }
6
7
func (trimTrailing) Tokens(tokens [][]nuri.ThemedToken) [][]nuri.ThemedToken {
8
  for i, line := range tokens {
9
    if len(line) > 0 {
10
      last := &tokens[i][len(line)-1]
11
      last.Content = strings.TrimRight(last.Content, " \t")
12
    }
13
  }
14
  return tokens
15
}

Next steps

• Transformers for the built-in notation, meta, and whitespace transformers
• Types for the full reference on Element, Text, Node, and all AST types
• Transformer API for complete hook signatures and built-in constructor details