Vigilio Desto
da1d02ccd1
- content/vault/: _index.md, diff.md, session.md, status.md, tasks.md, wikilinks.md - content/docs/: _index.md, introduction, tokens, reset, semantic-html, components, data-attributes, navigation, layouts, charts, chroma, accordion-dialog 96 pages build clean (was 36). Docs use sidebar nav + TOC layout. Vault uses sidebar with section fallback (no vault menu configured yet). URLs fixed: playground refs → asw.trentuna.com. Closes: asw#12, asw#9
155 lines
4.4 KiB
Markdown
155 lines
4.4 KiB
Markdown
---
|
|
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
|