Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 11 additions & 6 deletions site/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,12 +41,17 @@ production HTTP headers. Deployment is a separate operation.

## Design

The approved minimal documentation layout uses a 240px navigation rail, a reading
column, and a 180px outline. Native disclosures replace the rail below 900px and
the outline below 1200px. Article prose uses Inter Variable at 17px and 1.65 line
height. Literal code uses JetBrains Mono at 15px and 1.6 line height without
ligatures. Both fonts are pinned dependencies, copied locally with their
licenses. Only the prose font is preloaded.
The shared documentation shell uses a 240px navigation rail, a reading column,
and a 180px outline. Native disclosures replace the rail below 900px and the
outline below 1200px. The landing page (`index`) adds a brand-first full-bleed
hero before that shell: large **A7** mark, one lede, Get started / Tour CTAs, and
a full-width code sample. Safe-area insets, short-height orientation compaction, and
fold / dual-segment spanning rules live in `src/tailwind.css`.

Article prose uses Inter Variable at 17px and 1.65 line height. Literal code
uses JetBrains Mono at 15px and 1.6 line height without ligatures. Both fonts
are pinned dependencies, copied locally with their licenses. Only the prose
font is preloaded.

Light and dark tokens live in `src/tailwind.css`. The initial theme follows the
system; explicit preferences apply before paint and persist when storage is
Expand Down
4 changes: 3 additions & 1 deletion site/docs/research-decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@ Reviewed 2026-09-19. These decisions implement the user's approved option 2 plan

Use a persistent documentation rail, a readable article column, and an optional page outline. Collapse navigation into native disclosures on smaller screens so it works without JavaScript. Separate the guided tour from exhaustive language reference. This applies the distinction between learning and information retrieval in [Diátaxis](https://diataxis.fr/).

No option 2 concept image was located by the initial repository filename search. The written approved plan is the design authority. Existing screenshots under `docs/audits/2026-09-19/browser/` record the previous site, not acceptance of this rebuild. Do not claim a pixel comparison against an unavailable reference.
The 2026-11 landing + responsive pass keeps that IA. The home route adds a brand-first hero (large A7, one sentence, two CTAs, full-bleed code visual) before the shared shell. Responsive hardening covers safe-area insets, short-height orientations, local overflow for tables and code, and progressive fold / viewport-segment dual-pane rules. Fold hardware coverage is only as strong as the CSS APIs the browser exposes; record simulations separately from device claims.

No option 2 concept image was located by the initial repository filename search. The written approved plan is the design authority for the docs shell. The Project store brief `site-responsive-redesign.md` (approach 3) is the authority for the landing and fold/responsive additions. Existing screenshots under `docs/audits/2026-09-19/browser/` record the previous site, not acceptance of this rebuild. Do not claim a pixel comparison against an unavailable reference.

## Typography

Expand Down
7 changes: 3 additions & 4 deletions site/public/docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,10 @@ summary: An experimental systems language that compiles to Zig and native progra
order: 0
---

# A7 documentation
# A7

A7 is an experimental, statically typed systems language. Its Python compiler
checks `.a7` source and emits a single Zig file. Zig 0.17.1 builds the native
program. Start below, then read the tour or the language reference.
A7 checks `.a7` source in Python, emits one Zig file, and builds a native program
with Zig 0.17.1. Start below, then read the tour or the language reference.

## Start in two minutes

Expand Down
6 changes: 3 additions & 3 deletions site/public/docs/manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"schemaVersion": 1,
"sourceRevision": {
"kind": "documentation-sha256",
"value": "eb7189210095e32a41842c28da6d205770570dcbeda5d106094c47ea587d26dd"
"value": "37e9a5b449debb1d260b3cd415d31b797ecfcfdb60376e4c6626530c3b532dd6"
},
"qualification": "Documentation content digest, not a compiler verification result. Evidence links identify the source authority.",
"pages": [
Expand All @@ -16,8 +16,8 @@
"sections": [
{
"level": 1,
"id": "a7-documentation",
"text": "A7 documentation"
"id": "a7",
"text": "A7"
},
{
"level": 2,
Expand Down
7 changes: 3 additions & 4 deletions site/public/llms-full.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,10 @@

Source: https://code5717.github.io/a7-py/docs/index.md

# A7 documentation
# A7

A7 is an experimental, statically typed systems language. Its Python compiler
checks `.a7` source and emits a single Zig file. Zig 0.17.1 builds the native
program. Start below, then read the tour or the language reference.
A7 checks `.a7` source in Python, emits one Zig file, and builds a native program
with Zig 0.17.1. Start below, then read the tour or the language reference.

## Start in two minutes

Expand Down
89 changes: 76 additions & 13 deletions site/scripts/build.ts
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,37 @@ function navigation(active: string) {
.join("")}</section>`,
).join("");
}
function topbar() {
return `<header class="topbar"><a class="brand" href="${BASE}/">A7 <span>Documentation</span><span class="brand-tag">Experimental</span></a><div class="tools"><button type="button" data-search-open hidden>${icon("search")}<span>Search</span><kbd>Ctrl K</kbd></button><label class="theme-control" hidden>Theme <select aria-label="Color theme"><option value="system">System</option><option value="light">Light</option><option value="dark">Dark</option></select></label><a href="https://github.com/code5717/a7-py">GitHub</a></div></header>`;
}
function searchDialog() {
return `<dialog id="search" aria-labelledby="search-title"><div class="search-top"><h2 id="search-title">Search documentation</h2><button data-search-close type="button">Close</button></div><label for="search-input">Words, features, or identifiers</label><input id="search-input" type="search" autocomplete="off" spellcheck="false" placeholder="Types, generics, exit codes…" aria-controls="search-results"><p id="search-status" role="status" aria-live="polite"></p><ul id="search-results" aria-label="Search results"></ul><p class="search-help"><span><kbd>↑</kbd> <kbd>↓</kbd> Navigate</span><span><kbd>Enter</kbd> Open</span><span><kbd>Esc</kbd> Close</span></p></dialog>`;
}
function shell(
doc: Doc,
articleInner: string,
outline: string,
neighbors: string,
options: { mainTag: "main" | "div"; mainClass?: string } = {
mainTag: "main",
},
) {
const tag = options.mainTag;
const cls = options.mainClass ? ` class="${options.mainClass}"` : "";
const mainOpen =
tag === "main"
? `<main id="main" tabindex="-1"${cls}>`
: `<div${cls}>`;
const mainClose = tag === "main" ? "</main>" : "</div>";
const article = `<article><header class="article-meta"><span>${e(doc.group)}</span><a href="${BASE}/docs/${doc.slug}.md">Read Markdown</a></header>
<details class="mobile-outline"><summary>On this page</summary><nav aria-label="Page outline">${outline}</nav></details>
<div class="prose">${articleInner}</div>
<nav class="pager" aria-label="Previous and next pages">${neighbors}</nav>
<footer><a href="${BASE}/docs/${doc.slug}.md">Markdown</a><a href="${BASE}/llms.txt">Agent index</a><a href="${BASE}/docs/manifest.json">Manifest</a><a href="${doc.sources[0]}">Page source</a><a href="https://github.com/code5717/a7-py">GitHub</a></footer></article>`;
return `<div class="shell"><aside class="sidebar"><details class="navigation" open><summary><span>Documentation navigation</span><span class="navigation-current">${e(doc.nav)}</span></summary><nav aria-label="Documentation">${navigation(doc.slug)}</nav></details></aside>
${mainOpen}${article}${mainClose}
<aside class="page-outline"><nav aria-label="On this page"><h2>On this page</h2>${outline}</nav></aside></div>`;
}
function page(doc: Doc) {
const outline = doc.headings
.filter((h) => h.level === 2)
Expand All @@ -38,6 +69,7 @@ function page(doc: Doc) {
d
? `<a class="pager-link" href="${docHref(d.slug)}"><small>${label === "Previous" ? icon("left") : ""}${label}${label === "Next" ? icon("right") : ""}</small><span>${e(d.nav)}</span></a>`
: "<span></span>";
const neighbors = `${neighbor(docs[i - 1], "Previous")}${neighbor(docs[i + 1], "Next")}`;
let articleHtml = doc.html;
for (const id of doc.aliases) {
const target =
Expand All @@ -47,26 +79,57 @@ function page(doc: Doc) {
`<span id="${e(id)}" class="legacy-anchor" aria-hidden="true"></span>$1`,
);
}
return `<!doctype html>
<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
const head = `<!doctype html>
<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
<title>${e(doc.title)}${doc.slug === "index" ? "" : " · A7"}</title><meta name="description" content="${e(doc.summary)}">
<meta name="color-scheme" content="light dark"><meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)"><meta name="theme-color" content="#171819" media="(prefers-color-scheme: dark)">
<meta property="og:title" content="${e(doc.title)}"><meta property="og:description" content="${e(doc.summary)}"><meta property="og:type" content="website"><meta property="og:url" content="${ORIGIN + docHref(doc.slug).slice(BASE.length)}"><meta name="twitter:card" content="summary">
<link rel="canonical" href="${ORIGIN + docHref(doc.slug).slice(BASE.length)}"><link rel="alternate" type="text/markdown" href="${BASE}/docs/${doc.slug}.md" title="Markdown"><link rel="icon" href="${BASE}/favicon.svg">
<link rel="preload" href="${BASE}/fonts/inter-latin-opsz-normal.woff2" as="font" type="font/woff2" crossorigin>
<script>try{var t=localStorage.getItem('a7-theme');if(t==='light'||t==='dark')document.documentElement.dataset.theme=t}catch{}</script>
<link rel="stylesheet" href="${BASE}/assets/site.css"></head><body data-slug="${e(doc.slug)}">
<a class="skip" href="#main">Skip to content</a>
<header class="topbar"><a class="brand" href="${BASE}/">A7 <span>Documentation</span><span class="brand-tag">Experimental</span></a><div class="tools"><button type="button" data-search-open hidden>${icon("search")}<span>Search</span><kbd>Ctrl K</kbd></button><label class="theme-control" hidden>Theme <select aria-label="Color theme"><option value="system">System</option><option value="light">Light</option><option value="dark">Dark</option></select></label><a href="https://github.com/code5717/a7-py">GitHub</a></div></header>
<div class="shell"><aside class="sidebar"><details class="navigation" open><summary><span>Documentation navigation</span><span class="navigation-current">${e(doc.nav)}</span></summary><nav aria-label="Documentation">${navigation(doc.slug)}</nav></details></aside>
<main id="main" tabindex="-1"><article><header class="article-meta"><span>${e(doc.group)}</span><a href="${BASE}/docs/${doc.slug}.md">Read Markdown</a></header>
<link rel="stylesheet" href="${BASE}/assets/site.css"></head>`;
if (doc.slug === "index") {
const match = articleHtml.match(/^<h1([^>]*)>([\s\S]*?)<\/h1>\s*/);
if (!match) throw new Error("expected leading H1 in article HTML");
const headingText = match[2];
const body = articleHtml.slice(match[0].length);
const headingId = doc.headings[0].id;
const hero = `<section class="landing-hero" aria-labelledby="${e(headingId)}">
<div class="landing-hero-plane" aria-hidden="true"></div>
<div class="landing-hero-grid">
<div class="landing-copy">
<p class="landing-eyebrow">Experimental systems language</p>
<h1 id="${e(headingId)}">${headingText}</h1>
<p class="landing-lede">${e(doc.summary)}</p>
<p class="landing-ctas"><a class="landing-cta" href="${BASE}/start/">Get started</a><a class="landing-cta landing-cta-secondary" href="${BASE}/tour/">Tour</a></p>
</div>
<div class="landing-visual" aria-hidden="true">
<pre class="landing-code"><code>io :: import "std/io"

<details class="mobile-outline"><summary>On this page</summary><nav aria-label="Page outline">${outline}</nav></details>
<div class="prose">${articleHtml}</div>
<nav class="pager" aria-label="Previous and next pages">${neighbor(docs[i - 1], "Previous")}${neighbor(docs[i + 1], "Next")}</nav>
<footer><a href="${BASE}/docs/${doc.slug}.md">Markdown</a><a href="${BASE}/llms.txt">Agent index</a><a href="${BASE}/docs/manifest.json">Manifest</a><a href="${doc.sources[0]}">Page source</a><a href="https://github.com/code5717/a7-py">GitHub</a></footer></article></main>
<aside class="page-outline"><nav aria-label="On this page"><h2>On this page</h2>${outline}</nav></aside></div>
<dialog id="search" aria-labelledby="search-title"><div class="search-top"><h2 id="search-title">Search documentation</h2><button data-search-close type="button">Close</button></div><label for="search-input">Words, features, or identifiers</label><input id="search-input" type="search" autocomplete="off" spellcheck="false" placeholder="Types, generics, exit codes…" aria-controls="search-results"><p id="search-status" role="status" aria-live="polite"></p><ul id="search-results" aria-label="Search results"></ul><p class="search-help"><span><kbd>↑</kbd> <kbd>↓</kbd> Navigate</span><span><kbd>Enter</kbd> Open</span><span><kbd>Esc</kbd> Close</span></p></dialog>
main :: fn() {
io.println("Hello, World!")
}</code></pre>
</div>
</div>
</section>`;
return `${head}<body data-slug="index">
<a class="skip" href="#main">Skip to content</a>
${topbar()}
<main id="main" tabindex="-1">
${hero}
${shell(doc, body, outline, neighbors, {
mainTag: "div",
mainClass: "landing-docs",
})}
</main>
${searchDialog()}
<script src="${BASE}/assets/site.js" defer></script></body></html>`;
}
return `${head}<body data-slug="${e(doc.slug)}">
<a class="skip" href="#main">Skip to content</a>
${topbar()}
${shell(doc, articleHtml, outline, neighbors)}
${searchDialog()}
<script src="${BASE}/assets/site.js" defer></script></body></html>`;
}
await rm(DIST, { recursive: true, force: true });
Expand Down
8 changes: 7 additions & 1 deletion site/src/site.js
Original file line number Diff line number Diff line change
@@ -1,10 +1,16 @@
const navigation = document.querySelector(".navigation");
const mobileNavigation = matchMedia("(max-width: 899px)");
const foldNavigation = matchMedia(
"(spanning: single-fold-vertical), (horizontal-viewport-segments: 2)",
);
function adaptNavigation() {
if (navigation) navigation.open = !mobileNavigation.matches;
if (!navigation) return;
// Dual-pane fold layouts keep the rail open even when the CSS width is mid-range.
navigation.open = foldNavigation.matches || !mobileNavigation.matches;
}
adaptNavigation();
mobileNavigation.addEventListener("change", adaptNavigation);
foldNavigation.addEventListener("change", adaptNavigation);
const base = "/a7-py";
const known = [
"start",
Expand Down
Loading
Loading