highlight_code

By Goblin Docs ~ 8 min read

:highlight_code takes a string of source code and returns highlighted HTML. Highlighting happens at build time inside the Goblin runtime — no JavaScript required in the browser.

Overview

:highlight_code is powered by Syntect, a Rust syntax highlighting library that uses the same grammar files as Sublime Text (.sublime-syntax / .tmLanguage). The same grammars power both the Goblin runtime and your Sublime Text editor.

Because highlighting runs inside the interpreter, the output is plain static HTML ready to embed in a page.

Signature

:highlight_code(code, lang, dark_theme, light_theme)

:highlight_code(code, lang, dark_theme, light_theme)

Argument	Type	Description
`code`	string	The source code to highlight.
`lang`	string	Language token or file extension (e.g. `"goblin"`, `"rust"`, `"ts"`, `"py"`).
`dark_theme`	string	Syntect theme name for dark mode.
`light_theme`	string	Syntect theme name for light mode.

Basic Usage

html | :highlight_code("x | 42\n:say(x)", "goblin", "base16-ocean.dark", "InspiredGitHub")

html | :highlight_code("x | 42\n:say(x)", "goblin", "base16-ocean.dark", "InspiredGitHub")

The return value is an HTML string containing two div wrappers — one for dark mode, one for light:

<div class="hl-dark"><!-- dark highlighted HTML --></div>
<div class="hl-light"><!-- light highlighted HTML --></div>

<div class="hl-dark"><!-- dark highlighted HTML --></div>
<div class="hl-light"><!-- light highlighted HTML --></div>

Both are generated at the same time. CSS on your page controls which one is visible.

Available Themes

Syntect ships with the following built-in themes:

Dark:

base16-ocean.dark
base16-eighties.dark
base16-mocha.dark
Solarized (dark)

Light:

InspiredGitHub
base16-ocean.light
Solarized (light)

Supported Languages

Syntect bundles grammars for most common languages — Rust, TypeScript, Python, JavaScript, SQL, Bash, CSS, HTML, JSON, YAML, and many more.

Goblin has its own .sublime-syntax grammar baked into the runtime, so "goblin" works as a language token without any extra setup.

If you pass an unrecognized language token, :highlight_code falls back to plain text — no error, no crash, just unstyled code.

Under the Hood

When the Goblin interpreter starts, it loads Syntect's default syntax set and adds the Goblin grammar on top. The grammars and themes are compiled into the binary at build time via include_str! — there are no external files to ship or locate at runtime.

The SyntaxSet and ThemeSet are stored in static OnceLock values so they are initialized once on first use and reused for every subsequent call. On a large build with many code blocks this makes a meaningful difference.

Syntect injects an inline background-color style on the <pre> tag. :highlight_code strips that out before returning so your own CSS controls the background.

Errors

Passing a non-string raises a type error:

:highlight_code(42, "rust", "base16-ocean.dark", "InspiredGitHub")
/// error: T0205 type-mismatch

:highlight_code(42, "rust", "base16-ocean.dark", "InspiredGitHub")
/// error: T0205 type-mismatch

Passing the wrong number of arguments raises a wrong-arity error:

:highlight_code("x | 1", "goblin")
/// error: R0301 wrong-arity: expected 4, got 2

:highlight_code("x | 1", "goblin")
/// error: R0301 wrong-arity: expected 4, got 2