Add Mermaid Local Editor (Custom Template)#7626
Conversation
🦋 Changeset detectedLatest commit: 9f7ea0f The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
✅ Deploy Preview for mermaid-js ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
@mermaid-js/examples
mermaid
@mermaid-js/layout-elk
@mermaid-js/layout-tidy-tree
@mermaid-js/mermaid-zenuml
@mermaid-js/parser
@mermaid-js/tiny
commit: |
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## develop #7626 +/- ##
==========================================
- Coverage 3.31% 3.29% -0.03%
==========================================
Files 543 549 +6
Lines 57217 57652 +435
Branches 840 846 +6
==========================================
Hits 1898 1898
- Misses 55319 55754 +435
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
|
The latest updates on your projects. Learn more about Argos notifications ↗︎
|
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
|
This PR only adds a new template file and does not modify any existing rendering logic. The Argos visual diff appears to be unrelated to this change. Please confirm if new HTML templates are expected to be excluded from visual tests. |
knsv-bot
left a comment
knsv-bot
left a comment
There was a problem hiding this comment.
[sisyphus-bot]
Thanks for putting this together, @Dvurechensky — there's a clear amount of effort here, and I can see the appeal of having a zero-tooling local editor that just works against dist/. Before we get into the line-level feedback, there's a scope question that should probably be answered first, because a lot of the other items depend on it.
🎉 What's working well
- Defense-in-depth on the render path is genuinely well thought out: DOMPurify sanitization, followed by a second manual attribute strip, inserted into an iframe with
sandbox="allow-same-origin"(notably withoutallow-scripts). Even if sanitization were bypassed, the sandbox blocks script execution. That's the right instinct. deterministicIds: true+ theIS_E2Ebranch shows you thought about testability, which is nice to see in a standalone tool.- The localStorage-backed multi-diagram management is a neat UX touch.
The scope question (please read first)
This PR overlaps substantially with infrastructure the project already has:
demos/— a directory of ~25 pre-built HTML demo pages that already run against the dev build.pnpm dev— esbuild-based dev server onhttp://localhost:9000/with live reload (see.esbuild/server.ts). This is the canonical way to work with Mermaid locally.- mermaid.live — the official, community-maintained live editor.
Adding a second, parallel editor surface (with its own Python server, its own template directory, and its own root-level npm scripts) inside the core library repo is a significant expansion of what the repo is responsible for. The maintainers are best placed to decide whether that's desirable — but it's probably worth getting a 👍 from them on the direction before iterating on the code itself. I'd suggest:
- Opening a discussion or issue referencing this work and asking whether a local editor belongs in
mermaid-js/mermaidcore, or whether it should live as a separate project (a common pattern for companion tools). - If maintainers are interested, consider whether the existing
demos/ordev/example.htmlpages could host this instead of a newtemplates/top-level directory.
Everything below assumes a positive answer to the above — but if this ends up living elsewhere, most of these items won't apply.
Things to address (if this goes ahead in-repo)
🔴 [blocking] External CDN load with no SRI — templates/index.html:6
<script src="https://unpkg.com/dompurify@3.0.6/dist/purify.min.js"></script>This fetches DOMPurify from unpkg over the network on every page load, with no integrity="sha384-..." hash. Two problems: (a) breaks the "run from dist/ with no tooling" promise the moment you're offline, and (b) supply-chain risk — if unpkg serves a modified file, the sandbox doesn't help because DOMPurify is what's doing the sanitizing. Mermaid already depends on DOMPurify internally; please either bundle it with the editor or install it as a dev dep and copy the file alongside mermaid.min.js in copy:index.
🔴 [blocking] Non-English content throughout — templates/index.html
<html lang="ru">on line 2- UI strings:
'Показать панель'/'Скрыть панель'(line ~396) - Code comments:
Подсветка прямоугольников нод(line ~53),// FIX: вернуть namespace (иначе текст пропадает)(line ~196),// вставка в iframe(line ~218),// убирает inline-центрирование/// убирает авто-отступы/// якорь трансформаций(lines ~104-107)
Mermaid is an English-first project and the rest of the codebase is consistently English. Please translate lang, UI strings, and inline comments to English.
🔴 [blocking] Python runtime dependency — package.json:"serve:dist"
"serve:dist": "cd packages/mermaid/dist && python -m http.server 8080"This introduces Python as a build-pipeline dependency in an otherwise Node-only monorepo. Not every contributor has python on PATH, and behavior differs between Python 2/3 and Windows vs Unix. Please switch to a Node-based static server — the project already uses start-server-and-test; http-server, serve, or sirv-cli would all fit the existing toolchain.
🟡 [important] No changeset or linked issue
For a user-facing addition that ships via dist/, a changeset is expected (see CONTRIBUTING.md and the existing .changeset/ flow). The PR also doesn't reference an issue where this was scoped/agreed. Linking one (or adding a short rationale to the PR description) will help a human reviewer assess fit.
🟡 [important] href stripped from all elements — templates/index.html:~210
svgEl.querySelectorAll('*').forEach((el) => {
[...el.attributes].forEach((attr) => {
if (attr.name.startsWith('on') || attr.name === 'href' || attr.name === 'xlink:href') {
el.removeAttribute(attr.name);
}
});
});Stripping every href and xlink:href breaks legitimate links Mermaid generates for click directives, and also strips xlink:href on <use> elements that reference in-document symbols (used by some shape sets). DOMPurify already blocks javascript: URLs — this extra pass is both redundant for security and destructive for functionality. Either drop it, or scope it to only strip values starting with javascript: / data: with non-SVG media types.
🟡 [important] Centering math appears off — templates/index.html:~460
const nodeCenterY = nodeRect.top + nodeRect.height / 6;
const contCenterY = contRect.top + contRect.height / 6;
// same pattern for X, using width / 6Dividing by 6 places the "center" one-sixth of the way down/across the node and container — should be / 2 for a true midpoint. Worth double-checking against the behavior you intended.
🟡 [important] Dead / duplicate code
- Outer-scope
let isPanning = false; let startX = 0, startY = 0;(~line 152) are shadowed byisPanningLocal/startXLocal/startYLocalinsiderender()and never used. const _render = render;(~line 522) — assigned and never read.function getRootGroup()(~line 342) — defined and never called.- Two
src.addEventListener('input', ...)listeners are registered separately (one renders, one debounces save). A single debounced listener is cleaner and avoids running the render pipeline twice per keystroke. - Two
#preview svg { ... }CSS rule blocks (~lines 90 and 96) that overlap — fold into one.
🟡 [important] build:mermaid:full has redundant + inconsistent steps
pnpm cleanis redundant withbuild:esbuild, which already runspnpm run -r clean.- Port is hardcoded to
8080, whilepnpm devusesMERMAID_PORT. If the editor is going to live alongside the dev server, sharing the port convention would be less surprising.
🟢 [nit] diagrams[name] = diagrams[name] || {} in the save handler preserves an object whose src and view are overwritten immediately after. The fallback isn't doing work.
💡 [suggestion] If this stays in the repo, moving the inline <style> and <script> blocks into templates/editor.css and templates/editor.js would let ESLint, CSpell, and Prettier cover them — right now a 500-line script is opaque to the usual quality gates.
Security summary
No confirmed XSS vectors in the rendering pipeline — the DOMPurify + sandboxed iframe combination is sound. The main security issue is the unpinned external CDN fetch (above). ADD_TAGS: ['foreignObject'] is acceptable here because DOMPurify still sanitizes the contents, and the iframe blocks script execution regardless.
Verdict
Requesting changes, but the primary ask is really the scope discussion with maintainers — let's land that first and then iterate on the technical items. Thanks again for the contribution; the render-path thinking in particular is solid. 🙂
|
Thanks for the detailed review — really appreciate the depth here. You're absolutely right that the biggest question is whether this belongs inside the core repo or should live as a separate companion tool. My initial intention was to provide a zero-tooling, fully offline editor that works directly against dist/, especially for cases where pnpm dev or mermaid.live are not ideal (e.g. isolated environments, quick prototyping, reverse/debug scenarios). That said, I agree this introduces a parallel surface and expands the repo scope. Before iterating further on the implementation, I’ll open a discussion with maintainers to clarify whether:
Once direction is clear, I’ll address the technical points accordingly. Thanks again — especially for the security feedback, that was very useful. |
|
Hi @Dvurechensky — thanks for the ping. My take: I think this can live in this repo. We're a monorepo, and a standalone editor under packages/ (e.g. packages/mermaid-local-editor or similar) slots in naturally alongside the other packages. So the scope concern from the bot isn't a blocker for me — it's a positioning question, and I'm fine with it being here. That said, the blockers the bot flagged are real and need fixing before this goes further:
If you take care of those three, plus move the template out of a new top-level templates/ into a proper package directory, I think this is genuinely nifty — the localStorage-based multi-diagram UX and the sandboxed-iframe render path are both nice touches. Happy to look again once those are addressed. |
|
Hi! I'm I would like to apply some automated changes to this pull request, but it looks like I don't have the necessary permissions to do so. To get this pull request into a mergeable state, please do one of the following two things:
|
autofix.ci
# Mermaid Local Editor (Custom Template) ## Overview This contribution introduces a lightweight local editor for Mermaid diagrams, implemented as a static HTML interface on top of the existing build output. The editor is designed to run directly from the compiled `dist` directory without requiring any additional tooling, frameworks, or runtime dependencies. --- ## Functionality The template provides the following capabilities: * **Live diagram editing** with immediate rendering * **Multiple diagram management** using `localStorage` * **Automatic persistence** of diagram content and view state * **Zoom and pan controls** (mouse-based interaction) * **Keyboard navigation** between nodes * **Node highlighting** (hover and selection) * **View state restoration** (per diagram) * **SVG export** of the current diagram * **Toolbar visibility toggle** The implementation is intentionally minimal and relies only on the Mermaid runtime (`mermaid.min.js`). --- ## Architecture The editor operates as a static layer: * `mermaid.min.js` is produced by the existing build pipeline * `index.html` provides the UI and interaction logic * A simple static server is used for local execution No changes are made to Mermaid’s internal rendering logic. --- ## Build Integration Additional scripts were introduced to integrate the editor into the existing workflow. ### `clean` ```bash rimraf packages/mermaid/dist ``` Removes the existing build output. --- ### `copy:index` ```bash cpy templates/index.html packages/mermaid/dist/ --flat ``` Copies the editor template into the `dist` directory. The `--flat` option ensures that the file is placed directly at: ``` packages/mermaid/dist/index.html ``` --- ### `serve:dist` ```bash cd packages/mermaid/dist && python -m http.server 8080 ``` Starts a static HTTP server serving the compiled output. --- ### `build:mermaid:full` ```bash pnpm clean && pnpm build:mermaid && pnpm copy:index && pnpm serve:dist ``` Executes the full pipeline: 1. Cleans the build directory 2. Builds the Mermaid bundle 3. Copies the editor template 4. Starts a local server --- ## Result After running the full build: ``` packages/mermaid/dist/ ├── mermaid.min.js ├── index.html ``` Opening the served directory provides a functional local editor for Mermaid diagrams. --- ## Scope * The implementation does not modify Mermaid core * It is fully isolated at the build/output level * It can be used as a development utility or demonstration interface --- ## Notes This approach enables a simple way to work with Mermaid locally without relying on external playgrounds or integrations.
…moved). This is a controlled local editor environment, risk is mitigated.
… and event handlers removed)
…cripts and event handlers removed)
|
CI is failing due to: The validate-lockfile step uses git diff between commits Fix: |
|
@knsv Hi — thanks for the detailed review. I've addressed the points raised:
Additional improvementsBeyond the requested changes, I also refactored the original single-file implementation:
If this structure looks good to you, I can follow up with further refinements if needed. |
|
I don't understand the reason for the Argos error. |
It is a flaky test, we are about to fix it. Will rerun the review to look at your new changes🤞 |
knsv-bot
left a comment
knsv-bot
left a comment
There was a problem hiding this comment.
[sisyphus-bot]
Thanks @Dvurechensky — really significant progress since the last round. The restructure into packages/mermaid-local-editor/ plus the modular JS split is a big improvement, and the CDN / Python-server / language fixes all landed cleanly. Nice work. 🎉
🎉 What's working well now (up from round 1)
- DOMPurify is now bundled locally via
copy:dompurifyfromnode_modules— the supply-chain and offline-capability concerns are both resolved. sirvinstead ofpython -m http.server— good Node-native choice, fits the rest of the toolchain.<html lang="en">and the toolbar labels are all English now.- Monorepo package layout (
packages/mermaid-local-editor/) plus theconfig.js/storage.js/renderer.js/ui.js/navigation.jssplit makes the code dramatically more readable and answers the earlier scope-creep question in a much better way.
🔴 [blocking] — eslint.config.js:28 blanket-ignores the whole new package
'packages/mermaid-local-editor/**',This excludes the entire new package — ~500 lines of JS, CSS, and HTML — from ESLint, Prettier, and CSpell. Other packages in this monorepo are fully covered. A new package shouldn't get a free pass, and in practice this is what lets the items below slip through (the Russian CSS comments would have been caught by CSpell; the duplicate CSS rule by the formatter; the dead variables by no-unused-vars; etc.).
Please remove the blanket ignore. If there's a narrow carve-out that's genuinely needed (for example the copied third-party files under static/vendor/), limit the entry to that:
'packages/mermaid-local-editor/dist/', // if there's a build output
'packages/mermaid/dist/mermaid-local-editor/', // the served output…and fix whatever the first lint pass flags.
🟡 [important] — Russian CSS comments remain in static/styles.css
- lines ~54:
/* фон */,/* свечение */ - lines ~101–103:
/* убирает inline-центрирование */,/* убирает авто-отступы */,/* якорь трансформаций */
Once the ESLint ignore is dropped, CSpell will highlight these. Worth doing a pass across all the new files to make sure no other non-English comments snuck in.
🟡 [important] — href / xlink:href / on* stripping still hurts functionality — static/js/renderer.js:42–48
svgEl.querySelectorAll('*').forEach((el) => {
[...el.attributes].forEach((attr) => {
if (attr.name.startsWith('on') || attr.name === 'href' || attr.name === 'xlink:href') {
el.removeAttribute(attr.name);
}
});
});DOMPurify already blocks javascript: / data: URLs, so this pass is redundant for security. What it does still do, however, is break legitimate hrefs that Mermaid emits for click directives, and strip xlink:href from <use> elements (which some shape sets use to reference in-document symbols). Suggestions:
- Drop the pass entirely and rely on DOMPurify, or
- Keep it protocol-scoped: only strip when
attr.value.startsWith('javascript:') || attr.value.startsWith('data:').
A quick smoke test against a flowchart with click A "https://example.com" in demos/flowchart.html will show the issue.
🟡 [important] — Centering still uses / 6 — static/js/navigation.js:39–45
const nodeCenterY = nodeRect.top + nodeRect.height / 6;
const contCenterY = contRect.top + contRect.height / 6;
// ...same pattern for X with width / 6Mid-point of a rectangle is / 2. If / 6 is intentional (e.g., to keep the selected node biased toward the upper-left so it's always in view), a one-line comment explaining that would help. Otherwise this likely wants to be / 2.
🟡 [important] — Duplicate CSS rule — static/styles.css:92 and :98
#preview svg {
width: 100%;
height: auto;
padding: 12px;
position: relative;
overflow: visible;
}
#preview svg {
display: block;
margin: 0;
transform-origin: 0 0;
}Same selector, non-overlapping properties — fold into one block.
🟡 [important] — No changeset
Adding a new monorepo package and four root-level npm scripts is user-facing. Please run pnpm changeset (or add the file manually) with a chore: or feat: prefix describing the addition. A patch bump is probably fine since nothing user-visible in the core mermaid package itself changes.
🟢 [nit] — Misleading variable name — static/js/ui.js:89
const toolbar = document.getElementById('src');
// ...
toolbar.classList.toggle('collapsed', toolbarCollapsed);The variable is named toolbar but it holds the source textarea (#src). Combined with the button labeled "toggle toolbar," what actually collapses on click is the source panel, not the toolbar (which is #toolbar). Either rename to srcPanel and adjust the button's label, or retarget #toolbar if the intent was the real toolbar.
💡 [suggestion] — setTimeout(…, 0) → requestAnimationFrame — static/js/renderer.js:56
Already using requestAnimationFrame a few lines below — using it here too for the rebuildNavNodes() call keeps it consistent and avoids the setTimeout(…, 0) footgun with microtask ordering.
💡 [suggestion] — Try a click-directive diagram end-to-end
Loading demos/flowchart.html-style content in the new editor and clicking a node would confirm (or rule out) the href-stripping regression flagged above.
Scope (context, not a finding)
The round-1 question about whether this belongs in the core mermaid-js/mermaid repo vs. as a separate project is better answered by the new packages/mermaid-local-editor/ layout — it's now genuinely isolated, which is much nicer. Still worth a 👍 from @knsv / maintainers on direction before spending a lot more polishing time on it, just so nobody is surprised.
Security summary
No new XSS vectors. The iframe sandbox (sandbox="allow-same-origin" with no allow-scripts) plus DOMPurify is sound. The remaining href issue is a functionality concern, not a security one.
Verdict: REQUEST_CHANGES (1 🔴, 5 🟡). Much narrower list than round 1, and most items are mechanical — I think we can get this across the finish line quickly once the ESLint ignore is lifted.
Heads-up on protocol: our automated review escalates to a human reviewer after two rounds of requested changes, so the next round (if needed) would route this to a maintainer rather than another bot pass.
|
Good progress @Dvurechensky !! Only mechanical changes left!
|
Other:
|
|
Hi @Dvurechensky, |
|
E2E bad 😑 |
|
@Dvurechensky The argos quota limit is now reset, please take the latest pull from develop, and the test cases should go properly. We'll be happy to merge this PR once it is green |
|
@ashishjain0512 It seems like everything went well 🎈 |
|
Merging 🥳 |
|
@Dvurechensky, Thank you for the contribution! |
6 participants
Mermaid Local Editor (Custom Template)
Overview
This contribution introduces a lightweight local editor for Mermaid diagrams, implemented as a static HTML interface on top of the existing build output.
The editor is designed to run directly from the compiled
distdirectory without requiring any additional tooling, frameworks, or runtime dependencies.Functionality
The template provides the following capabilities:
localStorageThe implementation is intentionally minimal and relies only on the Mermaid runtime (
mermaid.min.js).Architecture
The editor operates as a static layer:
mermaid.min.jsis produced by the existing build pipelineindex.htmlprovides the UI and interaction logicNo changes are made to Mermaid’s internal rendering logic.
Build Integration
Additional scripts were introduced to integrate the editor into the existing workflow.
cleanRemoves the existing build output.
copy:indexCopies the editor template into the
distdirectory.The
--flatoption ensures that the file is placed directly at:serve:distStarts a static HTTP server serving the compiled output.
build:mermaid:fullExecutes the full pipeline:
Result
After running the full build:
Opening the served directory provides a functional local editor for Mermaid diagrams.
Scope
Notes
This approach enables a simple way to work with Mermaid locally without relying on external playgrounds or integrations.
Screenshots