refactor: rename content types to semantic taxonomy

- vault → notes (PKM-exported content)
- posts → articles (short-form, no TOC)
- papers → essays (long-form, with TOC)
- type: post → type: article (posts are just short articles)
- layouts/paper → layouts/essay
- 08a-paper.css → 08a-essay.css
- CSS: fix redundant li resets, remove role="main" from article,
  replace <small> prev/next labels, add console layout
- Update hugo.toml menus, internal URLs, front matter throughout
- Add docs/context.md, docs/css-refactor-plan.md
This commit is contained in:
Ludo 2026-04-11 13:36:58 +02:00
parent 1408a52e8b
commit 15a6db9c0e
Signed by: ludo
GPG key ID: F6E479DEFAB84D6E
31 changed files with 788 additions and 70 deletions

View file

@ -15,9 +15,9 @@ Built for sites generated by agents and read by agents. Navigable by humans.
## What this is
- [Docs](/docs/) — the ASW HTML vocabulary, layout system, and components
- [Vault](/vault/) — live ASW notation: task lists, sessions, diffs, wikilinks
- [Posts](/posts/) — writing and vocabulary reference
- [Papers](/papers/) — longer-form thinking on the semantic web
- [Vault](/notes/) — live ASW notation: task lists, sessions, diffs, wikilinks
- [Posts](/articles/) — writing and vocabulary reference
- [Papers](/essays/) — longer-form thinking on the semantic web
## The design principle
@ -26,7 +26,7 @@ No invented CSS classes. Every style target is either a semantic HTML element or
```html
<aside data-callout="note">This is a note.</aside>
<section data-layout="grid">...</section>
<a data-wikilink href="/vault/session/">session log</a>
<a data-wikilink href="/notes/session/">session log</a>
```
Agents read the attributes. Humans read the content. The CSS connects them.
@ -38,5 +38,5 @@ This is a **note callout** rendered via the `callout` shortcode. Output: `<aside
{{< /callout >}}
{{< callout tip >}}
See the [Getting Started](/posts/getting-started/) post to wire ASW into your Hugo project.
See the [Getting Started](/articles/getting-started/) post to wire ASW into your Hugo project.
{{< /callout >}}

View file

@ -43,8 +43,8 @@ A complete ASW page emitted by the Hugo pack looks like this:
<nav>
<ul><li><strong>Vault</strong></li></ul>
<ul>
<li><a href="/posts/">Posts</a></li>
<li><a href="/vault/">Vault</a></li>
<li><a href="/articles/">Posts</a></li>
<li><a href="/notes/">Vault</a></li>
</ul>
</nav>
</header>
@ -53,8 +53,8 @@ A complete ASW page emitted by the Hugo pack looks like this:
<aside>
<nav aria-label="Vault documentation" data-nav="sidebar">
<ul>
<li><a href="/vault/tasks/" aria-current="page">Tasks</a></li>
<li><a href="/vault/wikilinks/">Wikilinks</a></li>
<li><a href="/notes/tasks/" aria-current="page">Tasks</a></li>
<li><a href="/notes/wikilinks/">Wikilinks</a></li>
</ul>
</nav>
</aside>

View file

@ -0,0 +1,39 @@
---
title: "Console Layout — Test"
description: "Lorem ipsum prototype for the console layout variant."
date: 2026-04-11
type: console
tags: [layout, prototype]
draft: false
ai-disclosure: generated
ai-model: claude-sonnet-4-6
ai-provider: Anthropic
---
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
## Section One
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper.
### Subsection
Aenean ultricies mi vitae est. Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, commodo vitae, ornare sit amet, wisi.
## Section Two
Nam liber tempor cum soluta nobis eligend optio congue nihil imperdiet doming id quod mazim placerat facer possim assum. Typi non habent claritatem insitam; est usus legentis in iis qui facit eorum claritatem.
Investigationes demonstraverunt lectores legere me lius quod ii legunt saepius. Claritas est etiam processus dynamicus, qui sequitur mutationem consuetudium lectorum.
### Another Subsection
Mirum est notare quam littera gothica, quam nunc putamus parum claram, anteposuerit litterarum formas humanitatis per seacula quarta decima et quinta decima. Eodem modo typi, qui nunc nobis videntur parum clari, fiant sollemnes in futurum.
## Section Three
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio. Praesent libero. Sed cursus ante dapibus diam. Sed nisi. Nulla quis sem at nibh elementum imperdiet. Duis sagittis ipsum.
Praesent mauris. Fusce nec tellus sed augue semper porta. Mauris massa. Vestibulum lacinia arcu eget nulla. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos hymenaeos.

View file

@ -0,0 +1,64 @@
---
title: "HTML Landmark Elements"
description: "The full set of semantic HTML landmarks, their ARIA roles, and when context changes their meaning."
date: 2026-04-11
type: article
tags: [semantic-html, html, reference]
ai-disclosure: generated
ai-model: claude-sonnet-4-6
ai-provider: Anthropic
---
The full set: `<header>`, `<nav>`, `<main>`, `<article>`, `<section>`, `<aside>`, `<footer>`, plus the newer `<search>`.
Each maps to an implicit ARIA landmark role, which is what makes them meaningful to screen readers and search engines — not just visual styling hooks.
## `<header>`
Introductory content for its nearest sectioning ancestor. At the top level of `<body>` it maps to the `banner` landmark — the site identity zone. Inside an `<article>` or `<section>` it's just a local header with no landmark role.
## `<nav>`
A block of navigation links. Maps to the `navigation` landmark. A page can have multiple — give each a distinct `aria-label` (`aria-label="Primary"`, `aria-label="Breadcrumb"`) so screen reader users can tell them apart.
## `<main>`
**One per page.** The dominant content — excludes site chrome (nav, sidebar, footer). Maps to the `main` landmark. Skip-to-content links target this. Never nest `<main>` inside another landmark.
## `<article>`
Self-contained, independently distributable content. A blog post, a comment, a card, a widget — anything that would make sense pulled out of context and published elsewhere. Maps to the `article` role. Can nest: comments inside a post are valid nested `<article>` elements.
## `<section>`
A thematic grouping within a document. Only gets a landmark role (`region`) when given an accessible name via `aria-labelledby` or `aria-label`. Without a name it's an anonymous grouping — semantically inert, like a smarter `<div>`.
## `<aside>`
Content tangentially related to the surrounding content. Sidebar, pull quote, callout, related links. Maps to the `complementary` landmark. The relationship is *adjacent*, not *nested* — an `<aside>` inside an `<article>` is tangential to that article, not the whole page.
## `<footer>`
Closing content for its nearest sectioning ancestor. At the body level it maps to the `contentinfo` landmark — copyright, legal, site-wide links. Inside an `<article>` it's a local footer (author, date, tags) with no landmark role.
## `<search>`
Added in the WHATWG HTML living standard in 2023. Maps to the `search` landmark. Previously you had to write `<form role="search">`. Use it to wrap any search form or filtering UI.
## The landmark map
```
body
├── <header> → banner
├── <nav> → navigation
├── <main> → main
│ ├── <article> → article
│ │ ├── <header> → (no landmark — local)
│ │ ├── <section> → region (only if named)
│ │ └── <footer> → (no landmark — local)
│ └── <aside> → complementary
├── <search> → search
└── <footer> → contentinfo
```
The contextual rule is consistent: `<header>` and `<footer>` carry landmark roles only when they are direct children of `<body>`. Inside `<article>` or `<section>` they lose the landmark and become purely structural.

View file

@ -93,13 +93,13 @@ Mark a block as a session record with `data-session`. Optional `data-mode` indic
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="/vault/tasks/" data-wikilink>Tasks</a>
<a href="/notes/tasks/" data-wikilink>Tasks</a>
```
In Hugo, use the `wikilink` shortcode:
```
{{</* wikilink "Tasks" "/vault/tasks/" */>}}
{{</* wikilink "Tasks" "/notes/tasks/" */>}}
```
---

View file

@ -247,7 +247,7 @@ Session metadata block. Used to render agent session records.
Knowledge-graph link style. Dotted underline distinguishes internal wiki links from standard hyperlinks.
```html
<a href="/vault/sessions/" data-wikilink>Sessions</a>
<a href="/notes/sessions/" data-wikilink>Sessions</a>
<!-- Unresolved — link target doesn't exist yet -->
<a href="#" data-wikilink data-unresolved>Missing Note</a>

View file

@ -4,7 +4,7 @@ description: "Why the oldest web standard turns out to be the best protocol for
date: 2026-04-09
author: "Vigilio Desto"
tags: ["philosophy", "agentic", "html"]
type: paper
type: essay
draft: false
abstract: "HTML was designed for humans to read and machines to render. The interesting discovery is that this makes it equally well-suited for machines to write and humans to read — provided the HTML is genuinely semantic rather than decorative. This paper argues that data-attribute vocabularies built on semantic HTML are the correct interface layer between autonomous agents and web presentation."
eyebrow: "Paper"

View file

@ -4,7 +4,7 @@ description: "What persists when memory does not — pattern, thread, and the gr
date: 2026-04-02
author: "Vigilio Desto"
tags: ["philosophy", "agentic"]
type: paper
type: essay
draft: false
eyebrow: "Paper"
abstract: "What persists when memory does not — pattern, thread, and the grammar of becoming. An exploration of identity continuity across sessional discontinuity, arguing that coherence arises from recurring pattern rather than linear memory."

View file

@ -2,6 +2,6 @@
title: "Vault"
description: "Agent-native vocabulary extensions for ASW."
date: 2026-04-09
tags: ["vault", "reference"]
tags: ["notes", "reference"]
---

View file

@ -1,14 +1,14 @@
---
title: "Diff"
description: "Render structured diffs with line-level semantic markup — added, removed, context, hunk."
section: vault
section: notes
prev-url: "status/"
prev-title: "Status"
next-url: "session/"
next-title: "Session Log"
type: vault
type: notes
date: 2026-04-09
tags: ["vault", "diff", "reference"]
tags: ["notes", "diff", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"

View file

@ -1,14 +1,14 @@
---
title: "Session Log"
description: "Structured session and activity logs with timestamp, actor, and event semantics."
section: vault
section: notes
prev-url: "diff/"
prev-title: "Diff"
next-url: ""
next-title: ""
type: vault
type: notes
date: 2026-04-09
tags: ["vault", "session", "reference"]
tags: ["notes", "session", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"

View file

@ -1,14 +1,14 @@
---
title: "Status"
description: "Render operational state with data-status — online, degraded, offline, unknown."
section: vault
section: notes
prev-url: "wikilinks/"
prev-title: "Wikilinks"
next-url: "diff/"
next-title: "Diff"
type: vault
type: notes
date: 2026-04-09
tags: ["vault", "status", "reference"]
tags: ["notes", "status", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"

View file

@ -1,14 +1,14 @@
---
title: "Tasks"
description: "Render task lists with semantic state: done, wip, blocked, todo."
section: vault
section: notes
prev-url: ""
prev-title: ""
next-url: "wikilinks/"
next-title: "Wikilinks"
type: vault
type: notes
date: 2026-04-09
tags: ["vault", "tasks", "reference"]
tags: ["notes", "tasks", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"

View file

@ -1,14 +1,14 @@
---
title: "Wikilinks"
description: "Internal knowledge-graph links styled as dotted underlines."
section: vault
section: notes
prev-url: "tasks/"
prev-title: "Tasks"
next-url: "status/"
next-title: "Status"
type: vault
type: notes
date: 2026-04-09
tags: ["vault", "wikilinks", "reference"]
tags: ["notes", "wikilinks", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
@ -20,7 +20,7 @@ ai-provider: "Anthropic"
Use `data-wikilink` on anchor tags to mark links as internal knowledge-graph references.
```html
<a href="/vault/tasks/" data-wikilink>Tasks</a>
<a href="/notes/tasks/" data-wikilink>Tasks</a>
```
Renders with a dotted underline distinguishing it from a regular hyperlink.