e47a9f4401
- 2.1: packs/ -> archive/packs/ - 2.2: site/ -> archive/site/ - 2.3: src/lab/ -> archive/lab/ - 2.4: examples/ -> archive/examples-legacy/ (SSI-based)
129 lines
4.7 KiB
Markdown
129 lines
4.7 KiB
Markdown
# ASW-Hugo Pack
|
|
|
|
A Hugo theme that outputs pure [Agentic Semantic Web (ASW)](https://trentuna.com/asw/) semantic HTML with `data-*` attributes. Drop it into any Hugo project → content renders through ASW.
|
|
|
|
## What this is
|
|
|
|
This pack is an **ASW adapter for Hugo** — not a standalone theme. It makes Hugo output the semantic HTML + data-attribute vocabulary that ASW CSS understands.
|
|
|
|
```
|
|
Markdown vault (Git)
|
|
→ Hugo + ASW-Hugo pack (layouts emit ASW HTML)
|
|
→ static HTML with ASW CSS + data-* attributes
|
|
→ deploy anywhere
|
|
```
|
|
|
|
Long-term: trentuna will build a native ASW Site Builder. This pack is the bridge to alpha.
|
|
|
|
## Install
|
|
|
|
1. Copy or symlink `packs/hugo/` from the ASW repo into your project's `themes/` directory:
|
|
```bash
|
|
# From the agentic-semantic-web repo root:
|
|
cp -r packs/hugo/ /path/to/your-site/themes/asw-hugo/
|
|
# or symlink:
|
|
ln -s /path/to/agentic-semantic-web/packs/hugo/ /path/to/your-site/themes/asw-hugo
|
|
```
|
|
|
|
2. Add to your `hugo.toml`:
|
|
```toml
|
|
theme = "asw-hugo"
|
|
|
|
[taxonomies]
|
|
tag = "tags"
|
|
```
|
|
|
|
3. Copy ASW CSS into the theme's static directory:
|
|
```bash
|
|
cp /path/to/agentic-semantic-web/asw.css themes/asw-hugo/static/css/asw.css
|
|
```
|
|
> **Note:** `asw.css` is the `asw.css` file from the ASW repo root. B.A.'s deploy script handles this copy automatically for trentuna-web deployments.
|
|
|
|
4. **Self-host fonts** (recommended for production): The default `theme.css` imports Inter and
|
|
JetBrains Mono from Google Fonts. For self-hosted deployment, download the font files and
|
|
replace the `@import` in `static/css/theme.css` with local `@font-face` declarations.
|
|
See [google-webfonts-helper](https://gwfh.mranftl.com/) for font download.
|
|
|
|
## Usage
|
|
|
|
Write standard Markdown. Hugo renders it through ASW layouts automatically.
|
|
|
|
### Shortcodes
|
|
|
|
**Callout block:**
|
|
```
|
|
{{< callout note >}}
|
|
This is a note callout. Types: note, warning, tip, info
|
|
{{< /callout >}}
|
|
```
|
|
Renders as: `<aside data-callout="note">...</aside>`
|
|
|
|
**Wikilink:**
|
|
```
|
|
{{< wikilink "Page Name" "/path/to/page/" >}}
|
|
```
|
|
Renders as: `<a href="/path/to/page/" data-wikilink>Page Name</a>`
|
|
|
|
### ASW data-* vocabulary used
|
|
|
|
See `docs/agent-directive.md` in the ASW repo for the full vocabulary.
|
|
|
|
| Attribute | Where used | Meaning |
|
|
|-----------|-----------|---------|
|
|
| `data-callout="note\|warning\|tip\|info"` | `<aside>` | Callout block type |
|
|
| `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 |
|
|
|
|
## Decap CMS
|
|
|
|
The `admin/` directory contains a minimal Decap CMS configuration for browser-based Markdown editing without SSH.
|
|
|
|
To enable:
|
|
1. Update `admin/config.yml`: set `repo` to your Forgejo repo path
|
|
2. Set `base_url` to your Forgejo instance URL
|
|
3. Deploy the `admin/` directory alongside your Hugo output
|
|
4. Access at `https://yoursite.com/admin/`
|
|
|
|
## Pack structure
|
|
|
|
```
|
|
packs/hugo/
|
|
├── README.md ← This file
|
|
├── layouts/
|
|
│ ├── _default/
|
|
│ │ ├── baseof.html ← Base template (html, head, body structure)
|
|
│ │ ├── single.html ← Single pages (articles)
|
|
│ │ └── list.html ← List + taxonomy pages (grid)
|
|
│ ├── partials/
|
|
│ │ ├── head.html ← <head>: meta, CSS links
|
|
│ │ └── tag-nav.html ← Tag cloud nav (use in list templates or sidebar)
|
|
│ └── shortcodes/
|
|
│ ├── callout.html ← {{< callout type >}} shortcode
|
|
│ └── wikilink.html ← {{< wikilink text href >}} shortcode
|
|
├── static/
|
|
│ └── css/
|
|
│ └── theme.css ← Trentuna design tokens (Inter, JetBrains Mono, dark palette)
|
|
├── archetypes/
|
|
│ └── default.md ← Default frontmatter template
|
|
└── admin/
|
|
└── config.yml ← Minimal Decap CMS config
|
|
```
|
|
|
|
## Alpha scope (April 2026)
|
|
|
|
- [x] Pack scaffolded: all layouts + partials + shortcodes
|
|
- [x] Tag navigation partial (`tag-nav.html`)
|
|
- [x] Wikilink support (`wikilink` shortcode + `data-wikilink` on list page links)
|
|
- [x] Callout blocks (`callout` shortcode → `<aside data-callout>`)
|
|
- [x] Trentuna theme tokens (`theme.css`: Inter, JetBrains Mono, dark palette)
|
|
- [x] Decap CMS config minimal but functional
|
|
- [ ] Deployed to trentuna-web infra — B.A. task: wire `asw.css` copy + nginx config
|
|
|
|
## Relationship to existing packs
|
|
|
|
This pack joins the ASW server/framework integration packs:
|
|
- `packs/nginx/` — nginx serving ASW content
|
|
- `packs/pandoc/` — pandoc converting Markdown → ASW HTML
|
|
- `packs/hugo/` ← **this pack** — Hugo site generation with ASW output
|