arborium

Batteries-included tree-sitter grammar collection with HTML rendering and WASM support.

Features

69 language grammars included out of the box
67 permissively licensed (MIT/Apache-2.0/CC0/Unlicense) grammars enabled by default
WASM support with custom allocator fix
Feature flags for fine-grained control over included languages

Usage

[dependencies]
arborium = "0.0.0"

By default, all permissively-licensed grammars are included. To select specific languages:

[dependencies]
arborium = { version = "0.0.0", default-features = false, features = ["lang-rust", "lang-javascript"] }

Browser Usage

Arborium can be used in the browser in two ways:

Option 1: Drop-in Script (Easiest)

Add a single script tag and arborium auto-highlights all code blocks:

<script src="https://cdn.jsdelivr.net/npm/@arborium/arborium/dist/arborium.iife.js"></script>

That's it! Arborium will:

Auto-detect languages from class="language-*" or data-lang="*" attributes
Load grammar WASM plugins on-demand from jsDelivr CDN
Inject the default theme CSS

Configuration via data attributes:

<script
  src="https://cdn.jsdelivr.net/npm/@arborium/arborium/dist/arborium.iife.js"
  data-theme="mocha"
  data-selector="pre code"
  data-manual
></script>

Configuration via JavaScript:

<script>
  window.Arborium = {
    theme: 'tokyo-night',
    selector: 'pre code, .highlight',
    cdn: 'jsdelivr',  // or 'unpkg' or a custom URL
    version: '1', // or 'latest'
  };
</script>
<script src="https://cdn.jsdelivr.net/npm/@arborium/arborium/dist/arborium.iife.js"></script>

Manual highlighting:

<script src="..." data-manual></script>
<script>
  // Highlight all code blocks
  arborium.highlightAll();

  // Highlight a specific element
  arborium.highlightElement(document.querySelector('code'), 'rust');
</script>

Option 2: ESM Module (Programmatic)

For bundlers (Vite, webpack, etc.) or ESM-native environments:

npm install @arborium/arborium

import { loadGrammar, highlight } from '@arborium/arborium';

// Load a grammar (fetched from CDN on first use)
const grammar = await loadGrammar('rust');

// Highlight code
const html = grammar.highlight('fn main() { println!("Hello!"); }');

// Or use the convenience function
const html = await highlight('rust', code);

Option 3: Compile Rust to WASM (Maximum Control)

For complete control and offline-first apps, compile the Rust crate directly to WASM:

[dependencies]
arborium = { version = "0.0.0", default-features = false, features = ["lang-rust", "lang-javascript"] }

# Requires LLVM with WASM support (see FAQ below)
cargo build --target wasm32-unknown-unknown

This embeds selected grammars directly in your WASM binary - no CDN required at runtime.

Themes

Arborium includes 32 built-in themes from popular color schemes.

Dark themes: catppuccin-mocha, catppuccin-macchiato, catppuccin-frappe, dracula, tokyo-night, nord, one-dark, github-dark, gruvbox-dark, monokai, kanagawa-dragon, rose-pine-moon, ayu-dark, solarized-dark, ef-melissa-dark, melange-dark, cobalt2, zenburn, desert256, rustdoc-dark, rustdoc-ayu

Light themes: catppuccin-latte, github-light, gruvbox-light, ayu-light, solarized-light, melange-light, light-owl, lucius-light, dayfox, alabaster, rustdoc-light

Import theme CSS:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@arborium/arborium/dist/themes/tokyo-night.css">

Or let the IIFE bundle auto-inject it via the data-theme attribute.

Theme Attribution: All themes are adaptations of color schemes from their original projects. See the arborium-theme crate README for full attribution and source links.

Feature Flags

Grammar Collections

Feature	Description
`mit-grammars`	All permissively licensed grammars (MIT, Apache-2.0, CC0) - default
`gpl-grammars`	GPL-licensed grammars (copyleft - may affect your project's license)
`all-grammars`	All grammars including GPL

Permissive Grammars (76)

These grammars use permissive licenses (MIT, Apache-2.0, CC0, Unlicense) and are included by default.

Feature	Language	License	Source

| lang-awk | AWK | MIT | tree-sitter-awk |

| lang-c | C | MIT | tree-sitter-c |

| lang-c-sharp | C# | MIT | tree-sitter-c-sharp |

| lang-cpp | C++ | MIT | tree-sitter-cpp |

| lang-css | CSS | MIT | tree-sitter-css |

| lang-elm | Elm | MIT | tree-sitter-elm |

| lang-fsharp | F# | MIT | tree-sitter-fsharp |

| lang-go | Go | MIT | tree-sitter-go |

| lang-jq | jq | MIT | tree-sitter-jq |

| lang-lua | Lua | MIT | tree-sitter-lua |

| lang-nix | Nix | MIT | tree-sitter-nix |

| lang-php | PHP | MIT | tree-sitter-php |

| lang-r | R | MIT | tree-sitter-r |

| lang-sql | SQL | MIT | tree-sitter-sql |

| lang-tlaplus | TLA+ | MIT | tree-sitter-tlaplus |

| lang-tsx | TSX | MIT | tree-sitter-tsx |

| lang-vue | Vue | MIT | tree-sitter-vue |

| lang-xml | XML | MIT | tree-sitter-xml |

| lang-zig | Zig | MIT | tree-sitter-zig |

| lang-zsh | Zsh | MIT | tree-sitter-zsh |

GPL-Licensed Grammars (1)

These grammars are not included by default due to their copyleft license. Enabling them may have implications for your project's licensing.

Feature	Language	License	Source

HTML Tag Reference

Arborium renders syntax highlighting using custom HTML elements. When highlighting code, it wraps spans of text with tags like <a-k>, <a-f>, etc. These tags are styled by the theme CSS you choose.

Tag Mappings

Each tag corresponds to a semantic code element. Here's the complete reference:

Tag	Element Type	Description
`<a-k>`	Keyword	Language keywords (if, else, while, class, fn, etc.)
`<a-f>`	Function	Function names and method calls
`<a-s>`	String	String literals and character literals
`<a-c>`	Comment	Comments (line and block)
`<a-t>`	Type	Type names and type annotations
`<a-v>`	Variable	Variable names and identifiers
`<a-co>`	Constant	Constants and boolean literals
`<a-n>`	Number	Numeric literals (integers and floats)
`<a-o>`	Operator	Operators (+, -, *, /, &&, etc.)
`<a-p>`	Punctuation	Delimiters and punctuation (parentheses, brackets, commas)
`<a-pr>`	Property	Object properties and struct fields
`<a-at>`	Attribute	Attributes and annotations (@, #[derive], etc.)
`<a-tg>`	Tag	HTML/XML tags
`<a-m>`	Macro	Macro names and invocations
`<a-l>`	Label	Labels and goto targets
`<a-ns>`	Namespace	Namespaces and modules
`<a-cr>`	Constructor	Constructor functions and type constructors

Markup Tags (Markdown, etc.)

Tag	Element Type	Description
`<a-tt>`	Title	Headings and titles
`<a-st>`	Strong	Bold text
`<a-em>`	Emphasis	Italic text
`<a-tu>`	Link	URLs and hyperlinks
`<a-tl>`	Literal	Code blocks and inline code
`<a-tx>`	Strikethrough	Strikethrough text

Diff Tags

Tag	Element Type	Description
`<a-da>`	Diff Add	Added lines in diffs
`<a-dd>`	Diff Delete	Deleted lines in diffs

Special Tags

Tag	Element Type	Description
`<a-eb>`	Embedded	Embedded language content
`<a-er>`	Error	Syntax errors

How It Works

Arborium uses tree-sitter grammars to parse code and identify semantic elements. Multiple capture names from tree-sitter queries (like @keyword.function, @keyword.import, @conditional) all map to the same theme slot. For example:

@keyword, @keyword.function, @include, @conditional → all become <a-k> (keyword)
@function, @function.builtin, @method → all become <a-f> (function)
@comment, @comment.documentation → all become <a-c> (comment)

Adjacent spans with the same tag are automatically merged into a single element for efficiency.

Styling Example

To create a custom theme, target these elements in your CSS:

/* Keywords in blue */
a-k { color: #569cd6; }

/* Functions in yellow */
a-f { color: #dcdcaa; }

/* Strings in green */
a-s { color: #ce9178; }

/* Comments in gray */
a-c { color: #6a9955; font-style: italic; }

/* Types in cyan */
a-t { color: #4ec9b0; }

See the included themes for more examples.

License

This project is dual-licensed under MIT OR Apache-2.0.

The bundled grammar sources retain their original licenses - see LICENSES.md for details.

WASM Support

Arborium supports building for wasm32-unknown-unknown. This requires compiling C code (tree-sitter core and grammar parsers) to WebAssembly.

macOS

On macOS, the built-in Apple clang does not support the wasm32-unknown-unknown target. You need to install LLVM via Homebrew:

brew install llvm

Then ensure the Homebrew LLVM is in your PATH when building:

export PATH="$(brew --prefix llvm)/bin:$PATH"
cargo build --target wasm32-unknown-unknown

Development

This project uses cargo xtask for most development and release tasks.

For detailed architecture, workflows, publishing order, and layout, see DEVELOP.md.

For a quick overview of available commands, run:

cargo xtask help

arborium 2.4.0