Chroma syntax highlighter

Syntax colouring provider implementing highlight_domain.Highlighter, backed by alecthomas/chroma/v2. Ships a bespoke Piko SFC lexer for .pk and .pkc files.

Overview

The Chroma highlighter takes a tokenised stream from a language lexer and renders it to HTML. It uses one of Chroma's bundled styles (Monokai, Dracula, Solarized, GitHub variants, and over 50 more). It caches lexers and rendered results for repeated code blocks, common in long markdown documents, and is safe for concurrent use.

The highlighter satisfies a one-method port, Highlight(code, language string) string. Piko applies it to every fenced code block in rendered markdown for you, so you write no per-block code. The single port method also means you can swap in a custom backend, for example a Prism wrapper or your own renderer, without touching the rest of the configuration.

A custom PikoLexer registers with Chroma at package init() time, so the side-effecting import alone enables it with no registration ordering to manage. It understands SFC blocks (<template>, <script>, <style>, <i18n>), embedded Go inside <script>, embedded CSS and JSON, Piko directives (p-if, p-for, p-bind) with modifiers, the :attr and @event shorthands, and {{ ... }} interpolation. Files matching *.pk or *.pkc get the Piko lexer automatically.

WithClasses defaults to false, which inlines the colour scheme into each token as a style attribute. Set it to true to emit CSS class names instead. The rendered HTML stays smaller, but you must then ship a matching stylesheet for the colours to appear. If you enable line numbers, LineNumbersInTable puts numbers in a separate table cell so they stay out of clipboard selections.

Configuration

import (
    "piko.sh/piko/wdk/highlight/highlight_chroma"
)

highlighter := highlight_chroma.NewChromaHighlighter(highlight_chroma.Config{
    Style:              "dracula", // optional, default "dracula", Chroma style name
    WithClasses:        true,      // optional, default false, emit class names instead of inline styles
    WithLineNumbers:    false,     // optional, default off
    LineNumbersInTable: false,     // optional, only meaningful when WithLineNumbers is true
    TabWidth:           4,         // optional, default 4
})

NewChromaHighlighter returns *Highlighter directly, no error path. An unknown style logs a warning and falls back to styles.Fallback.

Bootstrap

ssr := piko.New(
    piko.WithHighlighter(highlighter),
)

piko.WithHighlighter is the only wiring step. It accepts any highlight_domain.Highlighter and stores it on the container. From there piko's markdown transformer colours every fenced code block, so you write no further glue.

highlight_chroma is its own pure-Go module. It pulls in alecthomas/chroma/v2 with its embedded lexers and styles, which adds a sizeable dependency, but it needs no build tags and no CGO. It drops into any piko run mode, including interpreted dev-i mode.

See also

Sibling integrations:

• Goldmark, markdown parser. Goldmark renders the markdown, then piko routes its fenced code blocks through whichever highlighter you register with WithHighlighter.

Framework docs:

• PK file format reference, every block, attribute, and directive the Piko lexer understands.
• About PK files, the design rationale for the SFC format the lexer parses.

External:

• alecthomas/chroma, the underlying lexer and formatter library and its bundled styles.