Skip to content

fix(mermaid): render diagrams with @mermanjs/node for Merman 0.9 - #717

Merged
CuteLeaf merged 1 commit into
CuteLeaf:masterfrom
hon454:fix/merman-0.9-migration
Nov 15, 2026
Merged

CuteLeaf merged 1 commit into
CuteLeaf:masterfrom
hon454:fix/merman-0.9-migration

Conversation

@hon454

@hon454 hon454 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Type of change

  • Bug fix (a non-breaking change that fixes an issue)
  • New feature (a non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Other (please describe):

Checklist

  • I have read the CONTRIBUTING document.
  • I have checked to ensure that this Pull Request is not for personal changes.
  • I have performed a self-review of my own code.
  • My changes generate no new warnings.

Related Issue

None. This unblocks #716. That Dependabot PR bumps @mermanjs/web from 0.8.0-alpha.3 to 0.9.3, and the build then fails while loading the Astro config:

[vite] The requested module '@mermanjs/web' does not provide an export named 'assertSafeSvgForDom'

Changes

Renaming the import is not enough. Merman 0.9 changed four things that affect src/plugins/rehype-mermaid.mjs:

  1. @mermanjs/web is browser-only now. initMerman() throws from assertBrowserRuntime under Node, and the README points Node hosts to @mermanjs/node.
  2. assertSafeSvgForDom was split into assertSelfContainedSvgForDom and assertNavigableSvgForDom.
  3. The host_theme render option was replaced by presentation.theme.preset.
  4. The HostThemePresetName type is gone. The entry point now exports the BUNDLED_THEME_PRESETS tuple instead.

This PR changes:

  • package.json: add @mermanjs/node@0.9.3 and bump @mermanjs/web to 0.9.3.
  • rehype-mermaid.mjs: render through createNodeEngine() and renderSvgSync(). The Merman README marks the sync method as the one for SSG build paths, so the rehype plugin stays synchronous. Theme presets go through presentation.theme.preset, and the WASM loading code is removed.
  • The SVG check now uses assertSelfContainedSvgForDom. It is the closer match to the old behavior because it forbids external navigation and resources. @mermanjs/web stays installed only for this check, which runs fine in Node (only initMerman() is guarded).
  • src/types/mermaidConfig.ts: derive MermaidThemeName from typeof 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 failed lines appear.
  • /posts/markdown-mermaid/ renders all 14 diagrams as light and dark SVGs (14 mermaid-N-light and 14 mermaid-N-dark ids, with no error fallback). I checked the page in astro preview in both color modes.
  • I also ran the same checks with all 14 updates from chore(deps): bump the minor-updates group across 1 directory with 14 updates #716 applied on top of this change. Everything passed.

Screenshots (if applicable)

N/A. The rendered output looks the same as before.

Additional Notes

  • @mermanjs/node loads a prebuilt native binary through optional dependencies. Binaries exist for darwin-x64, darwin-arm64, linux-x64-gnu, linux-x64-musl, and win32-x64-msvc. GitHub Actions, Vercel, Netlify, and Cloudflare Pages all build on linux x64. A linux-arm64 or win32-arm64 machine would fail with MermanMissingPlatformPackageError. With the WASM package, any platform worked.
  • Once this is merged, Dependabot should rebase chore(deps): bump the minor-updates group across 1 directory with 14 updates #716 without the Merman bump, and its CI should go green.
  • I stayed on 0.9.3 instead of the newer 0.10.0, which was published only a day ago.

Sourcery 摘要

恢复与 Merman 0.9 兼容的构建时 Mermaid 图表渲染功能。

错误修复:

  • 更新 Mermaid 图表渲染,以适配 Merman 0.9,确保服务端构建继续成功生成 SVG 图表。

增强功能:

  • 使用 Node 渲染引擎、当前主题配置和 SVG 验证 API,同时保留受支持的 Mermaid 主题名称。

构建:

  • 将 Merman 软件包升级至 0.9.3,并添加 Node 引擎依赖。
Original summary in English

Summary by Sourcery

Restore build-time Mermaid diagram rendering compatibility with Merman 0.9.

Bug Fixes:

  • Update Mermaid diagram rendering for Merman 0.9 so server-side builds continue to generate SVG diagrams successfully.

Enhancements:

  • Use the Node rendering engine and current theme configuration and SVG validation APIs while preserving supported Mermaid theme names.

Build:

  • Upgrade the Merman packages to 0.9.3 and add the Node engine dependency.

@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
@netlify

netlify Bot commented Nov 13, 2026

Copy link
Copy Markdown

👷 Deploy request for demo-firefly pending review.

Visit the deploys page to approve it

Name Link
🔨 Latest commit 0e8a51c

@sourcery-ai

sourcery-ai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

审阅者指南

API

更新公开的 Mermaid 主题类型,使其有效预设继承自 Merman 导出的捆绑预设元组。

  • src/types/mermaidConfig.ts L1-6, L14-16

API 的使用

将 rehype 渲染器切换为 Merman 的 Node 引擎和 0.9 版渲染选项,并使用替代的 DOM 安全断言验证渲染后的 SVG。

  • src/plugins/rehype-mermaid.mjs L1-2, L18-20, L38-60

配置

添加 Node 引擎依赖项,并将 web 包升级到匹配的 Merman 0.9 版本。

  • package.json L48-49

锁文件和 vendored 代码

更新锁文件,以记录 Merman 依赖项的变更。

  • pnpm-lock.yaml L74-79, L2232-2269, L8688-8711

提示和命令

与 Sourcery 交互

  • 触发新的审阅: 在拉取请求中评论 @sourcery-ai review。
  • 继续讨论: 直接回复 Sourcery 的审阅评论。
  • 根据审阅评论创建 GitHub issue: 回复审阅评论,让 Sourcery 根据该评论创建 issue。也可以回复审阅评论并输入 @sourcery-ai issue 来创建 issue。
  • 生成拉取请求标题: 在拉取请求标题的任意位置输入 @sourcery-ai,即可随时生成标题。也可以在拉取请求中评论 @sourcery-ai title,随时(重新)生成标题。
  • 生成拉取请求摘要: 在拉取请求正文中你希望摘要出现的位置输入 @sourcery-ai summary,即可随时生成 PR 摘要。也可以在拉取请求中评论 @sourcery-ai summary,随时(重新)生成摘要。
  • 生成审阅者指南: 在拉取请求中评论 @sourcery-ai guide,即可随时(重新)生成审阅者指南。
  • 解决所有 Sourcery 评论: 在拉取请求中评论 @sourcery-ai resolve,即可解决所有 Sourcery 评论。如果你已处理完所有评论且不想再看到它们,这项功能会很有用。
  • 忽略所有 Sourcery 审阅: 在拉取请求中评论 @sourcery-ai dismiss,即可忽略所有现有的 Sourcery 审阅。如果你想从头开始进行新的审阅,这项功能尤其有用——别忘了评论 @sourcery-ai review 来触发新的审阅!

自定义使用体验

访问你的控制面板,以便:

  • 启用或停用审阅功能,例如 Sourcery 生成的拉取请求摘要、审阅者指南等。
  • 更改审阅语言。
  • 添加、移除或编辑自定义审阅说明。
  • 调整其他审阅设置。

获取帮助

Original review guide in English

Reviewer's Guide

API

Update the public Mermaid theme type to derive its valid presets from Merman’s exported bundled preset tuple.

  • src/types/mermaidConfig.ts L1-6, L14-16

Uses of the API

Switch the rehype renderer to Merman’s Node engine and 0.9 render options, and validate rendered SVGs with the replacement DOM-safety assertion.

  • src/plugins/rehype-mermaid.mjs L1-2, L18-20, L38-60

Configuration

Add the Node engine dependency and upgrade the web package to the matching Merman 0.9 release.

  • package.json L48-49

Lock files and vendored code

Update the lockfile to record the Merman dependency changes.

  • pnpm-lock.yaml L74-79, L2232-2269, L8688-8711

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

嗨——我发现了 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


Sourcery 对开源项目免费——如果您喜欢我们的评审,欢迎分享 ✨
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


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

});
// @mermanjs/web 自 0.9 起仅支持浏览器运行时,构建期渲染改用 Node 原生引擎;
// @mermanjs/web 仅用于校验输出的 SVG 可以安全插入 DOM
const mermanEngine = await createNodeEngine();

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 中等 · 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`.

@hon454

hon454 commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

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 master to upstream 994c0b8d and opened a PR from this same head commit (0e8a51c3) in the fork: hon454#1. All checks pass:

Check Result
Astro Check for Node.js 22 ✅ pass
Astro Check for Node.js 23 ✅ pass
Astro Build for Node.js 22 ✅ pass
Astro Build for Node.js 23 ✅ pass
quality (Biome) ✅ pass

The Astro Build jobs ran on ubuntu-latest (linux x64), so they also confirm that the @mermanjs/node native binary installs and loads on CI.

@CuteLeaf
CuteLeaf merged commit 72f6edc into CuteLeaf:master Nov 15, 2026
1 of 6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants