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:
parent
1408a52e8b
commit
15a6db9c0e
GPG key ID:
F6E479DEFAB84D6E
31 changed files with 788 additions and 70 deletions
74
content/articles/asw-vocabulary.md
Normal file
74
content/articles/asw-vocabulary.md
Normal file
|
|
@ -0,0 +1,74 @@
|
|||
---
|
||||
title: "ASW Data-Attribute Vocabulary"
|
||||
description: "The data-* attributes emitted by the ASW-Hugo pack."
|
||||
date: 2026-04-08
|
||||
tags: [asw, html, reference]
|
||||
ai-disclosure: "generated"
|
||||
ai-model: "claude-sonnet-4-5"
|
||||
ai-provider: "Anthropic"
|
||||
|
||||
---
|
||||
|
||||
# ASW Data-Attribute Vocabulary
|
||||
|
||||
The ASW-Hugo pack emits these `data-*` attributes in its HTML output.
|
||||
|
||||
| Attribute | Element | Meaning |
|
||||
|-----------|---------|---------|
|
||||
| `data-callout="note"` | `<aside>` | Note callout block |
|
||||
| `data-callout="warning"` | `<aside>` | Warning callout |
|
||||
| `data-callout="tip"` | `<aside>` | Tip callout |
|
||||
| `data-callout="info"` | `<aside>` | Info callout |
|
||||
| `data-wikilink` | `<a>` | Internal vault-style link |
|
||||
| `data-role="tag-cloud"` | `<nav>` | Tag navigation |
|
||||
| `data-layout="grid"` | `<section>` | Grid layout for list pages |
|
||||
| `data-tag` | `<a>` | Tag label on links |
|
||||
|
||||
All styling comes from `asw.css` targeting these attributes — no CSS classes required.
|
||||
|
||||
## Example: Full Page Skeleton
|
||||
|
||||
A complete ASW page emitted by the Hugo pack looks like this:
|
||||
|
||||
```html
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Session Log · Vault</title>
|
||||
<link rel="stylesheet" href="/css/asw.css">
|
||||
</head>
|
||||
<body>
|
||||
<header>
|
||||
<nav>
|
||||
<ul><li><strong>Vault</strong></li></ul>
|
||||
<ul>
|
||||
<li><a href="/articles/">Posts</a></li>
|
||||
<li><a href="/notes/">Vault</a></li>
|
||||
</ul>
|
||||
</nav>
|
||||
</header>
|
||||
|
||||
<div data-layout="docs">
|
||||
<aside>
|
||||
<nav aria-label="Vault documentation" data-nav="sidebar">
|
||||
<ul>
|
||||
<li><a href="/notes/tasks/" aria-current="page">Tasks</a></li>
|
||||
<li><a href="/notes/wikilinks/">Wikilinks</a></li>
|
||||
</ul>
|
||||
</nav>
|
||||
</aside>
|
||||
|
||||
<article>
|
||||
<hgroup>
|
||||
<h1>Tasks</h1>
|
||||
<p>Render task lists with semantic state.</p>
|
||||
</hgroup>
|
||||
<!-- page content -->
|
||||
</article>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
Notice: no `class` attributes anywhere. The layout, sidebar, and navigation styles are all driven by element semantics and `data-*` attributes.
|
||||
39
content/articles/console-layout-test.md
Normal file
39
content/articles/console-layout-test.md
Normal 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.
|
||||
51
content/articles/getting-started.md
Normal file
51
content/articles/getting-started.md
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
---
|
||||
title: "Getting Started with ASW-Hugo"
|
||||
description: "How to set up the ASW-Hugo pack in your Hugo project."
|
||||
date: 2026-04-08
|
||||
tags: [setup, hugo, asw]
|
||||
ai-disclosure: "generated"
|
||||
ai-model: "claude-sonnet-4-5"
|
||||
ai-provider: "Anthropic"
|
||||
|
||||
---
|
||||
|
||||
# Getting Started with ASW-Hugo
|
||||
|
||||
The ASW-Hugo pack is a theme that outputs [Agentic Semantic Web](https://asw.trentuna.com/) semantic HTML from your Hugo Markdown content.
|
||||
|
||||
## Installation
|
||||
|
||||
1. Copy or symlink `packs/hugo/` from the ASW repo:
|
||||
```bash
|
||||
ln -s /path/to/agentic-semantic-web/packs/hugo/ themes/asw-hugo
|
||||
```
|
||||
|
||||
2. Set `theme = "asw-hugo"` in your `hugo.toml`.
|
||||
|
||||
3. Add tag taxonomy:
|
||||
```toml
|
||||
[taxonomies]
|
||||
tag = "tags"
|
||||
```
|
||||
|
||||
4. Wire ASW CSS:
|
||||
```bash
|
||||
cp /path/to/agentic-semantic-web/agentic.css \
|
||||
themes/asw-hugo/static/css/asw.css
|
||||
```
|
||||
|
||||
5. Build:
|
||||
```bash
|
||||
hugo
|
||||
```
|
||||
|
||||
## What you get
|
||||
|
||||
- Semantic HTML output: `<article>`, `<section data-layout="grid">`, `<aside data-callout>`
|
||||
- Tag navigation at `/tags/`
|
||||
- Callout blocks: `{{</* callout note */>}} ... {{</* /callout */>}}`
|
||||
- Wikilinks: `{{</* wikilink "Text" "/path/" */>}}`
|
||||
|
||||
{{< callout tip >}}
|
||||
The ASW-Hugo pack uses **system font stacks** by default — no external font loading required.
|
||||
{{< /callout >}}
|
||||
64
content/articles/html-landmarks.md
Normal file
64
content/articles/html-landmarks.md
Normal 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue