Repository navigation
fix(mermaid): render diagrams with @mermanjs/node for Merman 0.9 - #717
Conversation
@mermanjs/web 0.9 refuses to initialize outside a browser realm, so the build-time rehype plugin can no longer use it. Render with the native @mermanjs/node engine instead and keep @mermanjs/web only for the DOM-safety assertion, which still runs in Node. - replace initMerman/renderSvg with createNodeEngine().renderSvgSync - pass themes through presentation.theme.preset (host_theme was removed) - use assertSelfContainedSvgForDom (assertSafeSvgForDom was renamed) - derive the theme name type from BUNDLED_THEME_PRESETS
👷 Deploy request for demo-firefly pending review.Visit the deploys page to approve it
|
审阅者指南API更新公开的 Mermaid 主题类型,使其有效预设继承自 Merman 导出的捆绑预设元组。
API 的使用将 rehype 渲染器切换为 Merman 的 Node 引擎和 0.9 版渲染选项,并使用替代的 DOM 安全断言验证渲染后的 SVG。
配置添加 Node 引擎依赖项,并将 web 包升级到匹配的 Merman 0.9 版本。
锁文件和 vendored 代码更新锁文件,以记录 Merman 依赖项的变更。
提示和命令与 Sourcery 交互
自定义使用体验访问你的控制面板,以便:
获取帮助Original review guide in EnglishReviewer's GuideAPIUpdate the public Mermaid theme type to derive its valid presets from Merman’s exported bundled preset tuple.
Uses of the APISwitch the rehype renderer to Merman’s Node engine and 0.9 render options, and validate rendered SVGs with the replacement DOM-safety assertion.
ConfigurationAdd the Node engine dependency and upgrade the web package to the matching Merman 0.9 release.
Lock files and vendored codeUpdate the lockfile to record the Merman dependency changes.
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
There was a problem hiding this comment.
嗨——我发现了 1 个问题
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="src/plugins/rehype-mermaid.mjs" line_range="20" />
<code_context>
-});
+// @mermanjs/web 自 0.9 起仅支持浏览器运行时,构建期渲染改用 Node 原生引擎;
+// @mermanjs/web 仅用于校验输出的 SVG 可以安全插入 DOM
+const mermanEngine = await createNodeEngine();
/**
</code_context>
<issue_to_address>
**Astro builds abort on ARM64**
When the build runs on Linux ARM64, Windows ARM64, or another platform without a packaged Merman binary, `createNodeEngine()` rejects during top-level module evaluation, before the per-diagram `try`/`catch` can run, so Astro cannot load its config and the build aborts, even when there are no Mermaid diagrams.
Initialize `mermanEngine` only in a guarded or lazy path and handle missing native binaries so plugin import succeeds on unsupported platforms.
Also at `package.json:48`.
</issue_to_address>Sourcery 评估
需要人工审核。 有 1 个问题需要优先处理;现在,构建会在使用另一种 DOM 安全验证器检查后,将由新的原生引擎渲染的 SVG 插入页面。如果该验证器接受了旧检查会拒绝的不安全 SVG,这些标记就可能被输出到已部署的页面中;回滚可以避免后续构建继续产生此问题,但无法移除已部署的副本。
阻塞性问题:src/plugins/rehype-mermaid.mjs:20
Original comment in English
Hey - I've found 1 issue
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="src/plugins/rehype-mermaid.mjs" line_range="20" />
<code_context>
-});
+// @mermanjs/web 自 0.9 起仅支持浏览器运行时,构建期渲染改用 Node 原生引擎;
+// @mermanjs/web 仅用于校验输出的 SVG 可以安全插入 DOM
+const mermanEngine = await createNodeEngine();
/**
</code_context>
<issue_to_address>
**Astro builds abort on ARM64**
When the build runs on Linux ARM64, Windows ARM64, or another platform without a packaged Merman binary, `createNodeEngine()` rejects during top-level module evaluation, before the per-diagram `try`/`catch` can run, so Astro cannot load its config and the build aborts, even when there are no Mermaid diagrams.
Initialize `mermanEngine` only in a guarded or lazy path and handle missing native binaries so plugin import succeeds on unsupported platforms.
Also at `package.json:48`.
</issue_to_address>Sourcery assessment
Needs a human reviewer. 1 finding to address first, and the build now inserts SVGs rendered by a new native engine after checking them with a different DOM-safety validator. If that validator accepts unsafe SVG the old check rejected, the markup could be emitted into deployed pages; reverting prevents future builds but does not remove copies already deployed.
Blocking findings: src/plugins/rehype-mermaid.mjs:20
| }); | ||
| // @mermanjs/web 自 0.9 起仅支持浏览器运行时,构建期渲染改用 Node 原生引擎; | ||
| // @mermanjs/web 仅用于校验输出的 SVG 可以安全插入 DOM | ||
| const mermanEngine = await createNodeEngine(); |
There was a problem hiding this comment.
🟡 中等 · Astro 构建在 ARM64 上中止
当构建在 Linux ARM64、Windows ARM64 或其他未提供 Merman 二进制文件的平台上运行时,createNodeEngine() 会在模块顶层求值期间拒绝执行,此时针对每个图表的 try/catch 尚无法运行。因此 Astro 无法加载其配置,构建会中止,即使项目中没有任何 Mermaid 图表也是如此。
仅在受保护或惰性执行的路径中初始化 mermanEngine,并处理原生二进制文件缺失的情况,以便插件能够在不受支持的平台上成功导入。
package.json:48 处也有此问题。
提供给 AI 代理的提示
在 `src/plugins/rehype-mermaid.mjs` 第 20 行:
**Astro 构建在 ARM64 上中止**
当构建在 Linux ARM64、Windows ARM64 或其他未提供 Merman 二进制文件的平台上运行时,`createNodeEngine()` 会在模块顶层求值期间拒绝执行,此时针对每个图表的 `try`/`catch` 尚无法运行。因此 Astro 无法加载其配置,构建会中止,即使项目中没有任何 Mermaid 图表也是如此。
仅在受保护或惰性执行的路径中初始化 `mermanEngine`,并处理原生二进制文件缺失的情况,以便插件能够在不受支持的平台上成功导入。
`package.json:48` 处也有此问题。Original comment in English
🟡 Medium · Astro builds abort on ARM64
When the build runs on Linux ARM64, Windows ARM64, or another platform without a packaged Merman binary, createNodeEngine() rejects during top-level module evaluation, before the per-diagram try/catch can run, so Astro cannot load its config and the build aborts, even when there are no Mermaid diagrams.
Initialize mermanEngine only in a guarded or lazy path and handle missing native binaries so plugin import succeeds on unsupported platforms.
Also at package.json:48.
Prompt for AI agents
In `src/plugins/rehype-mermaid.mjs` at line 20:
**Astro builds abort on ARM64**
When the build runs on Linux ARM64, Windows ARM64, or another platform without a packaged Merman binary, `createNodeEngine()` rejects during top-level module evaluation, before the per-diagram `try`/`catch` can run, so Astro cannot load its config and the build aborts, even when there are no Mermaid diagrams.
Initialize `mermanEngine` only in a guarded or lazy path and handle missing native binaries so plugin import succeeds on unsupported platforms.
Also at `package.json:48`.|
The upstream checks on this PR fail before any step runs. GitHub reports "The job was not started because your account is locked due to a billing issue." so they don't reflect the change. To get a real result, I ran the same workflows in my fork. I fast-forwarded the fork's
The Astro Build jobs ran on |
Type of change
Checklist
Related Issue
None. This unblocks #716. That Dependabot PR bumps
@mermanjs/webfrom0.8.0-alpha.3to0.9.3, and the build then fails while loading the Astro config:Changes
Renaming the import is not enough. Merman 0.9 changed four things that affect
src/plugins/rehype-mermaid.mjs:@mermanjs/webis browser-only now.initMerman()throws fromassertBrowserRuntimeunder Node, and the README points Node hosts to@mermanjs/node.assertSafeSvgForDomwas split intoassertSelfContainedSvgForDomandassertNavigableSvgForDom.host_themerender option was replaced bypresentation.theme.preset.HostThemePresetNametype is gone. The entry point now exports theBUNDLED_THEME_PRESETStuple instead.This PR changes:
package.json: add@mermanjs/node@0.9.3and bump@mermanjs/webto0.9.3.rehype-mermaid.mjs: render throughcreateNodeEngine()andrenderSvgSync(). The Merman README marks the sync method as the one for SSG build paths, so the rehype plugin stays synchronous. Theme presets go throughpresentation.theme.preset, and the WASM loading code is removed.assertSelfContainedSvgForDom. It is the closer match to the old behavior because it forbids external navigation and resources.@mermanjs/webstays installed only for this check, which runs fine in Node (onlyinitMerman()is guarded).src/types/mermaidConfig.ts: deriveMermaidThemeNamefromtypeof BUNDLED_THEME_PRESETS. Valid values stay the same:editor-light,editor-dark,one-dark,gruvbox-light,gruvbox-dark,ayu-light,ayu-dark. An unknown preset still fails loudly (unsupported presentation.theme.preset).How To Test
pnpm check: 0 errors, 0 warnings, 0 hints.pnpm type-check: passes.biome check src scripts: no issues.pnpm build: completes. No[rehype-mermaid] Render failedlines appear./posts/markdown-mermaid/renders all 14 diagrams as light and dark SVGs (14mermaid-N-lightand 14mermaid-N-darkids, with no error fallback). I checked the page inastro previewin both color modes.Screenshots (if applicable)
N/A. The rendered output looks the same as before.
Additional Notes
@mermanjs/nodeloads a prebuilt native binary through optional dependencies. Binaries exist fordarwin-x64,darwin-arm64,linux-x64-gnu,linux-x64-musl, andwin32-x64-msvc. GitHub Actions, Vercel, Netlify, and Cloudflare Pages all build on linux x64. A linux-arm64 or win32-arm64 machine would fail withMermanMissingPlatformPackageError. With the WASM package, any platform worked.0.9.3instead of the newer0.10.0, which was published only a day ago.Sourcery 摘要
恢复与 Merman 0.9 兼容的构建时 Mermaid 图表渲染功能。
错误修复:
增强功能:
构建:
Original summary in English
Summary by Sourcery
Restore build-time Mermaid diagram rendering compatibility with Merman 0.9.
Bug Fixes:
Enhancements:
Build: