Handoff: `ai-system-design` docs on GitHub Pages (design prototype)¶

Purpose: Publish the Markdown in this repo to GitHub Pages while testing layout directions prototyped for giconsulting.net (options A-F and AIS-inspired reading patterns). This is not Novartis/SOW work and not the production gi-consulting marketing deploy.

Canonical path (committed): ai-system-design/docs/HANDOFF_github_pages_design_prototypes.md

Pair with: novartis/docs/HANDOFF_giconsulting_website_design_alternatives.md (design comparison) and novartis/docs/HANDOFF_giconsulting_website_publish_articles.md (Vercel / giconsulting.net recovery)

Goals (that thread)¶

Ship the existing docs/ corpus as a public static site (GitHub Pages).
Reuse one or more reading / docs layouts from the GI design demos (not the full consulting marketing site).
Prove which patterns (scroll reveal, TOC, catalog, glossary, docs sidebar) are worth porting to gi-consulting later.

Content inventory (this repo)¶

Path	Role
index.md	Site home; links into the doc set
docs/00-outline.md	Top-level IA / open questions
docs/01-production-requirements-runtime.md	Requirement to capability matrix
docs/02-llm-app-design-concepts.md	Concept framing
docs/references/*.md	Fetched article summaries + figures
docs/case-studies/*.md	Case-study bridges
docs/references/sources.md	Attribution

Design prototypes to test (source of truth: `gi-consulting`)¶

Local Next.js demos (same sample article; different chrome). Dev server (when running): http://localhost:3001/design-demos/ (hub) and /design-demos/a/ through /f/.

Option	Route	Best fit for this repo
A	`/design-demos/a/`	Landing + consulting chrome: low fit (marketing, not docs)
B	`/design-demos/b/`	Long-form article + colophon + glossary cards
C	`/design-demos/c/`	GI shell + Markdown + sticky TOC / scroll spy
D	`/design-demos/d/`	Docs subsite: sidebar, search, catalog table
E	`/design-demos/e/`	Single-scroll brochure: low fit
F	`/design-demos/f/`	Distill-style essay + margin TOC + footnotes

Recommended default for ai-system-design: D (reference library + case studies) with B or C for long chapters; skip A/E unless you add a one-page about strip.

Implementation files (copy or port, do not fork wholesale):

~/Transmute-Data/gi-consulting/pages/design-demos/ routes
~/Transmute-Data/gi-consulting/components/design-demos/ (OptionB.tsx through OptionF.tsx, DesignDemoEffects.tsx, ThemeToggle.tsx, useSectionSpy.ts, demoExtras.ts)
~/Transmute-Data/gi-consulting/styles/globals.css (.demo-* motion, catalog, glossary, TOC, responsive rules)

Reference site (AIS patterns, static): clone ~/Transmute-Data/ai-engineering-from-scratch; site root site/; local preview python3 -m http.server 8080 in site/. Scroll reveal uses IntersectionObserver in site/app.js plus .reveal in site/style.css (ported into MkDocs extra.js / extra.css).

GitHub Pages: what works with these components¶

Approach	Effort	Components / patterns
Static `docs/` + Jekyll (GitHub default)	Low	Markdown only; custom theme must re-implement `.demo-*` / AIS CSS in layouts
MkDocs Material to `gh-pages`	Medium	Sidebar, search, TOC natively; maps to option D without React
Eleventy / Astro in `site/`	Medium	Copy vanilla reveal + catalog JS from AIS / GI CSS
Next static export in `ai-system-design/web/`	Higher	Lift `components/design-demos/*` almost intact; build to `out/`; Pages from Actions
Submodule / copy AIS `site/`	Medium	Fast B-like reading; replace `data.js` with build from this repo Markdown

Constraint: GitHub Pages serves static files only. React demos in gi-consulting require a build step (Next export, Astro, or rewrite to HTML/CSS/JS). Do not expect to point Pages at gi-consulting dev server or raw pages/ without a generator.

Figures: keep under docs/references/ (or docs/assets/); use relative image paths so Pages base URL /repo-name/ resolves.

Suggested task order (Pages thread)¶

Initialize git first commit; create GitHub repo; set Pages source (gh-pages from Action).
Pick one spine MkDocs Material (this repo) or static site/ plus small build.js (AIS-style) or Next export subfolder.
Map IA 00-outline to home; 01/02 to chapters; references/ plus case-studies/ to catalog rows; optional glossary from 02 terms.
Port one layout implement D or C first; wire reveal, scroll progress, theme toggle as static JS if not using React.
Smoke test curl -sI published URL; mobile width; reduced-motion; internal links plus # anchors.
Record winner note which option ships to gi-consulting in the design-alternatives handoff.

Local commands (this repo)¶

cd ~/Transmute-Data/ai-system-design
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
mkdocs serve -a 127.0.0.1:8010
# open http://127.0.0.1:8010/
mkdocs build --strict

GI design demos (Next):

cd ~/Transmute-Data/gi-consulting && npm run dev -- -p 3001 -H 0.0.0.0
# open http://localhost:3001/design-demos/

AIS static reference:

cd ~/Transmute-Data/ai-engineering-from-scratch/site && python3 -m http.server 8080 --bind 127.0.0.1
# open http://127.0.0.1:8080/index.html

Out of scope¶

Novartis SOW / mcds POC specs.
Production giconsulting.net DNS/Vercel (see publish handoff).
Committing secrets; OAuth env vars on any host.

Index¶

Linked from the repository root README.md when the Pages experiment starts.

Handoff: ai-system-design docs on GitHub Pages (design prototype)¶