docs: ADR-0042 — public website + documentation site plan
Planning artifacts for the first public website, recorded before any code is written. - ADR-0042: the decisions — Astro 5 + Starlight + Tailwind v4 (over SvelteKit); asciinema .cast demos reusable in docs (scripted-input driver, not history.log replay); in-page WASM playground deferred behind a stable demo seam, with the portable-core vs native-edge boundary recorded for a future ADR; portable static hosting (Vercel target); monorepo (website/); website is the canonical docs home; full-feature-set docs with "planned" callouts; user-facing copy uses no engine name and no "DSL"; install via prebuilt binaries + package managers. - docs/plans/20260604-adr-0042-website.md: implementation plan with the grounded documentation inventory and phases A–E. - website/STYLE.md: living documentation style guide + open-decisions log. - docs/adr/README.md: index updated for ADR-0042 (numerical order).
This commit is contained in:
claude@clouddev1
@@ -0,0 +1,172 @@
|
||||
# Plan: public website and documentation site
|
||||
|
||||
**Date:** 2026-06-04 · **Status:** ready to build
|
||||
|
||||
Decisions for this work are recorded in
|
||||
[ADR-0042](../adr/0042-public-website-and-documentation-site.md): Astro 5 +
|
||||
Starlight + Tailwind v4; asciinema demos reusable in docs; the in-page WASM
|
||||
playground deferred behind a stable demo seam; portable static hosting
|
||||
(Vercel target); monorepo (`website/`); website is the canonical docs home;
|
||||
full-feature-set docs with "planned" callouts; install docs cover prebuilt
|
||||
binaries + package managers. This plan is the *how*.
|
||||
|
||||
## Repository layout
|
||||
|
||||
The site lives under `website/` in this repo; the crate stays at the root.
|
||||
|
||||
```
|
||||
website/
|
||||
├── package.json # pnpm; astro, @astrojs/starlight, tailwind v4
|
||||
├── astro.config.mjs # Starlight integration + sidebar nav
|
||||
├── src/
|
||||
│ ├── pages/index.astro # marketing landing (custom, not Starlight)
|
||||
│ ├── components/
|
||||
│ │ ├── Demo.astro # demo SLOT — the WASM-playground seam
|
||||
│ │ └── Cast.astro # asciinema-player island wrapper
|
||||
│ ├── content/docs/ # Starlight MDX docs (the bulk of the work)
|
||||
│ └── styles/ # shared Tailwind + Starlight theme tokens
|
||||
├── public/casts/ # recorded *.cast asciinema files
|
||||
├── README.md # local dev + recording recipe
|
||||
└── STYLE.md # living documentation style guide
|
||||
```
|
||||
|
||||
Root `.gitignore` gains `website/node_modules`, `website/dist`,
|
||||
`website/.astro`.
|
||||
|
||||
## Documentation inventory (grounded — drives Phase D scope)
|
||||
|
||||
Built from `docs/handoff/55–57`, `docs/adr/*`, the command REGISTRY
|
||||
(`src/dsl/grammar/mod.rs:603`, which also auto-assembles in-app `help`), the
|
||||
`Command` enum (`src/dsl/command.rs:149`), and
|
||||
`src/friendly/strings/en-US.yaml` — **not** the coarse `requirements.md`
|
||||
checkboxes. Test state at survey time: **2151 passing, 0 failing, 1 ignored.**
|
||||
|
||||
**SHIPPED — document as-is (the doc core):**
|
||||
- Input modes: simple, advanced (SQL), `:` one-shot escape, `mode` command,
|
||||
per-project mode restore (ADR-0003/0015/0037).
|
||||
- Full simple-mode command surface: create/drop table; add/drop/rename/
|
||||
change column; add/drop 1:n relationship (named, ON DELETE/UPDATE
|
||||
CASCADE/SET NULL/RESTRICT, `--create-fk`); add/drop index; insert/update/
|
||||
delete (required WHERE + `--all-rows`; complex WHERE: AND/OR/NOT, LIKE,
|
||||
IS NULL, IN, BETWEEN); show table/data (where/limit); add/drop constraint;
|
||||
explain (ADR-0009/0013/0014/0025/0026/0028/0029).
|
||||
- Full advanced-mode SQL: CREATE/DROP/ALTER TABLE (cols, constraints, inline
|
||||
+ table FKs, rename, alter-column-type), CREATE [UNIQUE]/DROP INDEX; SELECT
|
||||
(joins, GROUP BY/HAVING, ORDER BY, LIMIT/OFFSET, UNION/INTERSECT/EXCEPT,
|
||||
WITH [RECURSIVE] CTEs); INSERT (multi-row, ON CONFLICT, RETURNING)/UPDATE/
|
||||
DELETE; full expression grammar incl. CASE, CAST, curated functions;
|
||||
EXPLAIN over SQL (ADR-0030–0039).
|
||||
- Types: all ten, advanced-mode SQL aliases, serial/shortid auto-fill
|
||||
(ADR-0005/0011/0017/0018). Constraints: PK incl. compound, NOT NULL,
|
||||
UNIQUE, CHECK, DEFAULT, FK (ADR-0029/0013/0035).
|
||||
- Undo/redo, history.log journal, replay, `--resume`, `--no-undo`
|
||||
(ADR-0006/0034). Projects & storage: project.yaml + CSV + history.log,
|
||||
save/save as/load/new/rebuild, temp projects, `--data-dir`
|
||||
(ADR-0004/0015). Export/import (zip), clipboard copy/copy all/copy last
|
||||
(ADR-0007/0041).
|
||||
- Friendly errors (all five categories) + validity indicator
|
||||
(ADR-0019/0027), DSL→SQL teaching echo (ADR-0038), EXPLAIN plan tree
|
||||
(ADR-0028), box-drawing tables (ADR-0016), tab completion + syntax
|
||||
highlighting + in-line editing (ADR-0022).
|
||||
|
||||
**DOCUMENT WITH CAVEAT:** `add unique index` is advanced-only; simple-mode
|
||||
table rename is intentionally absent (rename is `ALTER TABLE … RENAME TO`);
|
||||
FK references target single-column PKs only (compound-PK FK refs pending);
|
||||
`help <command>` detail and richer `hint` (H2/H3) still partial.
|
||||
|
||||
**OMIT or MARK "planned":** multi-line input (I1), readline shortcuts (I1b),
|
||||
in-flight cancellation / query timeout (I5/B3), `seed` (SD1), `m:n` (C4),
|
||||
one-step modify relationship (C3a), `show tables`/`relationships`/`indexes`
|
||||
(V5), ER-diagram view/export (V1/V3), session-log + Markdown export (V4).
|
||||
|
||||
**Mine verbatim for docs:** `en-US.yaml` `help.app.*`, `help.ddl.*`,
|
||||
`help.data.*`, `help.types_reference`, `parse.usage.*` (one-line syntax
|
||||
templates), `hint.*` — keeps docs and in-app help consistent.
|
||||
|
||||
## Phases
|
||||
|
||||
### A — Scaffold
|
||||
`pnpm create astro@latest` (Starlight template) in `website/`; `astro add
|
||||
tailwind` (Tailwind v4 via `@tailwindcss/vite`); add
|
||||
`@astrojs/starlight-tailwind`. Confirm `pnpm dev` serves and `pnpm build`
|
||||
emits a static `dist/`. Echo build steps for traceability.
|
||||
|
||||
### B — Landing page
|
||||
Custom `src/pages/index.astro` (Starlight owns `/docs/*`). Hero + value prop
|
||||
("learn relational databases by doing"), feature highlights from the
|
||||
inventory, an embedded demo cast above the fold. Use the `frontend-design`
|
||||
skill to avoid generic AI aesthetics; honour NFR-4/5/7 (distinctive design,
|
||||
meaningful colour, light/dark).
|
||||
|
||||
### C — asciinema recording workflow
|
||||
Record real `rdbms-playground` sessions to `public/casts/*.cast` using a
|
||||
**scripted-input driver** (e.g. `asciinema-automation`/autocast, or an
|
||||
expect/doitlive script) for paced, re-recordable demos. Record at a fixed
|
||||
sensible cols×rows; provide light + dark player themes. `Cast.astro` wraps
|
||||
`asciinema-player` as a `client:visible` island; the same component embeds
|
||||
casts inline in docs. Document the recipe in `website/README.md`.
|
||||
(`asciinema` 2.4.0 is installed.)
|
||||
|
||||
### D — Documentation (the bulk)
|
||||
Starlight sidebar, scoped from the inventory; built in priority order:
|
||||
- **Getting started** — install (prebuilt binaries + package managers),
|
||||
first project, simple vs. advanced mode.
|
||||
- **Concepts** — projects & storage; undo, history & replay.
|
||||
- **Simple-mode command reference** — full surface; syntax conventions;
|
||||
simple-command → SQL teaching echo.
|
||||
- **Advanced (SQL) mode** — full SQL DDL/DML/SELECT surface.
|
||||
- **Types**, **Relationships**, **Constraints**, **Indexes**, **Query plans
|
||||
/ EXPLAIN**.
|
||||
- **Working with the editor** — completion, highlighting, validity
|
||||
indicator, in-line editing.
|
||||
- **Errors explained** — the friendly error layer.
|
||||
- **Export / import & sharing** (E2 recipes), **clipboard**.
|
||||
|
||||
Build order: Tier 1 simple-mode reference + types + constraints + input
|
||||
modes + mined help/usage strings → Tier 2 advanced SQL + relationships +
|
||||
project lifecycle + undo/history → Tier 3 teaching echo + EXPLAIN + errors +
|
||||
completion/highlighting → Tier 4 clipboard + hints + editing.
|
||||
|
||||
Conventions live in the **living style guide** `website/STYLE.md` (binding
|
||||
rules from ADR-0042 §7 — no engine name, **no "DSL"**, "planned" callouts —
|
||||
plus finer conventions and an open-decisions log for depth/splitting/example
|
||||
dataset/etc. as they settle). Sources to mine: `src/dsl/command.rs`,
|
||||
`src/dsl/grammar/*`, the REGISTRY, `en-US.yaml`, `docs/adr/*`,
|
||||
`docs/simple-mode-limitations.md`.
|
||||
|
||||
### E — Hosting & portability
|
||||
Keep the default static build (no adapter); `dist/` deploys to Vercel or any
|
||||
static host. `website/README.md` notes the Vercel preset (root dir
|
||||
`website/`) and the one-line `@astrojs/vercel` switch if SSR is ever needed.
|
||||
|
||||
## Demo seam (WASM hook)
|
||||
|
||||
`Demo.astro` exposes a stable contract (`{ src, title, height, autoplay }`).
|
||||
At launch it renders `Cast.astro`; later a `Playground.astro` WASM island
|
||||
swaps in behind the same props on the landing page and in docs, with zero
|
||||
call-site changes. Boundary details are in ADR-0042 §3.
|
||||
|
||||
## Verification
|
||||
|
||||
- `pnpm dev` renders landing + docs; `pnpm build` emits a clean static
|
||||
`dist/` with no errors/warnings.
|
||||
- Landing shows at least one playing `.cast`; the same component renders a
|
||||
cast inline in a docs page (proves reuse).
|
||||
- Starlight link-check passes (broken internal links fail the build).
|
||||
- Docs grep clean of forbidden terms: **no "DSL"**, no engine name.
|
||||
- A `dist/` static deploy works on Vercel (manual import) — confirms
|
||||
portability. (No CI gate yet, per ADR-0042 §4.)
|
||||
|
||||
## Notes / recommendations (non-blocking)
|
||||
|
||||
- **Doc drift:** consider generating the command reference from source (the
|
||||
`help` REGISTRY / `en-US.yaml`) rather than hand-writing all of it.
|
||||
- **Accessibility/SEO:** pair each hero `.cast` with a text transcript or the
|
||||
equivalent docs snippet.
|
||||
- **Branding/domain & analytics** unspecified — assume none until decided;
|
||||
no third-party trackers without consent.
|
||||
- Tailwind v4 + Starlight have occasional theme-token friction; the
|
||||
`@astrojs/starlight-tailwind` plugin is the supported bridge.
|
||||
- Starlight ships local search (Pagefind) by default.
|
||||
- No `README.md` exists at the repo root yet — wanted for the destination
|
||||
repo; out of this plan's core scope but flagged.
|
||||
Reference in New Issue
Block a user