Support for Rendering Excalidraw Diagrams

[darren]

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-viewer.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.

[techknowlogick]

Could you provide some screenshots?

[darren]

Could you provide some screenshots?

sure

Readme markdown in dark theme

Issue view in light theme

file view

[darren]

I've reconsidered embedding Excalidraw's JSON directly into Markdown, and I don't believe it's the best approach. Although Excalidraw is great for creating diagrams, its underlying JSON format lacks human readability, which would make the Markdown source difficult to read and maintain.

A better solution would be to support rendering .excalidraw files using the standard Markdown image syntax, like this:

![Example Diagram](example.excalidraw)

This would render the file as an inline vector image, much like how SVGs are handled, keeping the Markdown source clean.

[silverwind]

Can excalidraw render .drawio files?

[darren]

Can excalidraw render .drawio files?

Unfortunately, they are not compatible. Excalidraw uses a JSON format, while .drawio uses XML.
Though they both support import from mermaid

[silverwind]

Hmm, that's really a shame, because I think drawio has a huge market share. I wonder if there is maybe a converter that could be used to convert drawio to excalidraw. Excalidraw seems reasonably popular that something like this may exist.

I guess it may still be good to support excalidraw standalone, given its popularity.

[wxiaoguang]

Can excalidraw render .drawio files?

drawio files can be rendered by "https://www.draw.io/js/viewer.min.js"

Since there are more and more renders, I would reiterate my question: #34794 (comment)

Should we keep adding more and more render libraries into the Gitea binary (each one is mega bytes), or use JS CDN as much as possible?

[silverwind]

drawio files can be rendered by "https://www.draw.io/js/viewer.min.js"

Is there a example that showcases its use somewhere?

[silverwind]

This package does not look very popular at all (only a few hundret weekly downloads). Are we sure this is the right interface to convert source to svg? I have a feeling this is not meant for public consumption.

Also it looks like this package brings some PNG-related modules into the dependency tree which would be unused in our case.

[darren]

This is from the official Excalidraw mono repo: https://github.com/excalidraw/excalidraw/tree/master/packages/utils

[wxiaoguang]

drawio files can be rendered by "https://www.draw.io/js/viewer.min.js"

Is there a example that showcases its use somewhere?

They should have some documents, I haven't taken time to look into it. AI says so:

(And some links: jgraph/drawio#3430 )

[silverwind]

drawio files can be rendered by "https://www.draw.io/js/viewer.min.js"

Is there a example that showcases its use somewhere?

They should have some documents, I haven't taken time to look into it. AI says so:

(And some links: jgraph/drawio#3430 )

Looks interesting, I guess we could try it, assuming that JS is available on NPM somewhere.

[wxiaoguang]

Since there are more and more renders, I would reiterate my question: #34794 (comment)

Should we keep adding more and more render libraries into the Gitea binary (each one is mega bytes), or use JS CDN as much as possible?

Looks interesting, I guess we could try it, assuming that JS is available on NPM somewhere.

So, add all render libraries into Gitea binary, or make users download them from JS CDN?

[darren]

Hmm, that's really a shame, because I think drawio has a huge market share. I wonder if there is maybe a converter that could be used to convert drawio to excalidraw. Excalidraw seems reasonably popular that something like this may exist.

I guess it may still be good to support excalidraw standalone, given its popularity.

Excalidraw offers a VS Code plugin[1] that enables you to edit .excalidraw files locally. This streamlines your workflow by eliminating the hassle of manually downloading and managing files from the web application like draw.io or excalidraw.com.

Also excalidraw is very popular among obsidian users with the plugin[2] .

1. https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor
2. https://github.com/zsviczian/obsidian-excalidraw-plugin.

[darren]

So, add all render libraries into Gitea binary, or make users download them from JS CDN?

A full featured plugin system would be a much better approach.

[silverwind]

Imho it's preferable that all assets are served from gitea itself because some users may be in an environment with blocked/restricted/unavailable Internet access.