From 49e6d5f6d6e498861477340a2ebf7a3ea368f3ad Mon Sep 17 00:00:00 2001 From: silverwind Date: Sat, 7 Feb 2026 03:22:57 +0100 Subject: [PATCH] Add `elk` layout support to mermaid (#36486) Fixes: https://github.com/go-gitea/gitea/issues/34769 This allows the user to opt-in to using `elk` layouts using either YAML frontmatter or `%%{ init` directives inside the markup code block. The default layout is not changed. --------- Signed-off-by: silverwind Co-authored-by: wxiaoguang --- package.json | 1 + pnpm-lock.yaml | 19 +++++ web_src/js/markup/mermaid.test.ts | 59 ++++++++++++++++ web_src/js/markup/mermaid.ts | 114 ++++++++++++++++++++++++++---- web_src/js/utils/testhelper.ts | 16 +++++ 5 files changed, 197 insertions(+), 12 deletions(-) create mode 100644 web_src/js/markup/mermaid.test.ts diff --git a/package.json b/package.json index f50bdb0ffb..7b33258759 100644 --- a/package.json +++ b/package.json @@ -15,6 +15,7 @@ "@github/relative-time-element": "5.0.0", "@github/text-expander-element": "2.9.4", "@mcaptcha/vanilla-glue": "0.1.0-alpha-3", + "@mermaid-js/layout-elk": "0.2.0", "@primer/octicons": "19.21.2", "@resvg/resvg-wasm": "2.6.2", "@silverwind/vue3-calendar-heatmap": "2.1.1", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 7764e51399..7795f1c6e3 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -53,6 +53,9 @@ importers: '@mcaptcha/vanilla-glue': specifier: 0.1.0-alpha-3 version: 0.1.0-alpha-3 + '@mermaid-js/layout-elk': + specifier: 0.2.0 + version: 0.2.0(mermaid@11.12.2) '@primer/octicons': specifier: 19.21.2 version: 19.21.2 @@ -805,6 +808,11 @@ packages: '@mcaptcha/vanilla-glue@0.1.0-alpha-3': resolution: {integrity: sha512-GT6TJBgmViGXcXiT5VOr+h/6iOnThSlZuCoOWncubyTZU9R3cgU5vWPkF7G6Ob6ee2CBe3yqBxxk24CFVGTVXw==} + '@mermaid-js/layout-elk@0.2.0': + resolution: {integrity: sha512-vjjYGnCCjYlIA/rR7M//eFi0rHM6dsMyN1JQKfckpt30DTC/esrw36hcrvA2FNPHaqh3Q/SyBWzddyaky8EtUQ==} + peerDependencies: + mermaid: ^11.0.2 + '@mermaid-js/parser@0.6.3': resolution: {integrity: sha512-lnjOhe7zyHjc+If7yT4zoedx2vo4sHaTmtkl1+or8BRTnCtDmcTpAjpzDSfCZrshM5bCoz0GyidzadJAH1xobA==} @@ -2257,6 +2265,9 @@ packages: electron-to-chromium@1.5.283: resolution: {integrity: sha512-3vifjt1HgrGW/h76UEeny+adYApveS9dH2h3p57JYzBSXJIKUJAvtmIytDKjcSCt9xHfrNCFJ7gts6vkhuq++w==} + elkjs@0.9.3: + resolution: {integrity: sha512-f/ZeWvW/BCXbhGEf1Ujp29EASo/lk1FDnETgNKwJrsVvGZhUWCZyg3xLJjAsxfOmt8KjswHmI5EwCQcPMpOYhQ==} + emoji-regex@10.6.0: resolution: {integrity: sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==} @@ -4744,6 +4755,12 @@ snapshots: dependencies: '@mcaptcha/core-glue': 0.1.0-alpha-5 + '@mermaid-js/layout-elk@0.2.0(mermaid@11.12.2)': + dependencies: + d3: 7.9.0 + elkjs: 0.9.3 + mermaid: 11.12.2 + '@mermaid-js/parser@0.6.3': dependencies: langium: 3.3.1 @@ -6172,6 +6189,8 @@ snapshots: electron-to-chromium@1.5.283: {} + elkjs@0.9.3: {} + emoji-regex@10.6.0: {} emoji-regex@8.0.0: {} diff --git a/web_src/js/markup/mermaid.test.ts b/web_src/js/markup/mermaid.test.ts new file mode 100644 index 0000000000..19c3963658 --- /dev/null +++ b/web_src/js/markup/mermaid.test.ts @@ -0,0 +1,59 @@ +import {sourcesContainElk} from './mermaid.ts'; +import {dedent} from '../utils/testhelper.ts'; + +test('sourcesContainElk', () => { + expect(sourcesContainElk([dedent(` + flowchart TB + elk --> B + `)])).toEqual(false); + + expect(sourcesContainElk([dedent(` + --- + config: + layout : elk + --- + flowchart TB + A --> B + `)])).toEqual(true); + + expect(sourcesContainElk([dedent(` + --- + config: + layout: elk.layered + --- + flowchart TB + A --> B + `)])).toEqual(true); + + expect(sourcesContainElk([` + %%{ init : { "flowchart": { "defaultRenderer": "elk" } } }%% + flowchart TB + A --> B + `])).toEqual(true); + + expect(sourcesContainElk([` + --- + config: + layout: 123 + --- + %%{ init : { "class": { "defaultRenderer": "elk.any" } } }%% + flowchart TB + A --> B + `])).toEqual(true); + + expect(sourcesContainElk([` + %%{init:{ + "layout" : "elk.layered" + }}%% + flowchart TB + A --> B + `])).toEqual(true); + + expect(sourcesContainElk([` + %%{ initialize: { + 'layout' : 'elk.layered' + }}%% + flowchart TB + A --> B + `])).toEqual(true); +}); diff --git a/web_src/js/markup/mermaid.ts b/web_src/js/markup/mermaid.ts index e1c2935f23..0314a6177c 100644 --- a/web_src/js/markup/mermaid.ts +++ b/web_src/js/markup/mermaid.ts @@ -3,6 +3,8 @@ import {makeCodeCopyButton} from './codecopy.ts'; import {displayError} from './common.ts'; import {queryElems} from '../utils/dom.ts'; import {html, htmlRaw} from '../utils/html.ts'; +import {load as loadYaml} from 'js-yaml'; +import type {MermaidConfig} from 'mermaid'; const {mermaidMaxSourceCharacters} = window.config; @@ -10,23 +12,111 @@ const iframeCss = `:root {color-scheme: normal} body {margin: 0; padding: 0; overflow: hidden} #mermaid {display: block; margin: 0 auto}`; +function isSourceTooLarge(source: string) { + return mermaidMaxSourceCharacters >= 0 && source.length > mermaidMaxSourceCharacters; +} + +function parseYamlInitConfig(source: string): MermaidConfig | null { + // ref: https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagram-api/regexes.ts + const yamlFrontMatterRegex = /^---\s*[\n\r](.*?)[\n\r]---\s*[\n\r]+/s; + const frontmatter = (yamlFrontMatterRegex.exec(source) || [])[1]; + if (!frontmatter) return null; + try { + return (loadYaml(frontmatter) as {config: MermaidConfig})?.config; + } catch { + console.error('invalid or unsupported mermaid init YAML config', frontmatter); + } + return null; +} + +function parseJsonInitConfig(source: string): MermaidConfig | null { + // https://mermaid.js.org/config/directives.html#declaring-directives + // Do as dirty as mermaid does: https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/utils.ts + // It can even accept invalid JSON string like: + // %%{initialize: { 'logLevel': 'fatal', "theme":'dark', 'startOnLoad': true } }%% + const jsonInitConfigRegex = /%%\{\s*(init|initialize)\s*:\s*(.*?)\}%%/s; + const jsonInitText = (jsonInitConfigRegex.exec(source) || [])[2]; + if (!jsonInitText) return null; + try { + const processed = jsonInitText.trim().replace(/'/g, '"'); + return JSON.parse(processed); + } catch { + console.error('invalid or unsupported mermaid init JSON config', jsonInitText); + } + return null; +} + +function configValueIsElk(layoutOrRenderer: string | undefined) { + if (typeof layoutOrRenderer !== 'string') return false; + return layoutOrRenderer === 'elk' || layoutOrRenderer.startsWith('elk.'); +} + +function configContainsElk(config: MermaidConfig | null) { + if (!config) return false; + // Check the layout from the following properties: + // * config.layout + // * config.{any-diagram-config}.defaultRenderer + // Although only a few diagram types like "flowchart" support "defaultRenderer", + // as long as there is no side effect, here do a general check for all properties of "config", for ease of maintenance + return configValueIsElk(config.layout) || Object.values(config).some((value) => configValueIsElk(value?.defaultRenderer)); +} + +/** detect whether mermaid sources contain elk layout configuration */ +export function sourcesContainElk(sources: Array) { + for (const source of sources) { + if (isSourceTooLarge(source)) continue; + + const yamlConfig = parseYamlInitConfig(source); + if (configContainsElk(yamlConfig)) return true; + + const jsonConfig = parseJsonInitConfig(source); + if (configContainsElk(jsonConfig)) return true; + } + + return false; +} + +async function loadMermaid(sources: Array) { + const mermaidPromise = import(/* webpackChunkName: "mermaid" */'mermaid'); + const elkPromise = sourcesContainElk(sources) ? + import(/* webpackChunkName: "mermaid-layout-elk" */'@mermaid-js/layout-elk') : null; + + const results = await Promise.all([mermaidPromise, elkPromise]); + return { + mermaid: results[0].default, + elkLayouts: results[1]?.default, + }; +} + +let elkLayoutsRegistered = false; + export async function initMarkupCodeMermaid(elMarkup: HTMLElement): Promise { // .markup code.language-mermaid - queryElems(elMarkup, 'code.language-mermaid', async (el) => { - const {default: mermaid} = await import(/* webpackChunkName: "mermaid" */'mermaid'); + const els = Array.from(queryElems(elMarkup, 'code.language-mermaid')); + if (!els.length) return; + const sources = Array.from(els, (el) => el.textContent ?? ''); + const {mermaid, elkLayouts} = await loadMermaid(sources); - mermaid.initialize({ - startOnLoad: false, - theme: isDarkTheme() ? 'dark' : 'neutral', - securityLevel: 'strict', - suppressErrorRendering: true, - }); + if (elkLayouts && !elkLayoutsRegistered) { + mermaid.registerLayoutLoaders(elkLayouts); + elkLayoutsRegistered = true; + } + mermaid.initialize({ + startOnLoad: false, + theme: isDarkTheme() ? 'dark' : 'neutral', + securityLevel: 'strict', + suppressErrorRendering: true, + }); + await Promise.all(els.map(async (el, index) => { + const source = sources[index]; const pre = el.closest('pre'); - if (!pre || pre.hasAttribute('data-render-done')) return; - const source = el.textContent; - if (mermaidMaxSourceCharacters >= 0 && source.length > mermaidMaxSourceCharacters) { + if (!pre || pre.hasAttribute('data-render-done')) { + return; + } + + if (isSourceTooLarge(source)) { displayError(pre, new Error(`Mermaid source of ${source.length} characters exceeds the maximum allowed length of ${mermaidMaxSourceCharacters}.`)); return; } @@ -83,5 +173,5 @@ export async function initMarkupCodeMermaid(elMarkup: HTMLElement): Promise