Add diagrams.net support to Gitlab Wikis (Markdown).
What does this MR do?
It implements support for creating and editing diagrams using the diagrams.net editor in Wikis.
How to test in your local environment?
- Edit or create a Wiki page.
- Switch to Markdown mode if you are using the Content Editor to edit the Wiki page’s content.
To create a diagram:
- Click the Insert or edit diagram toolbar button in the Markdown editor.
- Use the diagrams.net editor to build the diagram.
- Click Save & exit.
- The Markdown field will insert a Markdown image declaration pointing to the diagram created.
To edit a diagram:
- Place the Markdown editor’s text field cursor in a Markdown image declaration that contains the diagram.
- Click the Insert or edit diagram toolbar button in the Markdown editor.
- Use the diagrams.net editor to build the diagram.
- Click Save & exit.
- The Markdown field will replace the previous Markdown image declaration pointing to the diagram created.
Screenshots
Markdown field | Draw.io Editor | Entering diagram name | Diagram saved successfully | Failed to load diagrams.net editor | Failed to load existing diagram |
---|---|---|---|---|---|
Implementation details
The diagrams are saved as SVG files that use the drawio.svg
extension and uploaded using GitLab’s user uploads API.
The diagrams.net editor is embedded in the GitLab application using an iframe. The iframe and the GitLab application communicate using the postMessage API. There are two main communication workflows between the draw.io iframe and the GitLab application: loading a diagram and saving a diagram.
sequenceDiagram
participant A as drawio_editor.js (container)
participant B as diagrams.net (iframe)
A->>+B: postMessage('configure', { darkMode })
B-->>-A: postMessage('init')
Loading a diagram
- The GitLab application will send a
configure
message to the draw.io iframe that indicates whether GitLab is in Dark mode and sets GitLab settings preset. - The diagrams.net iframe will reply with an
init
message to the GitLab application. - If there is a draw.io diagram selected in the Markdown field, the
EditorFacade
will download the diagram and the GitLab application willload
it into the draw.io editor. - Otherwise, the GitLab application sends a
load
message with an empty payload.
Saving a diagram
- The diagrams.net iframe will send an
export
message to the GitLab application when the user clicks "Save & Exit". - If the unsaved diagram doesn’t have a name.
3. The gitlab application will send a
prompt
message to display a filename dialog in the diagrams.net editor. 4. The diagrams.net editor will send aprompt
message back to the GitLab application with the filename entered by the user. - When the filename is set, the GitLab application will upload the diagram as an SVG file.
- It will insert a Markdown image declaration pointing to the diagram SVG file.
Markdown field editor facade
The markdown_field_editor_facade.js
module is a bridge between the diagrams.net editor and the markdown_field component. The goal of this module is keeping the diagrams.net editor agnostic from text editors. It will allow us to implement support for this editor in the Content Editor as well.
Next steps
-
Dark mode support — !109994 (closed) -
Content Editor support
Related to #322174 (closed)