Skip to content

Commit 6df21b1

Browse files
a2ml.net / k9-svc.net: SEO-max, downloads, share/RSS, roadmap (#452)
## Summary Modernises the a2ml.net and k9-svc.net site content per the short-term roadmap: SEO essentials, a downloadable-template area, social/RSS discovery, and a public roadmap page. - `templates/default.html`: canonical link, Open Graph + Twitter Card meta, schema.org JSON-LD, feed/sitemap discovery links, share row, nav additions (Downloads, Roadmap). - `site/downloads.md` (new): starter templates per strictness/trust level (individually and bundled as `.tar.gz`), served from `public/downloads/`. - `site/roadmap.md` (new): now/next/later, including a2mliser/k9iser mid-term and the owner's typed-routing-protocol research as an honestly-framed later direction. - `index.md`/`spec.md`/`start.md`: added missing frontmatter `description` (previously empty — meant empty SEO meta description), refreshed dates. - `scripts/deploy-site.sh` + `Justfile site-deploy`: build with ddraig-ssg, deploy via `deno run -A npm:wrangler pages deploy` (Deno's npm-compat layer, no npm/node_modules on disk). This is a **draft**: I could not do a full `ddraig build` verification before opening this, because the local Idris 2 toolchain binary was unexpectedly missing (`asdf` install present but no `idris2` executable) — looks like a concurrent/in-progress reinstall, not something I touched. I did statically verify: JSON-LD blocks are valid JSON (`jq empty`), and every `{{placeholder}}` used in the templates matches exactly the substitution set `ddraig`'s `applyTemplate` implements (confirmed by reading `Ddraig.idr`). Please run a real `ddraig build` once the toolchain is back before merging. Also note: the actual Cloudflare Pages deploy is separately blocked right now (API token invalid) — this PR only lands the site *content*; deployment is a follow-up once both the toolchain and the Cloudflare token are sorted. ## Test plan - [ ] `idris2 Ddraig.idr -o ddraig` compiles once the toolchain is available - [ ] `ddraig build a2ml/site out https://a2ml.net` and `ddraig build k9-svc/site out https://k9-svc.net` produce clean output (no leftover `{{...}}`, valid JSON-LD via `jq empty`) - [ ] W3C Nu validator clean on the built HTML - [ ] `just site-deploy` (in each site dir) once `CLOUDFLARE_API_TOKEN`/`CLOUDFLARE_ACCOUNT_ID` are valid 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent a44c93a commit 6df21b1

36 files changed

Lines changed: 1216 additions & 0 deletions

a2ml/Justfile

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,11 @@ docs:
193193
demo:
194194
@./scripts/build-demo-ddraig.sh
195195

196+
# Build the real a2ml.net site (site/) with ddraig-ssg and deploy it to
197+
# Cloudflare Pages. Requires CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID.
198+
site-deploy:
199+
@./scripts/deploy-site.sh
200+
196201
# Run vector checks (prototype runner)
197202
vectors:
198203
@echo "Running vector checks..."

a2ml/scripts/deploy-site.sh

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
#!/usr/bin/env bash
2+
# SPDX-License-Identifier: MPL-2.0
3+
# Build the a2ml.net site with ddraig-ssg and deploy it to the Cloudflare
4+
# Pages project "a2ml". Requires CLOUDFLARE_API_TOKEN (Pages:Edit) and
5+
# CLOUDFLARE_ACCOUNT_ID in the environment (e.g. `source ~/.secrets/cloudflare.env`).
6+
# wrangler is run via Deno's npm-compat layer (no npm/node_modules/package.json
7+
# on disk) per estate policy — "JS deps: Deno".
8+
set -euo pipefail
9+
10+
SITE_DIR="$(cd "$(dirname "$0")/.." && pwd)/site"
11+
DDRAIG_REPO="${DDRAIG_REPO:-$(cd "$(dirname "$0")/../../.." && pwd)/ddraig-ssg}"
12+
DDRAIG_BIN="$DDRAIG_REPO/build/exec/ddraig"
13+
OUT_DIR="${OUT_DIR:-$(mktemp -d)}"
14+
BASE_URL="https://a2ml.net"
15+
PROJECT_NAME="a2ml"
16+
17+
if [ ! -x "$DDRAIG_BIN" ]; then
18+
echo "Building ddraig-ssg..."
19+
( cd "$DDRAIG_REPO" && idris2 Ddraig.idr -o ddraig )
20+
fi
21+
22+
echo "Building $SITE_DIR -> $OUT_DIR (base $BASE_URL)"
23+
"$DDRAIG_BIN" build "$SITE_DIR" "$OUT_DIR" "$BASE_URL"
24+
25+
: "${CLOUDFLARE_API_TOKEN:?Set CLOUDFLARE_API_TOKEN (Pages:Edit) before deploying}"
26+
: "${CLOUDFLARE_ACCOUNT_ID:?Set CLOUDFLARE_ACCOUNT_ID before deploying}"
27+
28+
echo "Deploying $OUT_DIR to Cloudflare Pages project '$PROJECT_NAME'"
29+
deno run -A npm:wrangler@4 pages deploy "$OUT_DIR" \
30+
--project-name="$PROJECT_NAME" \
31+
--branch=main
32+
33+
echo "Done. Verify: curl -I $BASE_URL/ and $BASE_URL/.well-known/security.txt"

a2ml/site/assets/style.css

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
/* SPDX-License-Identifier: MPL-2.0 */
2+
/* Copyright (c) 2025-2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk> */
3+
/*
4+
* a2ml.net / k9-svc.net site theme — built on the ddraig-ssg AAA base.
5+
* WCAG 2.2 AAA: all text/UI colours contrast-verified >= 7:1 (light + dark),
6+
* focus ring >= 3:1, reduced-motion, reflow, >= 44px targets.
7+
*/
8+
9+
:root {
10+
--bg: #ffffff;
11+
--bg-soft: #f4f5f9;
12+
--bg-code: #eceef5;
13+
--fg: #1a1b26; /* 17.09:1 on --bg */
14+
--fg-muted: #3a3d4d; /* 10.74:1 on --bg */
15+
--link: #3730a3; /* 9.93:1 on --bg */
16+
--link-hover: #1f1b6b;
17+
--border: #5a5e73;
18+
--focus: #3730a3;
19+
--btn-fg: #ffffff; /* on --link (#3730a3) = 9.93:1 */
20+
--radius: 8px;
21+
--maxw: 70rem;
22+
--measure: 40rem;
23+
}
24+
@media (prefers-color-scheme: dark) {
25+
:root {
26+
--bg: #0e0f1a;
27+
--bg-soft: #181a2a;
28+
--bg-code: #1c1f33;
29+
--fg: #e6e8f2; /* 15.60:1 */
30+
--fg-muted: #c2c6d8; /* lightened for >=7:1 on --bg-soft */
31+
--link: #b9c2ff; /* 11.09:1 */
32+
--link-hover: #dde2ff;
33+
--border: #8c91ad;
34+
--focus: #b9c2ff;
35+
--btn-fg: #0e0f1a; /* dark text on light --link in dark mode */
36+
}
37+
}
38+
39+
*, *::before, *::after { box-sizing: border-box; }
40+
html { font-size: 100%; -webkit-text-size-adjust: 100%; }
41+
body {
42+
margin: 0;
43+
font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
44+
font-size: 1.0625rem; line-height: 1.6;
45+
color: var(--fg); background: var(--bg);
46+
overflow-wrap: break-word;
47+
}
48+
.container { width: 100%; max-width: var(--maxw); margin-inline: auto; padding-inline: 1.25rem; }
49+
50+
/* Skip link (2.4.1) */
51+
.skip-link { position: absolute; left: -9999px; top: 0; background: var(--link); color: #fff; padding: .75rem 1.25rem; border-radius: 0 0 var(--radius) 0; font-weight: 600; z-index: 100; min-height: 44px; line-height: 1.4; }
52+
.skip-link:focus { left: 0; }
53+
54+
/* Focus (2.4.7/2.4.11/2.4.13) */
55+
:focus-visible { outline: 3px solid var(--focus); outline-offset: 2px; border-radius: 2px; }
56+
a:focus, button:focus, [tabindex]:focus { outline: 3px solid var(--focus); outline-offset: 2px; }
57+
58+
/* Header / nav */
59+
.site-header { border-bottom: 1px solid var(--border); }
60+
.nav { display: flex; flex-wrap: wrap; align-items: center; gap: 1rem; padding-block: .75rem; }
61+
.brand { font-weight: 700; font-size: 1.2rem; color: var(--fg); text-decoration: none; }
62+
.nav-links { list-style: none; display: flex; flex-wrap: wrap; gap: .5rem 1.25rem; margin: 0; padding: 0; }
63+
.nav-links a, .brand { display: inline-flex; align-items: center; min-height: 44px; }
64+
65+
/* Links: underlined (1.4.1) */
66+
a { color: var(--link); text-decoration: underline; text-underline-offset: 2px; }
67+
a:hover { color: var(--link-hover); }
68+
.brand, .nav-links a, .btn { text-decoration: none; }
69+
.nav-links a:hover, .nav-links a:focus { text-decoration: underline; }
70+
71+
main { display: block; }
72+
.prose { padding-block: 2rem; }
73+
.prose h1 { font-size: 2.25rem; line-height: 1.2; margin: 0 0 1rem; }
74+
.prose h2 { font-size: 1.6rem; line-height: 1.3; margin: 2.25rem 0 .75rem; }
75+
.prose h3 { font-size: 1.25rem; margin: 1.5rem 0 .5rem; }
76+
.prose :is(h1,h2,h3,h4), .prose p, .prose li { max-width: var(--measure); }
77+
78+
/* Lede */
79+
.lede { font-size: 1.3rem; line-height: 1.5; color: var(--fg); max-width: var(--measure); margin: 0 0 1.5rem; }
80+
81+
/* Badges */
82+
.badges { display: flex; flex-wrap: wrap; gap: .5rem; margin: 1rem 0; padding: 0; list-style: none; }
83+
.badge { display: inline-flex; align-items: center; min-height: 1.9rem; padding: .25rem .7rem; border: 1px solid var(--border); border-radius: 999px; font-size: .85rem; color: var(--fg); background: var(--bg-soft); }
84+
85+
/* Buttons (>=44px target, 2.5.5) */
86+
.btn-row { display: flex; flex-wrap: wrap; gap: .75rem; margin: 1.5rem 0; }
87+
.btn { display: inline-flex; align-items: center; min-height: 44px; padding: .6rem 1.15rem; border-radius: var(--radius); font-weight: 600; border: 2px solid var(--link); }
88+
.btn-primary { background: var(--link); color: var(--btn-fg); }
89+
.btn-primary:hover { background: var(--link-hover); border-color: var(--link-hover); color: var(--btn-fg); }
90+
.btn-ghost { background: transparent; color: var(--link); }
91+
.btn-ghost:hover { background: var(--bg-soft); }
92+
93+
/* Cards */
94+
.cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr)); gap: 1rem; margin: 1.5rem 0; }
95+
.card { border: 1px solid var(--border); border-radius: var(--radius); padding: 1.25rem; background: var(--bg-soft); }
96+
.card h3 { margin: 0 0 .5rem; font-size: 1.1rem; }
97+
.card p { margin: 0; color: var(--fg); }
98+
99+
/* Code */
100+
code { background: var(--bg-code); padding: .15em .35em; border-radius: 4px; font-size: .9em; }
101+
pre { background: var(--bg-code); padding: 1rem; border-radius: var(--radius); overflow-x: auto; }
102+
pre code { background: none; padding: 0; }
103+
104+
/* Tables */
105+
.prose table { border-collapse: collapse; width: 100%; max-width: 100%; margin: 1rem 0; }
106+
.prose caption { text-align: left; font-weight: 600; color: var(--fg-muted); padding: .5rem 0; }
107+
.prose th, .prose td { border: 1px solid var(--border); padding: .5rem .75rem; text-align: left; }
108+
.prose th { background: var(--bg-soft); }
109+
110+
blockquote { margin: 1rem 0; padding: .5rem 1rem; border-left: 4px solid var(--link); color: var(--fg); background: var(--bg-soft); }
111+
img { max-width: 100%; height: auto; }
112+
hr { border: none; border-top: 1px solid var(--border); margin: 2rem 0; }
113+
.muted { color: var(--fg-muted); }
114+
115+
.site-footer { border-top: 1px solid var(--border); margin-top: 3rem; padding-block: 1.5rem; color: var(--fg-muted); font-size: .95rem; }
116+
.site-footer a { color: var(--link); }
117+
118+
@media (prefers-reduced-motion: reduce) {
119+
*, *::before, *::after { animation-duration: .001ms !important; animation-iteration-count: 1 !important; transition-duration: .001ms !important; scroll-behavior: auto !important; }
120+
}
121+
@media (max-width: 30rem) { .nav { gap: .5rem; } body { font-size: 1rem; } }

a2ml/site/downloads.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
2+
<!-- SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk> -->
3+
---
4+
title: Downloads
5+
site: A2ML
6+
description: Starter A2ML templates — lax, checked and profile examples — free to download and adapt.
7+
date: 2026-06-29
8+
---
9+
10+
# Downloads
11+
12+
<p class="lede">Starter templates for each strictness mode. Download one, adapt it, and tighten the guarantees as your document matures.</p>
13+
14+
<div class="cards">
15+
<div class="card">
16+
<h3>Lax example</h3>
17+
<p>Write freely, no structural enforcement.</p>
18+
<p><a class="btn btn-ghost" href="/downloads/lax-example.a2ml">Download .a2ml</a></p>
19+
</div>
20+
<div class="card">
21+
<h3>Checked example</h3>
22+
<p>Required sections exist, references resolve, IDs are unique.</p>
23+
<p><a class="btn btn-ghost" href="/downloads/checked-example.a2ml">Download .a2ml</a></p>
24+
</div>
25+
<div class="card">
26+
<h3>Profile example</h3>
27+
<p>A domain profile layered on the base vocabulary.</p>
28+
<p><a class="btn btn-ghost" href="/downloads/profile-example.a2ml">Download .a2ml</a></p>
29+
</div>
30+
<div class="card">
31+
<h3>All templates</h3>
32+
<p>The full set plus a README, bundled.</p>
33+
<p><a class="btn btn-primary" href="/downloads/a2ml-templates.tar.gz">Download .tar.gz</a></p>
34+
</div>
35+
</div>
36+
37+
## Licence
38+
39+
Templates are `MPL-2.0` (code); this page is `CC-BY-SA-4.0`.
40+
41+
## More tooling
42+
43+
Full implementations, editor support and CI actions are coordinated in the
44+
[a2ml-ecosystem](https://github.com/hyperpolymath/a2ml-ecosystem) hub — clone
45+
the repository directly if you want more than the starter templates above.

a2ml/site/index.md

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
2+
<!-- SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk> -->
3+
---
4+
title: A2ML
5+
site: A2ML
6+
description: A2ML is a lightweight, Djot-like markup that compiles into a typed, attested core, with progressive strictness from lax to fully attested.
7+
date: 2026-06-29
8+
---
9+
10+
# A2ML — Attested Markup Language
11+
12+
<p class="lede">A lightweight, Djot-like markup that compiles into a typed, attested core. Authoring stays simple; structural guarantees switch on when you want them.</p>
13+
14+
<div class="badges">
15+
<span class="badge">Spec v1.1.0</span>
16+
<span class="badge">Typed core</span>
17+
<span class="badge">Progressive strictness</span>
18+
<span class="badge">Byte-for-byte payloads</span>
19+
<span class="badge">MPL-2.0 / CC-BY-SA-4.0</span>
20+
</div>
21+
22+
<div class="btn-row">
23+
<a class="btn btn-primary" href="/start.html">Get started</a>
24+
<a class="btn btn-ghost" href="/spec.html">Read the spec</a>
25+
<a class="btn btn-ghost" href="https://github.com/hyperpolymath/a2ml-ecosystem">GitHub</a>
26+
</div>
27+
28+
## What it does
29+
30+
<div class="cards">
31+
<div class="card">
32+
<h3>Readable surface</h3>
33+
<p>Write a clean, Djot-like format. No ceremony when you don't need it.</p>
34+
</div>
35+
<div class="card">
36+
<h3>Typed, attested core</h3>
37+
<p>Required sections, resolved references and unique IDs — verified, not hoped for.</p>
38+
</div>
39+
<div class="card">
40+
<h3>Faithful payloads</h3>
41+
<p>Opaque content is preserved byte-for-byte for reliable embedding.</p>
42+
</div>
43+
<div class="card">
44+
<h3>Portable rendering</h3>
45+
<p>One source, many targets — HTML, Markdown and PDF pipelines.</p>
46+
</div>
47+
</div>
48+
49+
## Progressive strictness
50+
51+
A2ML lets you dial guarantees up as a document matures:
52+
53+
| Mode | Guarantee |
54+
|------|-----------|
55+
| **lax** | Parse and render; no structural enforcement. |
56+
| **checked** | Required sections exist, references resolve, IDs are unique. |
57+
| **attested** | Checked, plus a verifiable attestation over the typed core. |
58+
59+
## A taste
60+
61+
```a2ml
62+
# A2ML Overview
63+
64+
@abstract:
65+
A2ML is a typed, attested markup format. It verifies structure and references.
66+
@end
67+
68+
## Claims
69+
- Required sections must exist.
70+
- References must resolve.
71+
72+
@refs:
73+
[1] Attested Markup Language Spec (draft)
74+
@end
75+
```
76+
77+
## Downloads & roadmap
78+
79+
Grab a [starter template](/downloads.html) in whichever strictness mode fits, or see the [roadmap](/roadmap.html) for what's next — including an interactive teaching area and [a2mliser](https://github.com/hyperpolymath/a2mliser).
80+
81+
## Part of the standards estate
82+
83+
A2ML is a satellite of the [Hyperpolymath standards hub](https://github.com/hyperpolymath/standards). The normative specification, conformance vectors and profiles live there; this site is the front door.
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
-----BEGIN PGP SIGNED MESSAGE-----
2+
Hash: SHA512
3+
4+
# Security contact for a2ml.net — RFC 9116
5+
# https://a2ml.net/.well-known/security.txt
6+
7+
Contact: mailto:j.d.a.jewell@open.ac.uk
8+
Encryption: openpgp4fpr:4A03639C1EB1F86C7F0C97A91835A14A2867091E
9+
Expires: 2027-06-21T00:00:00Z
10+
Preferred-Languages: en
11+
Canonical: https://a2ml.net/.well-known/security.txt
12+
Policy: https://github.com/hyperpolymath/a2ml-ecosystem/security/policy
13+
Acknowledgments: https://github.com/hyperpolymath/a2ml-ecosystem/security/advisories
14+
-----BEGIN PGP SIGNATURE-----
15+
16+
iQIzBAEBCgAdFiEEljlFF1RJblHWtTfK0RkBfr9pWrEFAmo5ozcACgkQ0RkBfr9p
17+
WrH2ORAAvgcBt6nmPx96PfNW6iwOKulGyx5suCH7+vfNZY5Y91U2ONOgiskpA3Oc
18+
HLQ2j79cWv96C50SvWahHGu6xUCovMKPAJYpCeSV973mpsLGuxzOXghfTZw9re5F
19+
E1W3BuuSYCGsb04maxSw8uWZ9H/ik3JJnrvOiXEcxUihJlfJSsxy6ZXZ8WwC+ajO
20+
k90f2yaS/TN9JPgyXwH8WwaNeVh1ZnnWUSdfLVmCvu5aXp+J21EqlJBumO/HCTRe
21+
hh8ojRwr8BGib4jbaAfPRfOZ3VIs1JUx1cJuRGsn3BkqLWuIyIeP9Xw3AVEt4pbv
22+
9G/XYAz0MULTxqA7pJUtMwF91KOlZ24DtB0yxKjcXev8L/1vW7EU0pBsO140Kqhq
23+
ULpPos0LpO/bGgeOBSQr164XTNFcWrEBmLjN1Qyi7ZqdMqTU2cNyM+3KFyPiPfnM
24+
7cW7H7R8xhr/RTzN8zz0eJnOFmX3rVSy854CUW/kmTBU/5GhFFBP7YqB2QBACqqW
25+
g+DpKobebYdL+B1jokzu4umhLd37hssojOcm0RuS13Fz3JSkvYpDKKHEjTTUO/lY
26+
k8EuilmGKWFXNwwDhwLzrx307N+9gqoDwTKBkuOx8lj5IwjJXZvO1R6pWrIR8quF
27+
7It/9vKqNo0O2xoebNsDM5DAn2zCtViftOieM2Tjk+gtLuxQ5yo=
28+
=vBOZ
29+
-----END PGP SIGNATURE-----

a2ml/site/public/CNAME

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
a2ml.net
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
// SPDX-License-Identifier: CC-BY-SA-4.0
2+
// SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
3+
= A2ML starter templates
4+
5+
Three starting points for writing A2ML, one per strictness mode:
6+
7+
* `lax-example.a2ml` — write freely, no structural enforcement.
8+
* `checked-example.a2ml` — required sections, resolved references, unique IDs.
9+
* `profile-example.a2ml` — a domain profile layered on the base vocabulary.
10+
11+
Copy whichever matches where you want to start, then tighten as your document
12+
matures — that is the whole point of progressive strictness. See
13+
https://a2ml.net/start.html[Get started] and https://a2ml.net/spec.html[the
14+
specification] for the full picture. Templates are `MPL-2.0`; this note is
15+
`CC-BY-SA-4.0`.
1.32 KB
Binary file not shown.
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<!-- SPDX-License-Identifier: MPL-2.0 -->
2+
<!-- A2ML template: checked mode — required sections exist, references
3+
resolve, IDs are unique. Validate this with the A2ML checked-mode
4+
validator before publishing. -->
5+
# Release Notes
6+
7+
@abstract:
8+
What changed in this release, in one paragraph.
9+
@end
10+
11+
## Changes
12+
- Added profiles for domain validation. [1]
13+
- Resolved all cross-references.
14+
15+
@refs:
16+
[1] A2ML Spec v1.1.0 — Profiles section
17+
@end

0 commit comments

Comments
 (0)