trentuna/asw
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: auto-generated docs sidebar, Decap CMS, content migration infra

Browse source 
Docs restructure:
- Move flat docs into section subdirs (getting-started/, core/,
  components/, reference/) with _index.md for each
- Sidebar auto-generates from content structure — no manual menu entries
- New doc pages appear automatically when created in a section

Decap CMS:
- admin/index.html + config.yml for browser-based editing
- Local mode (npx decap-server) — no OAuth needed
- Collections for all content types: docs, articles, essays, notes, pages

Hugo head.html updated for new CSS layer filenames.
decap-server added as devDependency.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ludo 2026-04-11 18:02:34 +02:00
parent 86464f3e21
commit dd810f5a63
Signed by: ludo
GPG key ID: F6E479DEFAB84D6E
22 changed files with 1624 additions and 140 deletions
Download patch file Download diff file Expand all files Collapse all files

4
site/content/docs/reference/_index.md Normal file
View file

@ -0,0 +1,4 @@
---
title: "Reference"
weight: 40
---

217
site/content/docs/reference/charts.md Normal file
View file

@ -0,0 +1,217 @@
---
title: "Charts"
description: "Data-driven charts from semantic HTML tables using the data-chart attribute vocabulary. Absorbed from Charts.css."
type: docs
weight: 80
date: 2026-04-09
tags: ["charts", "css", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
ASW includes a chart layer (`06-charts.css`) absorbed from [Charts.css](https://chartscss.org/) (MIT), with the class-based API converted to data-attributes. Charts are pure CSS — no JavaScript, no Canvas, no SVG.
The data source is a standard `<table>`. CSS turns it into a chart.
---
## How data binding works
Each `<td>` carries a `--size` CSS custom property via `style` attribute. This is the **one place** ASW permits inline styles — `style="--size: 0.8"` is data injection (a numeric value binding), not presentational styling.
```
--size: 0.0 → 0%
--size: 0.5 → 50%
--size: 1.0 → 100%
```
---
## Bar chart
Horizontal bars. Each row is one bar.
```html
<table data-chart="bar">
<caption>Token budget usage</caption>
<tbody>
<tr>
<th scope="row">Wake</th>
<td style="--size: 0.15">15%</td>
</tr>
<tr>
<th scope="row">Research</th>
<td style="--size: 0.62">62%</td>
</tr>
<tr>
<th scope="row">Output</th>
<td style="--size: 0.23">23%</td>
</tr>
</tbody>
</table>
```
---
## Column chart
Vertical bars. Each `<td>` is one column.
```html
<table data-chart="column">
<caption>Sessions per day</caption>
<tbody>
<tr>
<td style="--size: 0.4">Mon</td>
<td style="--size: 0.7">Tue</td>
<td style="--size: 0.55">Wed</td>
<td style="--size: 0.9">Thu</td>
<td style="--size: 0.3">Fri</td>
</tr>
</tbody>
</table>
```
---
## Line chart
Connects data points with a line. Requires two `<td>` values per point: `--start` and `--end`.
```html
<table data-chart="line">
<caption>Uptime trend</caption>
<tbody>
<tr>
<td style="--start: 0.6; --end: 0.75"></td>
<td style="--start: 0.75; --end: 0.8"></td>
<td style="--start: 0.8; --end: 0.95"></td>
<td style="--start: 0.95; --end: 0.98"></td>
</tr>
</tbody>
</table>
```
---
## Area chart
Like a line chart but with the area beneath filled.
```html
<table data-chart="area">
<caption>Memory usage</caption>
<tbody>
<tr>
<td style="--start: 0.2; --end: 0.35"></td>
<td style="--start: 0.35; --end: 0.5"></td>
<td style="--start: 0.5; --end: 0.4"></td>
<td style="--start: 0.4; --end: 0.6"></td>
</tr>
</tbody>
</table>
```
---
## Axis labels
Add `data-chart-labels` to show `<thead>` column labels as axis labels.
```html
<table data-chart="column" data-chart-labels>
<thead>
<tr>
<th scope="col">Mon</th>
<th scope="col">Tue</th>
<th scope="col">Wed</th>
</tr>
</thead>
<tbody>
<tr>
<td style="--size: 0.4">40%</td>
<td style="--size: 0.7">70%</td>
<td style="--size: 0.55">55%</td>
</tr>
</tbody>
</table>
```
---
## Bar spacing
Control gap between bars with `data-chart-spacing="1"` through `"5"` (default is `2`).
```html
<table data-chart="bar" data-chart-spacing="4">
...
</table>
```
---
## Stacked charts
Multi-dataset mode. Each `<tr>` in `<tbody>` becomes a dataset (one colour per row).
```html
<table data-chart="column" data-chart-stacked>
<caption>Token usage by phase</caption>
<tbody>
<tr style="--color: var(--accent)">
<td style="--size: 0.3"></td>
<td style="--size: 0.4"></td>
<td style="--size: 0.25"></td>
</tr>
<tr style="--color: var(--accent-blue)">
<td style="--size: 0.2"></td>
<td style="--size: 0.15"></td>
<td style="--size: 0.3"></td>
</tr>
</tbody>
</table>
```
---
## Custom colours
Override the default colour cycle with `style="--color: ..."` on any `<tr>`.
```html
<tr style="--color: var(--accent-red)">
<td style="--size: 0.85">Error rate</td>
</tr>
```
Default colour cycle (8 slots): accent → blue → orange → red → purple → cyan → pink → teal.
---
## Customising chart dimensions
Override chart size tokens on the `[data-chart]` element:
```html
<table data-chart="column" style="
--chart-height: 300px;
--chart-bar-size: 3rem;
--chart-gap: 8px;
">
```
| Token | Default | Description |
|-------|---------|-------------|
| `--chart-height` | `200px` | Column chart area height |
| `--chart-bar-size` | `2rem` | Column bar width / bar chart bar height |
| `--chart-gap` | `6px` | Gap between data points |
---
## Related
- [Token System](/docs/tokens/) — colour tokens used by the chart colour cycle (`--accent`, `--accent-blue`, etc.)
- [Data Attributes](/docs/data-attributes/) — the broader `data-*` vocabulary of which `data-chart` is a part

155
site/content/docs/reference/chroma.md Normal file
View 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