Transformers

Transformers modify the HTML rendering pipeline. Pass them in CodeToHTMLOptions.Transformers:

1
import "github.com/frostybee/nuri/transformers"
2
3
html, err := h.CodeToHTML(ctx, code, nuri.CodeToHTMLOptions{
4
  Lang:  "go",
5
  Theme: "github-dark",
6
  Transformers: []nuri.Transformer{
7
    transformers.Notation(),
8
    transformers.Meta("{1,3-5}"),
9
    transformers.Whitespace(),
10
  },
11
})

Transformers run in slice order and apply to HTML output only.

Notation

transformers.Notation() parses magic comments in the source code and applies CSS classes to the corresponding lines. The magic comments are stripped from the output.

1
html, err := h.CodeToHTML(ctx, `
2
func greet(name string) {
3
  fmt.Println("hello, " + name) // [!code highlight]
4
}
5
`, nuri.CodeToHTMLOptions{
6
  Lang:  "go",
7
  Theme: "github-dark",
8
  Transformers: []nuri.Transformer{transformers.Notation()},
9
})

Supported annotations

The [!code word:WORD] annotation does not add a class to the line. Instead, it wraps every matching occurrence of the word within token spans.

Comment stripping

The annotation comment is removed from the output. If the entire line is a comment containing only the annotation (no other code), the line itself is removed and subsequent line numbers shift down.

Focus behavior

When any [!code focus] annotation is present:

• The <pre> element gets class has-focused
• The annotated line gets class focused
• Every other line gets class dimmed

Style has-focused .line:not(.focused) with reduced opacity to create a spotlight effect.

Meta string highlighting

transformers.Meta() highlights lines based on a code-fence meta string:

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

The range expression {1,3-5} highlights lines 1, 3, 4, and 5. Highlighted lines get class highlighted, the same class produced by [!code highlight].

The Meta transformer works by appending parsed ranges to CodeToHTMLOptions.HighlightLines during the Preprocess hook. The renderer applies the class.

Standalone parsing

transformers.ParseMetaRanges() is exported for consumers who need the range parsing without the transformer:

1
ranges, err := transformers.ParseMetaRanges("{1,3-5}")

Returns ([]nuri.LineRange, error). Returns nil, nil for empty input or input without {}.

Visible whitespace

transformers.Whitespace() replaces tab and space characters with visible symbols:

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

Each replaced character is wrapped in a <span> with the corresponding class.

Custom symbols

Override the default symbols with transformers.WhitespaceWith():

1
transformers.WhitespaceWith(transformers.WhitespaceOptions{
2
  Tab:   "⇥",
3
  Space: "⋅",
4
})

Next steps

• Custom Transformers to write your own transformer hooks
• Line Decorations for highlight, focus, and diff without magic comments
• Style-to-Class Mode to replace inline styles with class names