---
title: "Syntax Highlighting"
description: "How ASW's chroma layer provides syntax highlighting for Hugo and how to use Prism.js as an alternative."
type: docs
weight: 90
date: 2026-04-09
tags: ["syntax-highlighting", "css", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"

---

ASW ships two syntax highlighting systems:

- **`07-chroma.css`** — Hugo/Chroma class names mapped to Open Props tokens. For Hugo sites.
- **`02-semantic.css` (Prism section)** — Token overrides for Prism.js. For non-Hugo sites.

Both render with the same token palette: Open Props perceptual colour scale, dark-first with light-mode overrides.

---

## Hugo / Chroma

Hugo uses [Chroma](https://github.com/alecthomas/chroma) to highlight code fences. Chroma emits CSS classes (`.k`, `.s`, `.c`, etc.). `07-chroma.css` maps those classes to ASW tokens.

### Setup

In `hugo.toml` (or `config.toml`):

```toml
[markup.highlight]
  noClasses = false    # emit class names, not inline styles
  codeFences = true
  lineNos = false
```

Then include `agentic.css` (which bundles `07-chroma.css`). No separate highlight stylesheet needed.

### Usage

Standard fenced code blocks in Markdown:

````markdown
```python
def greet(name: str) -> str:
    return f"Hello, {name}"
```
````

````markdown
```javascript
const greet = (name) => `Hello, ${name}`;
```
````

### Token colour mapping

| Token class | Colour token | Example |
|------------|-------------|---------|
| `.k` keywords | `--violet-4` | `def`, `return`, `if` |
| `.s` strings | `--green-4` | `"hello"`, `'world'` |
| `.c` comments | `--gray-5` italic | `# comment` |
| `.n` names | `--blue-3` | identifiers |
| `.mi` integers | `--orange-4` | `42`, `0xff` |
| `.mf` floats | `--orange-3` | `3.14` |
| `.nb` builtins | `--cyan-4` | `print`, `len` |
| `.nf` functions | `--blue-4` | function names |
| `.nc` classes | `--yellow-3` | class names |
| `.o` operators | body colour | `+`, `=`, `->` |
| `.p` punctuation | muted | `(`, `)`, `,` |
| `.err` errors | `--red-4` | parse errors |

Light mode swaps all tokens to their darker counterparts (e.g. `--green-4` → `--green-8`).

### Wrapper

Chroma wraps output in `<div class="highlight"><pre class="chroma"><code>`. ASW styles `.chroma` as a block with `var(--surface-2)` background and rounded corners.

```css
.chroma {
  background: var(--surface-2);
  border-radius: var(--radius-2);
  overflow-x: auto;
}
```

---

## Prism.js (non-Hugo)

For sites not using Hugo, ASW's `02-semantic.css` includes token overrides for [Prism.js](https://prismjs.com/).

### Setup

Load Prism from CDN:

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-core.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/plugins/autoloader/prism-autoloader.min.js"></script>
```

No Prism theme stylesheet needed — ASW overrides the colours.

### Usage

```html
<pre><code class="language-css">:root {
  --accent: var(--green-5);
  --surface: var(--gray-15);
}</code></pre>

<pre><code class="language-html"><div data-layout="hero">
  <h1>Hello</h1>
</div></code></pre>
```

Prism auto-detects the language from the `language-*` class and highlights on load.

### Token mapping (Prism)

| Token class | Colour | Example |
|------------|--------|---------|
| `.token.keyword` | `--blue-4` | `const`, `return` |
| `.token.string` | `--green-4` | `"text"` |
| `.token.comment` | `--gray-6` italic | `// comment` |
| `.token.number` | `--orange-4` | `42` |
| `.token.function` | `--cyan-4` | function names |
| `.token.class-name` | `--cyan-4` | class names |
| `.token.tag` | `--red-4` | HTML tags |
| `.token.attr-name` | `--yellow-4` | `href`, `data-role` |
| `.token.attr-value` | `--green-4` | attribute values |
| `.token.selector` | `--teal-4` | CSS selectors |
| `.token.property` | `--blue-5` | CSS properties |

---

## Choosing between the two

| | Chroma | Prism |
|--|--------|-------|
| **Requires** | Hugo | JavaScript |
| **Languages** | 200+ (server-side) | 200+ (lazy-loaded) |
| **Build step** | No (Hugo handles it) | No (CDN) |
| **Output** | Static HTML | Dynamic (runtime) |
| **ASW layer** | `07-chroma.css` | `02-semantic.css` |

Use Chroma for Hugo sites. Use Prism for everything else.

---

## Related

- [Token System](/docs/tokens/) — the Open Props colour tokens that the highlight palette maps to
- [Semantic HTML](/docs/semantic-html/) — how `<pre>` and `<code>` are styled at the element level