Skip to content

feat(studio): render Mermaid in Markdown previews - #4459

Open
ranxi2001 wants to merge 2 commits into
volcengine:mainfrom
ranxi2001:feature/studio-mermaid-preview
Open

feat(studio): render Mermaid in Markdown previews#4459
ranxi2001 wants to merge 2 commits into
volcengine:mainfrom
ranxi2001:feature/studio-mermaid-preview

Conversation

@ranxi2001

Copy link
Copy Markdown
Contributor

Description

Web Studio currently renders fenced mermaid blocks in resource Markdown files as syntax-highlighted source. This change detects those blocks at React Markdown's component boundary and renders them with the official Streamdown Mermaid plugin.

The diagram renderer is lazy-loaded only when a Mermaid fence is present. It follows the current light or dark application theme, localizes its loading and error states, preserves parser diagnostics and source on failure, and keeps wide diagrams readable inside a contained horizontal scroller.

Ordinary Markdown files keep the existing React Markdown path, including internal resource links, images, raw HTML sanitization, and non-Mermaid code highlighting.

Human Involvement

  • A human participated in the implementation or review loop
  • This PR was generated entirely by AI agents without human participation in the loop

Related Issue

Fixes #4453

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Refactoring (no functional changes)
  • Performance improvement
  • Test update

Changes Made

  • add the official @streamdown/mermaid renderer behind a lazy component;
  • render code.language-mermaid blocks using the current application theme and localized preview states;
  • preserve readable view-box sizing for wide diagrams within the preview's own horizontal scroll area; and
  • cover SVG rendering, theme changes, parser errors, non-Mermaid Markdown, internal links, and raw HTML safety behavior.

Testing

  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • I have tested this on the following platforms:
    • Linux
    • macOS
    • Windows

Local checks:

  • npm ci
  • npm test -- --maxWorkers=1 (57 files, 219 tests passed)
  • npm test -- src/routes/resources/-components/mermaid-diagram.test.tsx src/routes/resources/-components/file-preview.test.tsx src/routes/resources/-components/file-preview-html.test.tsx --maxWorkers=1 (3 files, 12 tests passed)
  • scoped ESLint and Prettier checks on changed TypeScript files
  • npm run build
  • git diff --check
  • Windows Chrome rendering at 1440px and 390px widths through CDP

A real Mermaid parser test renders the issue's flowchart into SVG under JSDOM; the test only supplies the SVG getBBox API that JSDOM does not implement. The ordinary file-preview production chunk remains 54.54 kB (18.76 kB gzip), and Mermaid remains lazy-loaded in separate chunks.

Full npx tsc --noEmit still reports the repository's existing diagnostics, with none in the changed file-preview or mermaid-diagram files. Vite retains its general warning for chunks over 500 kB. Repository-wide lint and format checks also remain red in unchanged files outside this PR.

Checklist

  • My code follows the project's coding style
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • Any dependent changes have been merged and published

Screenshots (if applicable)

Light theme

Desktop (English) Mobile (Simplified Chinese)
Mermaid preview in the light theme at desktop width Mermaid preview in the light theme at mobile width

Dark theme

Desktop (Simplified Chinese) Mobile (Simplified Chinese)
Mermaid preview in the dark theme at desktop width Mermaid preview in the dark theme at mobile width

The captures cover the issue chart, a wide flowchart, and localized invalid-source handling.

Additional Notes

The plugin's default Mermaid configuration uses securityLevel: "strict" and suppresses Mermaid's own error SVG. The resource preview owns its visible loading and error states; optional copy, download, fullscreen, and pan-zoom controls are outside this issue's rendering scope. Session messages, directory summaries, and JSONL previews are intentionally unchanged.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Backlog

Development

Successfully merging this pull request may close these issues.

Support Mermaid diagrams in Web Studio Markdown viewer

1 participant