fix(docs): final passes on docs before publish#193
Merged
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThis PR integrates Mermaid diagram rendering with a unified design system, consolidates component mark usage, adds visual regression and audit scripts for diagrams, refactors branding asset generation to derive colors from CSS, and establishes repository-wide Markdown linting and editor tooling. ChangesMermaid Diagrams and Design System Integration
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Note 🎁 Summarized by CodeRabbit FreeYour organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login. Comment |
github-actions
Bot
added
documentation
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request completes the final polish of the documentation site, with a primary focus on high-quality, theme-aware Mermaid diagrams. It introduces a custom build-time integration to handle SVG patching, color variable mapping, and layout fixes. Additionally, it adds robust tooling for visual regression testing and updates existing documentation pages to leverage these new standardized styling components. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive build-time pipeline and styling polish for Mermaid diagrams in the WaveHouse documentation, including SVG post-processing, automated screenshot generation, and a layout/contrast audit script. While the implementation significantly improves diagram presentation and theme compatibility, several issues need to be addressed: a fragile regex in the SVG patcher that can misposition labels across anonymous subgraphs, potential crashes and parsing errors in the audit script's relative luminance calculator, a path-resolution bug on filesystems with spaces due to URL-encoded pathnames, and a performance bottleneck caused by running Playwright installation on every build. Verdict: Iterate
Address Gemini review on #193: - mermaid.mjs: add a negative lookahead to the cluster-centering regex so an untitled subgraph (a cluster with no .cluster-label) can no longer cause the scan to swallow the following cluster and reposition its label against the wrong rect. No-op for the current diagrams (every subgraph is titled); guards future ones. - mermaid-audit.mjs: make relLum() parse defensively (3/4/6/8-digit hex and rgb()/rgba(), comma or space separated, default black) so the dev-only audit tool can't crash on a null match or emit NaN. Output is identical for the 6-digit hex values rgbToHex() actually feeds it. The two other review comments (decodeURIComponent in screenshot-diagrams, prebuild playwright install) were assessed and declined — see PR threads. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Mermaid: extract the build-time plugin to the public Wave-RF/astro-themed-mermaid package (pinned github:Wave-RF/astro-themed-mermaid#v0.1.1) and delete the local copy at src/integrations/mermaid.mjs. WaveHouse keeps its own palette (src/config/mermaid-theme.mjs) and --wh-mermaid-* CSS vars; the package holds no colors. Drops the direct unist-util-visit dep (now transitive via the package). v0.1.1 fixes build-time font measurement (the inlined @font-face is registered under its primary family name) so node labels no longer clip. Branding: single-source brand kit. One mark.svg + the --brand-* palette in global.css drive scripts/branding/generate.sh (favicons, .ico, apple-touch, OG card, lockup), all written to public/branding/. <WaveMark/> inlines that same mark (currentColor, theme-aware) in SiteTitle and the new two-variant Footer (compact on doc pages, full marketing footer on splash). env.d.ts declares the Starlight virtual modules the Footer override re-renders so astro check passes. Old per-mode mark SVGs and root-level icons removed in favor of the generated kit. Verified: pnpm build passes, all internal links validate, diagrams render themed with correctly-sized boxes (no label clipping), brand kit regenerates. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…refactor
This branch reshuffled the branding assets and adopted astro-themed-mermaid
but left the [Unreleased] CHANGELOG describing the prior architecture, plus
two stale path references that this branch's file moves would break on merge:
- README front-page logo -> the two wavehouse-mark SVGs this branch moved
to docs/public/branding/mark-{light,dark}.svg (byte-identical blobs)
- AGENTS.md:123 'make docs-branding' comment -> mark.svg, which moved from
docs/scripts/branding/ to docs/src/assets/branding/
CHANGELOG [Unreleased]:
- extracted-packages entry: two -> three packages (add astro-themed-mermaid,
pinned #v0.1.1; note it replaced inline rehype-mermaid + dropped
unist-util-visit).
- branding-pipeline entry: sources -> src/assets/branding, assets ->
public/branding, colors single-sourced from --brand-* in global.css,
logo: block -> inline <WaveMark/> + favicon:, COLOR_* guidance fixed, 6->7
artifacts.
- footer entry: single footer -> compact/full split keyed on hasSidebar.
- relocated-pipeline sub-entry: corrected destination paths.
README: repoint <picture>/<img> logo to the byte-identical relocated blobs.
AGENTS.md: correct the make docs-branding source path.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adopt main's consolidated tooling (single root pnpm workspace, root Makefile, biome) while preserving this branch's docs work (astro-themed-mermaid, branding reorg, mermaid theming, content edits). Conflict resolutions: - docs/Makefile: accept main's deletion (targets folded into root Makefile) - pnpm-lock.yaml / pnpm-workspace.yaml: accept consolidation into the single root workspace; regenerated root lockfile to include astro-themed-mermaid - docs/package.json: keep astro-themed-mermaid; drop prebuild + packageManager (superseded by root workspace + Makefile install-playwright-docs target) - AGENTS.md: main's verb-first docs targets + branch's corrected docs/src/assets/branding/mark.svg path - CHANGELOG.md: main's workspace-structure entry (Changed) + branch's three-package / branding entry (Added), targets renamed to main's convention - generate.sh: branch's single-source description, command -> make branding-docs - architecture.md: main's WebSocket removal + branch's :::client mermaid styling Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Biome now lints/formats docs/** JS/TS/JSON (astro config, mermaid theme,
sidebar, worker, dev scripts) alongside the SDK and E2E harness; .astro
templates and Markdown stay out of Biome's scope by design.
Add markdownlint-cli2 for repo-wide Markdown linting, wired into make lint /
make fix next to Biome. Rules live in .markdownlint.json (so editor
extensions stay in sync), file globs in .markdownlint-cli2.jsonc. Disable
MD013 / MD033 / MD060 (ill-fitting for this repo's prose, README HTML, and
tables); exempt MD024 in CHANGELOG.md only (Keep a Changelog repeats section
headings per version). .mdx is not linted (markdownlint parses CommonMark).
- biome.json: add docs/**/*.{ts,js,mjs,cjs,json} + !**/.astro to includes
- mermaid-audit.mjs: biome fixes + matchAll refactor (noAssignInExpressions)
- sdk.md: tag the API-tree code fence as `text` (MD040)
- markdownlint --fix: blank lines around lists (cover.md), EOF newline (SDK README)
- package.json: lint:md / fix:md scripts + markdownlint-cli2 devDependency
- Makefile + AGENTS.md: document the extended coverage
Verified: make lint clean (Biome 57 files, markdownlint 31, golangci 0);
make build-docs builds 13 pages, valid links, working mermaid.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add source.fixAll.markdownlint to the [markdown] codeActionsOnSave block so the recommended DavidAnson.vscode-markdownlint extension applies the same fixes on save that `make fix` / `pnpm run fix:md` apply. Editor and CI already share rules (.markdownlint.json) + globs (.markdownlint-cli2.jsonc); this aligns on-save behavior too, matching the existing Go/TS pattern. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
area/sdk
VS Code's built-in Markdown validation resolves root-absolute links against the workspace folder, so Starlight routes like /api or /configuration#authentication were flagged broken though they're valid pages (no remap setting exists — microsoft/vscode#222020). Turn off file-link validation (the false-positive source) while keeping the accurate checks: same-page #anchors and reference links. Cross-page link/route/fragment correctness stays gated in CI by starlight-links-validator at `astro build` — the single source of truth. Also document that ownership split in .markdownlint-cli2.jsonc (markdownlint is style-only; it never resolved these links). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
TS widened the colorReplacements literal to string[][], which isn't assignable to the themedMermaid plugin's [string, string][] parameter — surfaced by `astro check`. Add a JSDoc tuple cast; no runtime change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
astro check (types + content-collection schemas) ran nowhere — `astro build` strips types without checking, so these errors were ungated. Add a docs `check` script and a `check-docs` make target, wired as a shared prereq of both `verify` and `build-docs`. As a prereq (not a parallel leaf) it runs once and serializes before the build, since astro check and astro build both write docs/.astro/ and must not race under `make -j`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
markdownlint-cli2 globs with dot:true, so `**/*.md` descends into hidden directories — including .worktrees/, where this repo nests git worktrees. Run from the main checkout that swept ~7k Markdown files across sibling branches into the lint set, and `make fix` (markdownlint --fix) would rewrite files belonging to other worktrees. Honor .gitignore (already excludes .worktrees/, tmp/, vendor/, dist/) and add an explicit **/.worktrees/** ignore as a fallback for when .gitignore is absent. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Static checks ran serially and noisily. They now fan out and report as a scannable checklist. Parallelism: - verify/ci/build-all/tools/fix fan out under `$(MAKE) -j $(JOBS)`. JOBS defaults to the host CPU count (getconf _NPROCESSORS_ONLN, falling back to 4), overridable; make self-caps at the ready-target count so it never oversubscribes — small machines run their core count, big ones the leaf count. - verify now schedules 8 atomic per-tool leaves (gofumpt, golangci-lint, Biome, markdownlint, govulncheck, astro check, tsc, go-mod-tidy) instead of bundling gofumpt+Biome and Biome+markdownlint+golangci, so the long pole is the slowest single tool, not the slowest group. Drops the redundant `biome format` pass — verify's `biome check` already verifies formatting. - fix fans out into three disjoint-file tracks: the ordered Go chain (tidy -> gofumpt -> goimports -> golangci --fix) in parallel with Biome and markdownlint. Output: - A `run` macro captures each check's output: green checkmark on success, red cross + the captured output (+ a fix hint) on failure. - pnpm install --reporter=silent and NODE_OPTIONS=--no-deprecation drop the install chatter and the astro DEP0205 deprecation warning. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ❌ Deployment failed View logs |
wavehouse-docs | 29a2f3a | Jun 03 2026, 02:39 PM |
Cloudflare Workers Builds can't build the docs site: rehype-mermaid renders diagrams to themed SVG at build time via headless Chromium, and the Workers Builds image has no browser and no root to apt-install one, so `astro build` fails there (and link validation then flags the unrendered pages as broken). The same build already succeeds in CI, where setup-env provides a cached Playwright Chromium. Deploy from the existing CI job instead: `make ci` already builds docs/dist/, so tail steps reuse that artifact (no rebuild, no extra runner) and run only when the whole pipeline is green — `wrangler deploy` on push to main, `wrangler versions upload` + a sticky preview comment on PRs. Deploys are skipped when no docs-affecting files changed, and on fork PRs (no secrets). Requires CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID repo secrets; Cloudflare Workers Builds must be disconnected from the wavehouse-docs Worker so it stops failing and doesn't double-deploy. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
the
github_actions
CI's setup-go installs the version from the go.mod `go` directive (go-version-file: go.mod). That directive was `1.26.3`, whose standard library trips govulncheck on GO-2026-5037 / GO-2026-5038 / GO-2026-5039 — turning the PR's CI run red. Those are fixed in Go 1.26.4 (local builds were already on it, which is why local vulncheck passed while CI did not). Bump the directive to `1.26.4` so the runner installs a patched toolchain. Patch-level bump only — no source changes; the released binaries pick up the patched stdlib too. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Tighten the landing page's conversion path ahead of the public launch:
- Add a problem->solution "versus" band under "Why WaveHouse exists" —
the failure modes of pointing a frontend straight at ClickHouse
(terracotta x) against what WaveHouse does instead (accent check),
condensed from the /why-wavehouse essay so the homepage carries the
argument on its own. Stacks vertically below 50rem.
- Trim the feature CardGrid from 8 to 6 (the differentiators that map to
the documented failure modes, plus the SDK); fold dedup + DLQ into a
one-line "Plus" that also surfaces named pipes.
- Trim "Where to next" from 6 to 4 (Configuration/Deployment stay in the
sidebar + footer).
- Replace the flat two-card "Project policies" block with a focused
closing CTA band that doubles as the honest alpha-maturity signal
("WaveHouse is alpha — and built entirely in the open").
New .wh-versus / .wh-closer styles in global.css follow the existing
token + comment conventions; both are static, so no reduced-motion
additions are needed.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…excludes Biome carried `biome init`'s scaffold defaults (vcs.enabled=false, useIgnoreFile=false) plus a hand-maintained `files.includes` exclude list. Because Biome wasn't reading .gitignore, that list had to enumerate every generated/vendored dir by hand — and it missed two that match the source globs: `docs/.wrangler/` (the wrangler dev/preview bundle) and `docs/screenshots/audit.json` (mermaid-audit output). The .wrangler bundle tripped `make verify` (biome check) with 7 errors the moment anyone ran the docs preview locally; the audit JSON was being linted too and only passed by luck. Turn vcs.enabled + useIgnoreFile on and drop the explicit excludes. Biome now derives its ignore set from .gitignore — root + nested docs/.gitignore, the source of truth the repo already maintains — so .wrangler, screenshots/, and any future generated dir are excluded automatically, with no parallel list to keep in sync. Matches markdownlint, which is already gitignore-aware. Verified from inside a git worktree (.git is a pointer file, not a dir): Biome reads the ignore files correctly and checks 56 source files (was 60 with the .wrangler bundle included). Full `make verify` is green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
American spelling, consistent with the rest of the docs. Comment-only — no rendered output changes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Resolves the CHANGELOG.md [Unreleased] conflict: keeps this branch's "Lint/format coverage" + docs-deploy-from-CI-job entries alongside main's new per-table-batching (#192) and health-endpoints (#213) entries, and reconciles the stale "Project policies CardGrid" wording (that homepage element was replaced by the closer call-to-action band on this branch). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
📚 Docs preview is live: https://8f9674a6-wavehouse-docs.wave-rf.workers.dev Updated for commit 6929e93 |
The description: field contained an unescaped ': ' (colon-space) in
'...pre-push-reviewer: in default...', which YAML parsed as a nested
mapping. Claude Code then dropped docs-reviewer from the agent registry
('Agent type docs-reviewer not found'), so the new mandatory docs gate
could never run. Rephrased the description to plain YAML-safe text
(verified it parses). Caught by the pre-push trial of the gate itself.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…nks, make clean) Pre-push self-review (pre-push-reviewer + docs-reviewer) surfaced four fixable findings on this branch (the license MIT/Apache-2.0 contradiction is separate — it resolves when origin/main #266 merges in): - CHANGELOG: no [Unreleased] entry for the first-boot trial policy, the standalone-stack compose wiring, or the http_scheme doc catch-up from d7ee36e. Add an Added bullet (CHANGELOG is in the docs-prose denylist, so the docs gate can't catch this — the code reviewer did). - clients/ts/README.md: E2E path said `tests/sdk/` (actual: `tests/e2e/sdk/`), and the Development Guide + SDK API Reference links pointed at non-existent `../../docs/{development,sdk}.md` repo paths — also broken on npmjs.com where this README is published. Repoint to the live https://wavehouse.dev/ URLs. - development.md: `make clean` row omitted `docs/dist/`, which `make clean` removes (Makefile help and deployment.md already list it). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…merge Merging origin/main brought in the repo-wide MIT->Apache-2.0 relicense (#266), which flipped LICENSE, the README badge/text, the SDK README, the JSON-LD + stat card, and why-wavehouse. But two license mentions live in branch-authored prose that #266 never saw (added in this branch's launch-sharpening work), so the merge resolution kept them as "MIT-licensed": - README.md:124 (Project status blurb) - docs/src/content/docs/index.mdx:158 (homepage closer) Both now read "Apache-2.0-licensed", consistent with LICENSE/NOTICE and the rest of the docs. The remaining CHANGELOG "MIT" mentions are intentionally kept: the relicense entry itself and the genuinely-MIT external plugin packages. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
github-project-automation
Bot
moved this from In progress
to Done
in WaveHouse Task Board
EricAndrechek
added a commit
that referenced
this pull request
Jun 5, 2026
…#277) ## Summary Four change sets, one theme: the docs workflow now behaves like production, fast. **1. Production-faithful `make dev-docs`** (`docs/scripts/dev.mjs`, new): `astro dev` skips everything the Cloudflare Worker adds in production — `cloudflare-md-router` content negotiation (`.md` twins), the pagefind search index, `starlight-llm-tools` outputs — so the de-facto workflow had become manually cycling `make build-docs && make preview-docs`. The dev loop now rebuilds on save (debounced; mid-build saves coalesce) into a `.dev-dist/` staging dir, syncs into `dist/` only on green builds (plain node fs — no rsync or other external tools), and serves through `wrangler dev --live-reload` on :4321 (`DOCS_PORT` overrides): the browser refreshes itself per build, and a failed build keeps serving the last good site (red banner + terminal bell). `starlight-links-validator` is skipped in watch builds so mid-edit dangling links don't block previewing (`DOCS_WATCH_STRICT=1` keeps it on; CI and `make build-docs` enforce links unchanged). The raw HMR server stays available as `pnpm run start`. **2. Per-diagram Mermaid render cache**: every build re-rendered all 17 diagrams through headless Chromium, diagrams changed or not. `docs/astro.config.mjs` now uses [`astro-themed-mermaid` v0.2.0](Wave-RF/astro-themed-mermaid@938f765)'s `rehypeMermaid` export (released as part of this work) — `rehype-mermaid` behind a content-addressed per-diagram disk cache. Warm rebuilds drop 6–7s → ~3.7s, a single-diagram edit re-renders only its page, and output is byte-identical modulo SVG ids. Save → refreshed browser is ~4s end to end. **3. Theme-adaptive favicon that actually displays** (commit 19e7a10): four stacked causes peeled — #193 dropped the `sizes="any"` SVG link (Chromium then picks the `.ico`); Chromium rasterizes an SVG favicon once and never re-renders on theme flip (crbug.com/1208277); in-place `href` mutation is honored only transiently; and Chromium's scorer commits an exact-size `.ico` over a `sizes="any"` SVG (verified against the profile `Favicons` SQLite, contradicting the standard blog advice). Fixed via the restored icon-link pair, statically-colored `favicon-{light,dark}.svg` brand-kit variants, and a `Head.astro` live-swap script (fresh link node per repaint, `.ico` removed from live candidates). No-JS and Safari ≤18 keep working fallbacks. **4. CI/review-automation docs refresh** (commit 0b54c50): `development.md` §CI & review automation and `CONTRIBUTING.md` still described `pr-title.yml`/`Validate`, `Check`/`Build` checks, `project-orchestrator.yml`, and `label.yml` — all replaced by `housekeeping.yml` / the single `CI` job / native Projects v2 board workflows (May consolidation, #115). Rewritten against the live config, the 72-char title cap documented, and a Chromium misattribution corrected (`starlight-links-validator` needs no browser; only `rehype-mermaid` does). ## Test plan - Dev loop verified end-to-end in-session: wrangler hot-pickup of modified *and new* assets, `Accept: text/markdown` twin negotiation, `/llms.txt`, pagefind, failed builds keep serving the previous dist, file↔directory type-flip recovery in the sync, `DOCS_WATCH_STRICT=1` fails loudly on a planted broken link, SIGINT/SIGTERM/`pkill` teardown leaves no orphans - Mermaid cache profiled cold (5.8s, 17 entries harvested) and warm (~3.5s); cached output diffed byte-identical to uncached modulo ids; `astro:build:done` theme patch counts unchanged; v0.2.0 ships 12 unit tests covering hit/miss/harvest/re-id/corruption paths - Favicon: Chromium profile `Favicons` DB ground truth, Playwright DOM swap checks both directions + across view transitions, manual Brave/Firefox/Safari - Docs rewrite verified claim-by-claim against the live ruleset (`gh api`), `housekeeping.yml`, `ci.yml`, and `admin-approval.yml` by the pre-push review gate - `make ci` green for every pushed tree (tree-keyed markers); both pre-push reviewers (code + docs) at ship_it for HEAD ## Related issues - Builds on the brand kit (#142) and head cleanup (#193); favicon entry supersedes the wiring described in the branding-pipeline CHANGELOG entry - Docs refresh closes out staleness introduced by the workflow consolidation (#115) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Continuation of #187
Plan
Related Issues