XU Mermaid Lazy Render

by xcloud-ai
5
4
3
2
1
Score: 50/100

Description

Obsidian plugin: defer Mermaid diagram rendering to viewport, so notes with many diagrams open instantly.

Reviews

No reviews yet.

Stats

0
stars
89
downloads
0
forks
54
days
51
days
51
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
4
commits

README file from

Github

流程图懒加载

[!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.

设置说明

设置项 默认值 说明
启用懒加载 开 关闭后恢复 Obsidian 原生渲染
渲染触发方式 自动 自动=滚动到视口附近渲染;手动=点击才渲染
预渲染边距 200px 距离视口多少像素内开始渲染
占位符显示图表类型 开 占位符上显示流程图类型
主题切换时重新渲染 开 切换明暗主题后自动重绘已显示的图

命令列表

命令 作用
渲染当前笔记中所有流程图 强制渲染当前笔记内所有未渲染的 Mermaid 图
渲染当前视口内的流程图 只渲染当前屏幕可见区域的流程图

技术说明

  • 通过 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

许可证

MIT License - Copyright (c) 2026 旭说