Add Mermaid diagram support to docs.warp.dev with custom Warp branding - #515
Add Mermaid diagram support to docs.warp.dev with custom Warp branding#515warp-agent-staging[bot] wants to merge 5 commits into
Conversation
Add astro-mermaid + mermaid so fenced ```mermaid blocks render as client-side SVG diagrams instead of plain code blocks. The integration is registered before starlight() per its required ordering, and autoTheme keeps each diagram's base theme in sync with the site's data-theme attribute. Brand the diagram accent (border/line color) and font with Warp's Inter stack and accent blue as literal values, since Mermaid resolves theme colors through its own color-math library at init time and can't parse a CSS var() reference. Add a real example diagram to the software-factory page's "How it works" section, showing the inner-loop handoff between agents and the human review gate. Co-Authored-By: Warp Agent <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
@warp-agent-staging[bot] I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
|
This PR was generated with Warp.   |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds client-side Mermaid rendering to the Astro/Starlight docs site, configures Warp-branded theme variables, adds container styling, and includes a software-factory flowchart example. The implementation follows the required integration order, the content change fits the existing conceptual page, and I did not find security or spec-alignment blockers.
Concerns
- The only concern is non-blocking production console noise from astro-mermaid's default client logging; set
enableLog: falsein the integration config.
Verdict
Found: 0 critical, 0 important, 1 suggestions
Approve with nits
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>
![warp-agent-staging[bot]](https://avatars.githubusercontent.com/in/2196476?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds client-side Mermaid rendering with branded theming and a software-factory flowchart. It cannot be accepted while the committed lockfile prevents required CI from installing dependencies.
Concerns
Required CI fails at npm ci because package-lock.json is missing @emnapi/runtime@1.11.1; the Vercel deployment fails downstream. Regenerate the lockfile with a supported Node/npm version and re-run the checks.
Verdict
Checks: CI ❌ (npm ci lockfile mismatch) · typecheck ✅ · build ✅ (with the documented Node stack workaround; the default-stack failure reproduces on main) · visual proof ✅
Found: 1 critical, 0 important, 1 suggestions
Request changes
Review run
https://oz.staging.warp.dev/runs/019ffc0a-b5ff-72e7-9ea1-81da6514bb26
- Regenerate package-lock.json with a Node version in the repo's supported engines range (Node 22, matching CI). The previous lockfile was generated with an unsupported Node version and was missing a package-lock entry for @emnapi/runtime@1.11.1, which made `npm ci` fail in CI. Restored the original lockfile as a base and added only the two new packages, instead of a full re-resolution, to keep the diff minimal (no unrelated dependency bumps). - Move the example diagram off the software-factory page (an internal process page) to the handoff overview page, where it visualizes the three real handoff directions between a local session and a cloud run. - Redesign the diagram as a compact top-down flowchart (3 nodes) instead of a wide left-right one (7 nodes), fixing legibility: the previous diagram's SVG had to scale down significantly to fit the content column width, shrinking all diagram text well below normal body size. - Trim the astro-mermaid integration comments to the essential rationale (required integration order, and why colors are literal hex instead of CSS variables). Co-Authored-By: Warp Agent <agent@warp.dev>
|
Addressed: regenerated Fixed in commit 368165b. |
There was a problem hiding this comment.
Overview
This PR adds client-side Mermaid rendering with branded theming and a compact Handoff flowchart. The rework resolves the lockfile and logging findings, and the final implementation meets the ticket’s acceptance criteria.
Verdict
Checks: CI ✅ · clean install ✅ · typecheck ✅ · style/link checks ✅ · visual proof ✅
Found: 0 critical, 0 important, 0 suggestions
Approve
Review run
https://oz.staging.warp.dev/runs/019ffc0a-b5ff-72e7-9ea1-81da6514bb26
- The handoff diagram's self-loop edge ("Cloud to cloud") made Mermaid
reserve extra vertical space in the SVG's viewBox that the visible
content never filled, showing as a large blank gap below the diagram.
Redesign the flow as two sequential "Cloud agent run" nodes instead of
a self-loop, which represents the same three handoff directions
without the layout artifact.
- Add MermaidControls.astro, a small component (included once via the
site-wide footer) that layers zoom/pan/reset/fullscreen controls onto
rendered diagrams using svg-toolbelt (zero runtime dependencies,
~5KB). astro-mermaid/mermaid expose no such hooks themselves. Re-runs
after every astro-mermaid re-render, since a theme switch replaces a
diagram's entire DOM subtree and would otherwise drop the controls.
- Brand the controls' background, border, and hover colors to match the
site's existing code-block/copy-button chrome in both themes.
Co-Authored-By: Warp Agent <agent@warp.dev>
There was a problem hiding this comment.
Accepted
No blocking findings in the follow-up controls and spacing update.
Validated:
- Current CI, clean
npm ci, typecheck, docs style/link checks, and full production build. svg-toolbelt0.7.0 is MIT-licensed and adds no runtime dependencies.- The Handoff diagram has no stray bottom whitespace in light or dark themes.
- Zoom in/out, reset, fullscreen, and fullscreen exit work; one toolbar remains functional after a theme switch with no Mermaid/control console errors.
- The PR body includes refreshed video proof for this interactive follow-up.
Review run: https://oz.staging.warp.dev/runs/019ffc0a-b5ff-72e7-9ea1-81da6514bb26
svg-toolbelt's own stylesheet hardcoded a light-only look (white background, gray border, a column of individually-bordered squares) that didn't re-theme with the site and read as a foreign floating widget. Restyle it as a single pill matching .copy-dropdown-panel, with borderless, transparent buttons matching .copy-dropdown-item, using Warp's existing color tokens so it re-themes correctly. `!important` is used because the library's own CSS uses the same selector specificity and can load after this stylesheet in the bundle. Verified with computer use: the toolbar's computed background/border/ icon colors now differ correctly between dark and light theme, buttons are flat/borderless by default with a themed hover highlight, and zoom/pan/reset interactions are smooth with no jank (the library already disables its CSS transition during active drag and only applies it to discrete actions like reset). Co-Authored-By: Warp Agent <agent@warp.dev>
2 participants
Summary
Adds Mermaid diagram support to docs.warp.dev with custom Warp branding, a real example diagram on an existing feature page, and Warp-styled zoom/pan/fullscreen controls for viewing diagrams.
astro-mermaid+mermaidintegration (client-side rendering, no Playwright/Chromium build dependency) beforestarlight()inastro.config.mjs, per the integration's required ordering.autoTheme: truekeeps each diagram's Mermaid base theme (default/dark) in sync with the site'sdata-themeattribute, so diagrams automatically get a correctly light/dark background and text color.--sl-color-accent, inlined as#51a6ec— see code comment for why a literal hex is used instead of avar(--sl-color-*)reference)..mermaidcontainer CSS polish insrc/styles/custom.css(border/radius aligned with the existing code-block tokens, responsive SVG sizing).MermaidControls.astro(included once via the site-wide footer), which layers zoom/pan/reset/fullscreen controls onto rendered diagrams usingsvg-toolbelt(zero runtime dependencies, ~5KB) —astro-mermaid/mermaiddon't expose zoom/pan hooks themselves. Restyled to match the site's existing.copy-dropdown-panel/.copy-dropdown-itemchrome (a single pill with flat, borderless buttons) in both themes.Verification
npm run typecheck(astro check) — 0 errors, 0 warnings (pre-existing hints only).npm run build(astro build) — succeeds end to end (364 pages built) on Node 22 (matching CI'snode-version: '22').npm ci— installs cleanly on Node 22, matching the CI environment exactly.npm run lint(trunk check) — thetrunkCLI is not available in this sandbox, so this documented check could not be run here; it is left to the PR's CI as an available lint gate.config-only/pure data-copy-adjacent), so a unit test would only assert that a fenced code block renders — the real verification is the build succeeding and the rendered output, confirmed with computer-use visual proof below.Rework changes (cycle 3 — requester follow-up, PR already
review-done)svg-toolbelt's own stylesheet hardcoded a light-only look (white background, gray border, a column of individually-bordered squares) that didn't re-theme with the site. Restyled it as a single pill matching.copy-dropdown-panel, with borderless/transparent buttons matching.copy-dropdown-item, using Warp's existing color tokens (!importantis used because the library's own CSS shares the same selector specificity and can load after this stylesheet in the Vite bundle). Verified via DevTools computed styles that colors now genuinely differ between dark and light theme.Rework changes (cycle 2 — requester follow-up, PR already
review-done)docs.auto.shpage (zoom in/out, reset, fullscreen, in a hover toolbar), implemented with the small zero-dependencysvg-toolbeltlibrary rather than hand-rolling touch/keyboard/accessibility handling.Rework changes (cycle 1 —
blocked)package-lock.jsonwas generated with an unsupported Node version and was missing a lockfile entry for@emnapi/runtime@1.11.1, makingnpm cifail. Regenerated the lockfile on Node 22 (matching CI), adding only the two new packages on top of the original lockfile so there are no unrelated dependency bumps. Verifiednpm cinow succeeds.enableLog: falseon theastro-mermaidintegration to avoid production console noise (this was already applied via a bot-suggested commit before this rework pass).astro-mermaidintegration comments inastro.config.mjsto the essential rationale only.Originating thread: https://warpdev.slack.com/archives/C09BVK0PL3Y/p1786636610730459
Computer-use screenshots (2)
Dark theme: the restyled toolbar as a single dark pill with flat icon buttons, matching the site's existing copy-button chrome.
Light theme: the same toolbar re-themed to a white pill with dark icons after switching themes.