Add Mermaid diagram support to docs.warp.dev with custom Warp branding - #515
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>
- The fullscreen toolbar button used svg-toolbelt's default '⛶' glyph, which rendered as a missing-glyph box on systems without a symbol-font fallback for that character. Replaced it with an inline stroke SVG icon matching the site's existing icon convention (see CopyPageButton.astro). - The idempotency guard and the fullscreen background CSS rule both targeted '.svg-toolbelt-wrapper', a class the library only applies via its separate initializeSvgToolbelt() helper. MermaidControls.astro instead instantiates SvgToolbelt directly on pre.mermaid, which carries '.svg-toolbelt-container' instead — so the guard never actually prevented re-processing on every poll tick, and the themed fullscreen background rule never applied. Fixed both to target the class that is actually present. Co-Authored-By: Warp <agent@warp.dev>
Per explicit requester feedback (Slack), removed the integration-order/ hex-value comment above the mermaid() call in astro.config.mjs and the svg-toolbelt-wrapper/container comment in custom.css, since the requester considers this class of 'why we did it this way' comment unnecessary here. Did a follow-up pass over the rest of the diff's comments with the same stricter bar (only keep a comment if it guards against a specific regression, not just background context) and also removed: - the accent-blue label comment in astro.config.mjs, - the top-of-file rationale banner in MermaidControls.astro, - the descriptive prose in custom.css's Mermaid section banner (kept just the section title). Comments that document the exact bugs fixed in the previous rework pass (the fullscreen-icon glyph fix, the .svg-toolbelt-controls idempotency- guard fix, the MutationObserver/polling/DOMContentLoaded rationale) were kept, since removing them risks a future edit silently reintroducing those regressions. Co-Authored-By: Warp <agent@warp.dev>
…mermaid-diagram-support
Per explicit requester feedback (Slack: 'honestly i think you should probably just remove like basically all of the comments'), removed essentially every comment this PR added in MermaidControls.astro and custom.css, keeping only a single one-line note guarding the exact selector-mismatch bug already fixed once (.svg-toolbelt-container vs .svg-toolbelt-wrapper). Co-Authored-By: Warp <agent@warp.dev>
…mermaid-diagram-support
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#51a6ecsince Mermaid computes shades from this value at init time and can't consume a CSS custom property)..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).npm ci— installs cleanly on Node 22, matching the CI environment.Full rework history for this PR (four review/requester cycles) is tracked as a comment on the linked Linear ticket, QUALITY-1631.
Originating thread: https://warpdev.slack.com/archives/C09BVK0PL3Y/p1786636610730459
Computer-use screenshots (3)
Light theme: the diagram with the corrected toolbar.
Dark theme: the same diagram and toolbar, correctly re-themed.
Close-up confirming all 4 toolbar icons render correctly.