Port vault section (5 pages) and docs section (11 pages)
- 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
This commit is contained in:
parent
cbe44d845c
commit
da1d02ccd1
GPG key ID:
159D6AD58C8E55E9
19 changed files with 2462 additions and 1 deletions
155
content/docs/chroma.md
Normal file
155
content/docs/chroma.md
Normal file
|
|
@ -0,0 +1,155 @@
|
|||
---
|
||||
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
|
||||
Loading…
Add table
Add a link
Reference in a new issue