Support for Rendering Excalidraw Diagrams

While issue #28903 explored integrating Draw.io, @lunny suggested in a #28903 (comment) that Excalidraw would be a better alternative. The primary reasons are its MIT license and its ease of integration into Gitea.

The recommended approach is to implement this as a plugin after the work in #34917 is completed.

Key Changes:

* Markdown Rendering:
   - The Markdown renderer now recognizes excalidraw as a language identifier in code blocks, similar to mermaid.
* Configuration:
    - A new setting `EXCALIDRAW_MAX_SOURCE_CHARACTERS` has been added to control the maximum size of Excalidraw source data.
* Dependencies:
     - The `@excalidraw/utils` package has been added to package.json to handle Excalidraw data processing.
* Frontend Features:
     - A new file view plugin (`excalidraw-view.ts`) is added to render .excalidraw files directly.
     - The markup content handling (`content.ts`) now initializes Excalidraw rendering for embedded diagrams.
     - A new module (`excalidraw.ts`) is created to handle the logic of rendering Excalidraw JSON from code blocks into SVG images, including dark mode support.
     - The main file view feature (`file-view.ts`) now includes the Excalidraw viewer plugin.

Author: darren

modules/markup/markdown/markdown.go

@@ -82,7 +82,7 @@ func (r *GlodmarkRender) highlightingRenderer(w util.BufWriter, c highlighting.C
 		languageStr := giteautil.IfZero(string(languageBytes), "text")
 
 		preClasses := "code-block"
-		if languageStr == "mermaid" || languageStr == "math" {
+		if languageStr == "mermaid" || languageStr == "math" || languageStr == "excalidraw" {
 			preClasses += " is-loading"
 		}
 

modules/setting/markup.go

@@ -13,9 +13,10 @@ import (
 
 // ExternalMarkupRenderers represents the external markup renderers
 var (
-	ExternalMarkupRenderers    []*MarkupRenderer
-	ExternalSanitizerRules     []MarkupSanitizerRule
-	MermaidMaxSourceCharacters int
+	ExternalMarkupRenderers       []*MarkupRenderer
+	ExternalSanitizerRules        []MarkupSanitizerRule
+	ExcalidrawMaxSourceCharacters int
+	MermaidMaxSourceCharacters    int
 )
 
 const (
@@ -127,6 +128,7 @@ func loadMarkupFrom(rootCfg ConfigProvider) {
 		}
 	}
 
+	ExcalidrawMaxSourceCharacters = rootCfg.Section("markup").Key("EXCALIDRAW_MAX_SOURCE_CHARACTERS").MustInt(100000)
 	MermaidMaxSourceCharacters = rootCfg.Section("markup").Key("MERMAID_MAX_SOURCE_CHARACTERS").MustInt(50000)
 	ExternalMarkupRenderers = make([]*MarkupRenderer, 0, 10)
 	ExternalSanitizerRules = make([]MarkupSanitizerRule, 0, 10)

package.json

@@ -10,6 +10,7 @@
     "@citation-js/plugin-bibtex": "0.7.18",
     "@citation-js/plugin-csl": "0.7.18",
     "@citation-js/plugin-software-formats": "0.6.1",
+    "@excalidraw/utils": "0.1.3-test32",
     "@github/markdown-toolbar-element": "2.2.3",
     "@github/paste-markdown": "1.5.3",
     "@github/relative-time-element": "4.4.8",

web_src/js/features/file-view.ts

@@ -1,6 +1,7 @@
 import type {FileRenderPlugin} from '../render/plugin.ts';
 import {newRenderPlugin3DViewer} from '../render/plugins/3d-viewer.ts';
 import {newRenderPluginPdfViewer} from '../render/plugins/pdf-viewer.ts';
+import {newRenderPluginExcalidrawViewer} from '../render/plugins/excalidraw-view.ts';
 import {registerGlobalInitFunc} from '../modules/observer.ts';
 import {createElementFromHTML, showElem, toggleElemClass} from '../utils/dom.ts';
 import {html} from '../utils/html.ts';
@@ -10,7 +11,7 @@ const plugins: FileRenderPlugin[] = [];
 
 function initPluginsOnce(): void {
   if (plugins.length) return;
-  plugins.push(newRenderPlugin3DViewer(), newRenderPluginPdfViewer());
+  plugins.push(newRenderPlugin3DViewer(), newRenderPluginPdfViewer(), newRenderPluginExcalidrawViewer());
 }
 
 function findFileRenderPlugin(filename: string, mimeType: string): FileRenderPlugin | null {

web_src/js/markup/content.ts

@@ -1,4 +1,5 @@
 import {initMarkupCodeMermaid} from './mermaid.ts';
+import {initMarkupCodeExcalidraw} from './excalidraw.ts';
 import {initMarkupCodeMath} from './math.ts';
 import {initMarkupCodeCopy} from './codecopy.ts';
 import {initMarkupRenderAsciicast} from './asciicast.ts';
@@ -12,6 +13,7 @@ export function initMarkupContent(): void {
     initMarkupTasklist(el);
     initMarkupCodeMermaid(el);
     initMarkupCodeMath(el);
+    initMarkupCodeExcalidraw(el);
     initMarkupRenderAsciicast(el);
   });
 }

web_src/js/markup/excalidraw.ts

@@ -0,0 +1,79 @@
+import {isDarkTheme} from '../utils.ts';
+import {makeCodeCopyButton} from './codecopy.ts';
+import {displayError} from './common.ts';
+import {queryElems} from '../utils/dom.ts';
+import {html, htmlRaw} from '../utils/html.ts';
+
+const {excalidrawMaxSourceCharacters} = window.config;
+
+const iframeCss = `body { margin: 0; } svg { max-width: 100%; height: auto; }`;
+
+export async function initMarkupCodeExcalidraw(elMarkup: HTMLElement): Promise<void> {
+  queryElems(elMarkup, 'code.language-excalidraw', async (el) => {
+    const {exportToSvg} = await import(/* webpackChunkName: "excalidraw/utils" */ '@excalidraw/utils');
+
+    const pre = el.closest('pre');
+    if (pre.hasAttribute('data-render-done')) return;
+
+    const source = el.textContent;
+    if (excalidrawMaxSourceCharacters >= 0 && source.length > excalidrawMaxSourceCharacters) {
+      displayError(pre, new Error(`Excalidraw source of ${source.length} characters exceeds the maximum allowed length of ${excalidrawMaxSourceCharacters}.`));
+      return;
+    }
+
+    let excalidrawJson;
+    try {
+      excalidrawJson = JSON.parse(source);
+    } catch (err) {
+      displayError(pre, new Error(`Invalid Excalidraw JSON: ${err}`));
+      return;
+    }
+
+    try {
+      const svg = await exportToSvg({
+        elements: excalidrawJson.elements,
+        appState: {
+          ...excalidrawJson.appState,
+          exportWithDarkMode: isDarkTheme(),
+        },
+        files: excalidrawJson.files,
+        skipInliningFonts: true,
+      });
+      const iframe = document.createElement('iframe');
+      iframe.classList.add('markup-content-iframe', 'tw-invisible');
+      iframe.srcdoc = html`<html><head><style>${htmlRaw(iframeCss)}</style></head><body>${htmlRaw(svg.outerHTML)}</body></html>`;
+
+      const excalidrawBlock = document.createElement('div');
+      excalidrawBlock.classList.add('excalidraw-block', 'is-loading', 'tw-hidden');
+      excalidrawBlock.append(iframe);
+
+      const btn = makeCodeCopyButton();
+      btn.setAttribute('data-clipboard-text', source);
+      excalidrawBlock.append(btn);
+
+      const updateIframeHeight = () => {
+        const body = iframe.contentWindow?.document?.body;
+        if (body) {
+          iframe.style.height = `${body.clientHeight}px`;
+        }
+      };
+      iframe.addEventListener('load', () => {
+        pre.replaceWith(excalidrawBlock);
+        excalidrawBlock.classList.remove('tw-hidden');
+        updateIframeHeight();
+        setTimeout(() => { // avoid flash of iframe background
+          excalidrawBlock.classList.remove('is-loading');
+          iframe.classList.remove('tw-invisible');
+        }, 0);
+
+        (new IntersectionObserver(() => {
+          updateIframeHeight();
+        }, {root: document.documentElement})).observe(iframe);
+      });
+
+      document.body.append(excalidrawBlock);
+    } catch (err) {
+      displayError(pre, err);
+    }
+  });
+}

web_src/js/render/plugins/excalidraw-view.ts

@@ -0,0 +1,33 @@
+import type {FileRenderPlugin} from '../plugin.ts';
+import {isDarkTheme} from '../../utils.ts';
+import {request} from '../../modules/fetch.ts';
+
+export function newRenderPluginExcalidrawViewer(): FileRenderPlugin {
+  return {
+    name: 'excalidraw-viewer',
+
+    canHandle(filename: string, _mimeType: string): boolean {
+      return filename.toLowerCase().endsWith('.excalidraw');
+    },
+
+    async render(container: HTMLElement, fileUrl: string): Promise<void> {
+      const {exportToSvg} = await import(/* webpackChunkName: "excalidraw/utils" */ '@excalidraw/utils');
+      const data = await request(fileUrl);
+      const excalidrawJson = await data.json();
+      const svg = await exportToSvg({
+        elements: excalidrawJson.elements,
+        appState: {
+          ...excalidrawJson.appState,
+          exportWithDarkMode: isDarkTheme(),
+        },
+        files: excalidrawJson.files,
+        skipInliningFonts: true,
+      });
+      container.style.display = 'flex';
+      container.style.justifyContent = 'center';
+      svg.style.maxWidth = '80%';
+      svg.style.height = 'auto';
+      container.append(svg);
+    },
+  };
+}