XU Mermaid Lazy Render

[!NOTE] 中文说明 流程图懒加载：视口外的 Mermaid 流程图延迟渲染，打开含大量图表的笔记不再卡顿。

打开一篇包含几十个 Mermaid 流程图的笔记时，Obsidian 会同步渲染所有图表，导致卡顿几秒才能正常操作。本插件接管 Mermaid 渲染，只渲染屏幕可见区域内的流程图，其余滚动到附近时再加载，大幅提升打开速度。不修改任何笔记内容，关闭插件即恢复原生渲染。

English description below for review purposes. / 以下为英文说明，用于过审。

XU Mermaid Lazy Render is an Obsidian plugin that defers rendering of off-screen Mermaid diagrams. Instead of rendering every diagram synchronously when a note opens (which freezes the UI for seconds on diagram-heavy notes), only diagrams in or near the viewport are rendered; the rest load on demand as you scroll. Your notes are never modified — disabling the plugin restores native rendering.

功能特性

• 视口懒渲染：默认只渲染屏幕可见的流程图，其余占位，滚动到附近才加载。
• 双触发模式：自动（滚动到视口附近渲染）或手动（点击占位符渲染）。
• 预渲染边距可调：设置距离视口多少像素内开始渲染，平衡加载时机与流畅度。
• 占位符显示图表类型：一眼看出是 flowchart 还是 sequenceDiagram。
• 主题切换自动重渲染：明暗主题切换后，已显示的流程图自动重绘适配新主题。
• 一键全渲染：命令面板提供「渲染当前笔记所有流程图」「渲染视口内流程图」。
• 点击看大图：正文中的流程图默认适配页宽保持版面整齐；点击流程图弹出全屏灯箱，可拖动平移、滚轮缩放、双击在「适应屏幕 / 原始尺寸」间切换，Esc 退出，超大图表也能看清。
• 零侵入：不修改笔记内容，关闭插件即恢复原生渲染；内置 SVG 消毒防 XSS。

Features

• Viewport lazy rendering: Only visible diagrams render by default; off-screen diagrams stay as placeholders until you scroll near them.
• Two trigger modes: Auto (render near viewport) or manual (click placeholder to render).
• Adjustable pre-render margin: Control how close to the viewport a diagram must be before rendering.
• Diagram type on placeholder: Quickly tell flowchart from sequenceDiagram at a glance.
• Auto re-render on theme change: Visible diagrams redraw when switching light/dark theme.
• Render-all commands: "Render all diagrams in current note" and "Render diagrams in viewport" via command palette.
• Click to enlarge: Diagrams fit page width inline to keep the layout tidy; click any rendered diagram to open a fullscreen lightbox with drag-to-pan, wheel-to-zoom, double-click to toggle fit/actual-size, and Esc to close — even oversized diagrams stay readable.
• Non-invasive: Never modifies your notes; built-in SVG sanitization for XSS protection.

安装

方式一：从 Obsidian 社区目录安装（推荐）

1. 打开 Obsidian 设置 → 社区插件
2. 点击「浏览」，搜索 "XU Mermaid Lazy Render"
3. 点击「安装」，然后「启用」

方式二：手动安装

1. 从 最新 Release 下载 main.js、manifest.json、styles.css 三个文件
2. 在 vault 中创建目录 .obsidian/plugins/mermaid-lazy-render/
3. 将三个文件放入该目录
4. 打开 Obsidian 设置 → 社区插件，找到 XU Mermaid Lazy Render 并开启

Installation

From Obsidian Community Directory:

1. Open Obsidian Settings → Community Plugins
2. Click "Browse" and search for "XU Mermaid Lazy Render"
3. Click "Install", then "Enable"

Manual Installation:

1. Download main.js, manifest.json, styles.css from the latest release
2. Put them in <vault>/.obsidian/plugins/mermaid-lazy-render/
3. Enable in Settings → Community Plugins

使用方法

1. 安装启用后无需任何配置，含大量 Mermaid 流程图的笔记打开速度显著提升。
2. 视口外的流程图显示为占位符，滚动到附近自动渲染（自动模式）或点击渲染（手动模式）。
3. 按 Ctrl+P 可使用「渲染当前笔记所有流程图」「渲染当前视口内的流程图」命令。
4. 在设置面板可调整触发方式、预渲染边距等参数。
5. 点击已渲染的流程图可全屏查看：鼠标拖动平移，滚轮/双指缩放，双击切换「适应屏幕 / 原始尺寸」，Esc 或点击空白处关闭。

[!NOTE] Obsidian 1.13+ 中 Mermaid 默认关闭，需先在 设置 → 编辑器 中开启 Mermaid，否则占位符会提示「Mermaid 未启用」。

Usage

1. Once enabled, no configuration is needed. Notes with many Mermaid diagrams open much faster.
2. Off-screen diagrams show as placeholders and render automatically when scrolled near (auto mode) or on click (manual mode).
3. Press Ctrl+P for "Render all diagrams in current note" or "Render diagrams in current viewport".
4. Adjust trigger mode, pre-render margin, etc. in the settings panel.
5. Click any rendered diagram for fullscreen viewing: drag to pan, wheel/pinch to zoom, double-click to toggle fit/actual-size, press Esc or click the backdrop to close.

设置说明

命令列表

技术说明

• 通过 registerMarkdownCodeBlockProcessor('mermaid', ...) 接管 Obsidian 内置 Mermaid 渲染器（与 Beauty Diagram / Beautiful Mermaid Renderer 同一机制）。
• 每个流程图用 MarkdownRenderChild 管理生命周期，文档关闭时自动断开 IntersectionObserver、取消渲染，无内存泄漏。
• 渲染使用 Obsidian 自带的 window.mermaid.render()，输出与原生一致；渲染前对 SVG 做消毒（移除 on* 事件属性、<script>/<iframe>、javascript: URL）。
• 主题切换通过 MutationObserver 监听 body.class 的 theme-light/theme-dark 变化，重渲染已显示的图。
• 不使用 Node/Electron API，支持桌面端与移动端（isDesktopOnly: false）。
• 与其他修改 Mermaid 的插件（如 Mermaid Next、Beauty Diagram）可能冲突，建议二选一。

致谢 / Credits

• 借鉴了社区插件 Beauty Diagram 和 Beautiful Mermaid Renderer 覆盖内置 mermaid 渲染器的实现思路。

许可证

MIT License - Copyright (c) 2026 旭说