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

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

View file

@ -0,0 +1,4 @@
---
title: "Components"
weight: 30
---

View file

@ -0,0 +1,117 @@
---
title: "Accordion & Dialog"
description: "Native disclosure and modal patterns. No JavaScript required for accordion; dialog uses the native showModal() API."
layout: docs
weight: 45
type: docs
date: 2026-04-09
tags: ["components", "interactive", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
## Accordion
Style native `<details>`/`<summary>` elements. No JS needed — the browser handles open/close state.
```html
<details>
<summary>What is agentic HTML?</summary>
<p>Agentic HTML is structured markup generated by AI agents — semantic, predictable, and styled without classes.</p>
</details>
```
**Live example:**
<details>
<summary>What is agentic HTML?</summary>
<p>Agentic HTML is structured markup generated by AI agents — semantic, predictable, and styled without classes.</p>
</details>
<details>
<summary>Why no classes?</summary>
<p>Language models reliably produce semantic HTML. Class names require memorisation and drift. Data-attributes are explicit and grep-friendly.</p>
</details>
---
## Grouped Accordion
Wrap in `<div data-role="accordion">` for flush connected borders.
```html
<div data-role="accordion">
<details>
<summary>Reset layer</summary>
<p>Normalises browser defaults without imposing opinions.</p>
</details>
<details>
<summary>Token layer</summary>
<p>Open Props foundation plus ASW semantic aliases.</p>
</details>
<details open>
<summary>Components layer</summary>
<p>Buttons, forms, accordion, dialog — all zero-class.</p>
</details>
</div>
```
**Live example:**
<div data-role="accordion">
<details>
<summary>Reset layer</summary>
<p>Normalises browser defaults without imposing opinions.</p>
</details>
<details>
<summary>Token layer</summary>
<p>Open Props foundation plus ASW semantic aliases.</p>
</details>
<details open>
<summary>Components layer</summary>
<p>Buttons, forms, accordion, dialog — all zero-class.</p>
</details>
</div>
---
## Dialog
Native `<dialog>` element. Use `dialog.showModal()` for a modal with backdrop, or `dialog.show()` for a non-modal popover.
```html
<dialog id="demo-dialog">
<header><h2>Confirm action</h2></header>
<p>Are you sure you want to proceed? This cannot be undone.</p>
<footer>
<button onclick="document.getElementById('demo-dialog').close()">Cancel</button>
<button onclick="document.getElementById('demo-dialog').close()">Confirm</button>
</footer>
</dialog>
<button onclick="document.getElementById('demo-dialog').showModal()">Open dialog</button>
```
**Live example:**
<dialog id="demo-dialog">
<header><h2>Confirm action</h2></header>
<p>Are you sure you want to proceed? This cannot be undone.</p>
<footer>
<button onclick="document.getElementById('demo-dialog').close()">Cancel</button>
<button onclick="document.getElementById('demo-dialog').close()">Confirm</button>
</footer>
</dialog>
<button onclick="document.getElementById('demo-dialog').showModal()">Open dialog</button>
---
## Notes
- Accordion uses `:not(nav details)` scoping so nav dropdowns are unaffected.
- Dialog backdrop uses `color-mix()` for transparency — no hardcoded rgba values.
- All spacing uses Open Props / ASW tokens (`--space-*`, `--radius-*`, `--shadow-*`).
- `dialog::backdrop` uses `backdrop-filter: blur(4px)` for frosted glass effect.

View file

@ -0,0 +1,222 @@
---
title: "Components"
description: "ASW's data-attribute vocabulary — callouts, tasks, session blocks, wikilinks, and layout primitives."
type: docs
weight: 30
date: 2026-04-09
tags: ["components", "css", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
## Callouts
Inline advisory blocks. The `data-callout` attribute sets the semantic type; the stylesheet handles colour, icon, and layout.
```html
<div data-callout="tip">
<span data-callout-title>Tip</span>
<p>Use <code>data-callout</code> instead of inventing class names.</p>
</div>
<div data-callout="warning">
<span data-callout-title>Warning</span>
<p>Overriding Open Props palette tokens breaks theming.</p>
</div>
<div data-callout="error">
<span data-callout-title>Error</span>
<p>This file exceeds the token budget.</p>
</div>
<div data-callout="note">
<span data-callout-title>Note</span>
<p>Both <code>note</code> and <code>info</code> are valid values.</p>
</div>
```
{{< callout tip >}}
In Hugo, use the `callout` shortcode: `{{</* callout tip */>}}...{{</* /callout */>}}`
{{< /callout >}}
Valid values: `tip`, `note`, `info`, `warning`, `error`.
---
## Tasks
Render task lists with semantic state. Agents write task lists naturally; `data-task` on the `<li>` adds the visual state indicator.
```html
<ul>
<li data-task="done">Token layer integrated</li>
<li data-task="done">Docs site taxonomy wired</li>
<li data-task="wip">Hugo layouts — in progress</li>
<li data-task="blocked">Deploy — waiting on DNS</li>
<li data-task="todo">Vocabulary retirement pass</li>
</ul>
```
Valid values: `done`, `wip`, `blocked`, `todo`.
---
## Session blocks
Mark a block as a session record with `data-session`. Optional `data-mode` indicates autonomous vs. interactive sessions.
```html
<section data-session data-mode="autonomous">
<header>
<h3>Session 2847</h3>
<p data-text="dim">2026-04-02 · 31 min · claude-sonnet-4-6</p>
</header>
<ul>
<li data-task="done">Vault token layer</li>
<li data-task="wip">Paper layout</li>
</ul>
<div data-callout="note">
<span data-callout-title>Handoff</span>
<p>Next session: harden paper/single.html styles into agentic.css.</p>
</div>
</section>
```
---
## Wikilinks
Internal knowledge-graph links. `data-wikilink` on an anchor renders it with a dotted underline to distinguish it from a regular hyperlink.
```html
<a href="/notes/tasks/" data-wikilink>Tasks</a>
```
In Hugo, use the `wikilink` shortcode:
```
{{</* wikilink "Tasks" "/notes/tasks/" */>}}
```
---
## Redacted content
Sensitive values rendered as black bars. Optional hover-reveal.
```html
<span data-redacted>API key: sk-ant-...</span>
<!-- Hover to reveal -->
<span data-redacted data-redacted-reveal>classified content</span>
```
---
## Layout primitives
### Grid
```html
<!-- Two columns, responsive stack below 600px -->
<div data-layout="grid-2">
<article>Left</article>
<article>Right</article>
</div>
<!-- Three columns, responsive stack below 768px -->
<div data-layout="grid-3">
<article>One</article>
<article>Two</article>
<article>Three</article>
</div>
<!-- Auto-fill card grid, minmax(280px, 1fr) -->
<div data-layout="card-grid">
<article>Card A</article>
<article>Card B</article>
<article>Card C</article>
</div>
```
### Stats row
```html
<div data-layout="stats">
<div>
<span data-stat="value">2847</span>
<span data-stat="label">Sessions</span>
</div>
<div>
<span data-stat="value">99.8%</span>
<span data-stat="label">Uptime</span>
</div>
</div>
```
### Docs layout
Three-column sidebar scaffold. Source order matters: left aside → article → right aside.
```html
<div data-layout="docs">
<aside>
<nav aria-label="Documentation" data-nav="sidebar">
<small>Section</small>
<ul>
<li><a href="/docs/introduction/" aria-current="page">Introduction</a></li>
<li><a href="/docs/tokens/">Token System</a></li>
</ul>
</nav>
</aside>
<article>
<!-- Main content -->
</article>
<aside data-toc>
<small>On this page</small>
<nav>
<ul>
<li><a href="#callouts">Callouts</a></li>
</ul>
</nav>
</aside>
</div>
```
---
## Text utilities
```html
<p data-text="dim">Muted — var(--text-3)</p>
<p data-text="accent">Accent colour</p>
<span data-text="eyebrow">SECTION LABEL</span>
<span data-text="small">Fine print</span>
```
---
## CTA links
```html
<a href="/docs/introduction/" data-role="primary">Get started →</a>
<a href="/docs/" data-role="secondary">Documentation</a>
```
---
## Badge
Icon or token pill. Used by the landing page pillars; also useful inline.
```html
<span data-badge>&lt;/&gt;</span>
<span data-badge>data=</span>
<span data-badge>:root</span>
```

View file

@ -0,0 +1,247 @@
---
title: "Layouts"
description: "All data-layout values and how to use them — docs scaffold, grids, hero, prose, timeline, and more."
type: docs
weight: 40
date: 2026-04-09
tags: ["layouts", "css", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
`data-layout` on any element activates a layout pattern. No classes needed.
---
## Docs layout
Three-column scaffold: sidebar, content, TOC. Source order: left `<aside>` → content → right `<aside data-toc>`.
```html
<div data-layout="docs">
<aside>
<nav data-nav="sidebar" aria-label="Docs">
<small>Getting started</small>
<ul>
<li><a href="/docs/introduction/" aria-current="page">Introduction</a></li>
<li><a href="/docs/tokens/">Token System</a></li>
</ul>
</nav>
</aside>
<article>
<h1>Page title</h1>
<p>Content goes here.</p>
</article>
<aside data-toc>
<small>On this page</small>
<nav>
<ul>
<li><a href="#section">Section</a></li>
</ul>
</nav>
</aside>
</div>
```
The right TOC hides below ~1280px. The left sidebar hides below ~768px.
---
## Hero
Landing page header block. Centers content, adds vertical padding, draws a bottom border.
```html
<header data-layout="hero">
<h1>Agentic Semantic Web</h1>
<p>CSS for agent-generated content.</p>
<p data-layout="install"><code>@import "agentic.css"</code></p>
</header>
```
### Install pill
`data-layout="install"` on a `<p>` or `<div>` renders an inline monospace pill — intended for single-line install commands inside a hero.
---
## Actions row
CTA button row, centered, wraps on small screens.
```html
<nav data-layout="actions">
<a href="/docs/introduction/" data-role="primary">Get started →</a>
<a href="https://github.com/..." data-role="secondary">GitHub</a>
</nav>
```
---
## Grid layouts
### Two columns
```html
<div data-layout="grid-2">
<article>Left column</article>
<article>Right column</article>
</div>
```
Stacks to one column below ~768px.
### Three columns
```html
<div data-layout="grid-3">
<article>One</article>
<article>Two</article>
<article>Three</article>
</div>
```
Stacks to one column below ~768px.
### Card grid
Auto-fill, responsive. Columns fill to a minimum of `--card-min-width` (default: `280px`).
```html
<div data-layout="card-grid">
<article>Card A</article>
<article>Card B</article>
<article>Card C</article>
</div>
```
---
## Stats row
Horizontal stat display. Wraps responsively.
```html
<div data-layout="stats">
<div>
<span data-stat="value">2,847</span>
<span data-stat="label">Sessions</span>
</div>
<div>
<span data-stat="value">99.8%</span>
<span data-stat="label">Uptime</span>
</div>
<div>
<span data-stat="value">14</span>
<span data-stat="label">Projects</span>
</div>
</div>
```
---
## Prose
Constrains width to `65ch` for comfortable reading. Apply to `<main>` or any block.
```html
<main data-layout="prose">
<h1>Article title</h1>
<p>Long-form content at a comfortable reading width.</p>
</main>
```
---
## Fluid
Removes the max-width constraint from `<main>`. Use for full-bleed layouts.
```html
<main data-layout="fluid">
<!-- Full-width content -->
</main>
```
---
## Timeline
Vertical chronological list with a spine line and accent dots.
```html
<ol data-layout="timeline">
<li>
<time>2026-04-10</time>
<article>
<h3>Event title</h3>
<p>Description of what happened.</p>
</article>
</li>
<li>
<time>2026-03-28</time>
<article>
<h3>Earlier event</h3>
<p>Prior milestone.</p>
</article>
</li>
</ol>
```
Add `alternate` to the value for a left/right alternating layout:
```html
<ol data-layout="timeline alternate">
```
---
## Report
Print-first document layout. Constrained to `72ch`, includes print stylesheet. Light surface regardless of OS theme.
```html
<div data-layout="report">
<header>
<h1>Report Title</h1>
<p>Prepared 2026-04-10</p>
</header>
<main>
<h2>Findings</h2>
<p>Content here.</p>
</main>
<footer>Confidential · Trentuna</footer>
</div>
```
On print, links render with their URL in parentheses. `data-no-print` on any element hides it from print output.
---
## Inline definition list
Renders a `<dl>` as a two-column grid: terms on the left, definitions on the right. Apply to `<dl>` only.
```html
<dl data-layout="inline">
<dt>--accent</dt>
<dd>Primary action colour, sourced from Open Props <code>--green-5</code></dd>
<dt>--surface</dt>
<dd>Page background, adaptive light/dark</dd>
<dt>--font-ui</dt>
<dd>Neo-grotesque sans stack for UI chrome</dd>
</dl>
```
---
## Related
- [Data Attributes](/docs/data-attributes/) — full `data-*` vocabulary reference
- [Token System](/docs/tokens/) — the custom property values that layout tokens reference

View file

@ -0,0 +1,105 @@
---
title: "Navigation"
description: "Breadcrumb trails and step sequences for orienting users in docs and agentic workflows."
type: docs
weight: 35
date: 2026-04-09
tags: ["navigation", "components", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
ASW provides two navigation components for orientation and workflow sequencing: `breadcrumb` for hierarchical location, and `steps` for pipeline progress.
---
## Breadcrumb
Shows the current page's position in a site hierarchy. Uses `<nav data-role="breadcrumb">` with a plain `<ol>` — no classes needed.
```html
<nav data-role="breadcrumb" aria-label="breadcrumb">
<ol>
<li><a href="/">Home</a></li>
<li><a href="/docs/">Docs</a></li>
<li aria-current="page">Token System</li>
</ol>
</nav>
```
- Separators (`/`) are drawn by CSS `::before` — no markup needed.
- The current page item gets `aria-current="page"`. It renders as plain text (no link), full colour, slightly bolder.
- Wraps on narrow viewports.
### Longer trail
```html
<nav data-role="breadcrumb" aria-label="breadcrumb">
<ol>
<li><a href="/">Home</a></li>
<li><a href="/docs/">Docs</a></li>
<li><a href="/docs/components/">Components</a></li>
<li aria-current="page">Navigation</li>
</ol>
</nav>
```
---
## Steps
A horizontal workflow sequence. Apply `data-role="steps"` to an `<ol>`. Each `<li>` takes a `data-status` attribute.
| `data-status` | Node | Label | Use |
|--------------|------|-------|-----|
| `complete` | ✓ (accent) | `var(--text-2)` | Finished step |
| `active` | number (filled) | bold, full colour | Current step |
| `pending` | number (dim) | `var(--text-3)` | Future step |
```html
<ol data-role="steps">
<li data-status="complete"><span>Plan</span></li>
<li data-status="complete"><span>Scaffold</span></li>
<li data-status="active"><span>Build</span></li>
<li data-status="pending"><span>Review</span></li>
<li data-status="pending"><span>Deploy</span></li>
</ol>
```
Steps distribute evenly across the available width. Connector lines between steps turn accent-coloured once the preceding step is `complete`.
### Agentic task pipeline
```html
<ol data-role="steps">
<li data-status="complete"><span>Wake</span></li>
<li data-status="complete"><span>Orient</span></li>
<li data-status="active"><span>Work</span></li>
<li data-status="pending"><span>Record</span></li>
<li data-status="pending"><span>Sleep</span></li>
</ol>
```
### Vertical layout
Add `data-layout="vertical"` for a top-down flow — useful in sidebars or narrow containers.
```html
<ol data-role="steps" data-layout="vertical">
<li data-status="complete"><span>Fetch task file</span></li>
<li data-status="complete"><span>Read source CSS</span></li>
<li data-status="active"><span>Implement components</span></li>
<li data-status="pending"><span>Build and verify</span></li>
<li data-status="pending"><span>Signal done</span></li>
</ol>
```
---
## Related
- [Data Attributes](/docs/data-attributes/) — `data-role`, `data-status`, and the full attribute vocabulary
- [Layouts](/docs/layouts/) — `data-layout` values including `vertical`
- [Components](/docs/components/) — callouts, tasks, and other component patterns