Spec M27 — site/: a static site generator written in mc, the layout and the icon

mcsite (site/gen/*.mc, built by mc build site) #

• Input: site/site.toml (title, base URL, nav order, sections mapping docs/guide and docs/reference to URL paths, theme options), docs/**/*.md, site/templates/*.html, site/static/**.
• Markdown subset: ATX headings with ids, paragraphs, emphasis, inline code, links, images, ordered and unordered lists, blockquotes, tables (pipe), fenced code with language tag; ```mc fences are highlighted by the bundled lexer (token classes -> <span class="tok-...">), taught syntax highlighted when the fence names a taught compiler; #-directives and $holes classified.
• Output: site/public/ — one HTML per page, index.html, sitemap.xml, search.json (title, url, headings, first paragraph) with a small inline search script, 404.html, copied static/. Deterministic output (byte-identical across runs; no timestamps).
• Performance: whole site renders in well under a second; mcsite --check validates links.
• GitHub Pages: .github/workflows/site.yml builds mc from the seed (clang once), then mc build site, then deploys site/public (the owner wires the repository later).

Design (by the designer agent) #

• Layout: left navigation (collapsible on mobile), content column with generous measure, right "on this page" outline; code blocks with copy button; light/dark by system preference; system fonts.
• Identity: an SVG icon expressing mc (small, self-hosting, teachable — e.g. a glyph that contains its own smaller copy, or mc letterforms built from the instruction word grid), favicon set, social preview image. site/DESIGN.md documents palette, type scale and the icon rationale.
• Accessibility review with the design:accessibility-review skill before acceptance.

Template contract (decided 2026-09-03 after the designer's delivery; see site/README.md) #

• Placeholders: {{site_title}} {{base_url}} {{page_title}} (complete title composed by the generator, e.g. Getting started - mc), {{page_description}} (first paragraph, also og:description), {{page_url}} {{content}} {{nav}} {{toc}} {{prev_url}} {{prev_title}} {{next_url}} {{next_title}} {{edit_url}} {{year}} {{search}} (the header search form + inline script; empty when search is off).
• Conditional blocks <!--if name-->...<!--endif-->: the generator deletes the block when the placeholder is empty, otherwise removes only the markers (string work, no HTML parsing).
• URL layout: /, /guide/, /reference/, /examples/, /guide/<slug>/, /reference/<slug>/ (one directory per page with index.html), configured in site/site.toml.
• Sidebar section titles are links to the section index pages (so phones reach them).
• Outline hidden below 1200px (no duplicated ids); mobile menu is a CSS checkbox toggle.
• Icon: icon.svg (bracket containing a half-scale copy of itself, solid core), favicon.svg with one generation fewer, PNG 16/32/180/512 (icon-180 exported full-bleed), social.svg/png 1200x630.
• Checks: site/tools/checkhtml.py (structure, landmarks, ids, links to static files) and site/tools/contrast.py (every token color in both themes >= 4.5:1; measured table in DESIGN.md) run in mcsite --check; vnu conformance is used when installed, never required.
• site/public/ is gitignored; .claude/launch.json has site-preview (python http.server on 8765) to look at site/preview/*.html before the generator exists.

Acceptance #

mc build site renders every doc; mcsite --check clean; two consecutive builds byte-identical; HTML validated (tidy or a validator script), contrast and keyboard navigation reviewed; the icon delivered as icon.svg, favicon.ico/PNGs; screenshots attached to the report when a browser is available.

Edit this page