vscode-drawio Documentation

This unofficial extension integrates Draw.io (also known as diagrams.net) into VS Code.

9,495 stars TypeScript TypeScript 1 file · ~5,570 tokens #diagram#drawio#hacktoberfest#vscode-extension
RAW Doc

Technical Documentation: hediet/vscode-drawio

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

Draw.io VS Code Integration

This unofficial extension integrates Draw.io (also known as diagrams.net) into VS Code.
Mentioned in the official diagrams.net blog.

Features

  • Edit .drawio, .dio, .drawio.svg or .drawio.png files in the Draw.io editor.
    • To create a new diagram, simply create an empty *.drawio, *.drawio.svg or *.drawio.png file and open it.
    • .drawio.svg are valid .svg files that can be embedded in Github readme files! No export needed.
    • .drawio.png are valid .png files! No export needed. You should use .svg though whenever possible - they look much better!
    • To convert between different formats, use the Draw.io: Convert To... command.
  • .drawio files are plain XML: they diff cleanly in git, and AI assistants can read, edit and review diagram changes like any other code.
  • Uses an offline version of Draw.io by default.
  • Multiple Draw.io themes are available.
  • Use Liveshare to collaboratively edit a diagram with others.
  • Nodes/edges can be linked with code spans.

Demo

Editing .drawio.svg/.drawio.png Files

You can directly edit and save .drawio.svg and .drawio.png files.
These files are perfectly valid svg/png-images that contain an embedded Draw.io diagram.
Whenever you edit such a file, the svg/png part of that file is kept up to date.

The logo of this extension is such a .drawio.png file that has been created with the extension itself!

If you want readable diffs, for your reviewers and your AI tools alike, prefer .drawio over .drawio.png diagrams.

Collaboratively Edit Or Present Diagrams

With version 1.0 of this extension, extensive support for VS Code Liveshare has been added. You can now edit or present your Draw.io diagrams remotely, while seeing each participant's cursor and selection! This can be used for discussing, reviewing or brainstorming diagrams.
With Draw.io's freehand drawing tool and integrated LaTeX support, this extension becomes an advanced whiteboard solution that can be used for remote code interviews!

Internally, this extension synchronizes Draw.io diagrams with text documents.
These text documents are shared by Liveshare. As Liveshare has no understanding of the text, modification conflicts might occur on simultaneous modifications.

In the status bar, you can enable or disable the code link feature.
If it is enabled and you double click on a node whose label starts with #,
you will perform a workspace search for a symbol matching the rest of the label.

If you have a node labeled #MyClass and a class of name MyClass, you will jump to its source if you double click the node!

Please note that you have to open at least one file of the project that contains the symbol.
Otherwise, VS Code will not consider this project when searching for symbols.
This file itself does not have to contain the symbol though.

Thanks to my latest github sponsors, this feature is open source and freely available now.

TIP: If you open the draw.io editor to the right side (i.e. the second editor column) and navigate to a symbol,
the diagram will stay visible.

Themes

text
**Available Draw.io Themes**


    <li>Theme "atlas"</li>
    <li>Theme "Kennedy"</li>
    <li>Theme "min"
    <li>Theme "dark"</li>

Associate `.svg` Files With The Draw.io Editor

By default, this extension only handles *.drawio.svg files.
Add this to your VS Code settings.json file if you want to associate it with .svg files:

json
"workbench.editorAssociations": {
    "*.svg": "hediet.vscode-drawio-text",
}

You won't be able to edit arbitrary SVG files though - only those that have been created with Draw.io or this extension!

Light and Dark `.drawio.svg` Files

By default, .drawio.svg files are saved with light colors, whatever theme the editor uses.
Set hediet.vscode-drawio.svgAppearance to auto to make them adapt to the color scheme of the page that shows them, for example a README on GitHub in dark mode, or to dark to always save them with dark colors.
The setting applies the next time a diagram is saved. Add it to the workspace settings so that everyone on a team saves the same file.

Inline Diagrams in VS Code's Markdown Editor (Experimental, Insiders only)

VS Code Insiders ships an experimental WYSIWYG Markdown editor (View: Reopen Editor With... > Markdown Editor).
In that editor, every fenced code block tagged drawio is replaced by a live, resizable Draw.io editor:

markdown
```drawio
<mxfile>...</mxfile>
```

Edits are written straight back into the fenced block, so the Markdown file stays the single source of truth and undo/redo, dirty state and hot exit keep working.
The block attributes of the inline editor are honored: locked makes a block read-only and height=N fixes its height, e.g. ```drawio locked height=300.
The Markdown editor's own lock toggle also puts the diagrams into read-only mode.

Notes:

  • VS Code's contribution point for this is experimental and only exists in Insiders builds; in stable VS Code (and in the regular Markdown preview) the fence is shown as text or rendered by the preview plugin as before.
  • Dynamic providers only run in trusted workspaces.
  • Settings that are baked into the editor (theme, appearance, custom libraries, fonts, ...) apply the next time the Markdown editor is opened.
  • Draw.io plugins are not loaded into the inline editors.

Editing the Diagram and its XML Side by Side

You can open the same *.drawio file with the Draw.io editor and as xml file.
They are synchronized, so you can switch between them as you like it.
This is super practical if you want to use find/replace to rename text or other features of VS Code to speed up your diagram creation/edit process.
Use the View: Reopen Editor With... command to toggle between the text or the Draw.io editor. You can open multiple editors for the same file.
This does not make much sense for SVG files though, as the draw.io diagram is stored in its metadata.

The same goes for AI assistants: the file is a visual diagram for you and plain text for your agent.
When an agent edits the XML, the change shows up in the open diagram right away, and in a pull request it can read the diff of a diagram (an added node, a changed connection, a new label) and act on it just like it would on code.

Contributors

  • Henning Dieterichs, hediet on Github (Main Contributor / Author)
  • Vincent Rouillé, Speedy37 on Github

See Also / Similar Extensions

  • Draw.io - This extension relies on the giant work of Draw.io. Their embedding feature enables this extension! This extension bundles a recent version of Draw.io.
  • vscode-drawio by eightHundreds.

Overview (`examples/formats/README.md`)

Draw.io diagrams can be embedded in markdown files!

SVG Diagram:

PNG Diagram:

Overview (`examples/inline-editor/README.md`)

Draw.io Markdown Diagrams - Test File

Diagrams as First-Class Markdown Content

This extension is a full draw.io editor for .drawio, .drawio.svg, and .drawio.png diagram files. On top of that, it can embed and edit diagrams directly inside Markdown — as fenced drawio XML blocks, HTML-comment blocks, or links to .drawio.svg/.drawio.png image files, with in-place mermaid conversion — all version-controlled and diffable.

Unlike text-to-diagram DSLs, the mxfile format encodes a full graph structure: typed nodes and edges, explicit geometry, hierarchical parent-child relationships, and extensible metadata on every element. This makes the XML machine-readable in ways DSLs are not — LLMs can parse, produce, and semantically diff diagram changes (added nodes, changed connections, moved components) without specialized tooling.

Screenshots

Code Lenses

Each drawio code block gets inline CodeLens actions (Edit, Inline Edit, Preview, Lock/Unlock) directly above the block. Edit opens the diagram in a new tab, while Inline Edit opens the Markdown Editor and scrolls to the diagram, activating the inline editor.

Markdown Editor

Right-click any .md file and choose "Open With..." to open it with the Draw.io Markdown Editor. This is an experimental, very simple editor to showcase the inline diagram editing experience:

Built-in Markdown Preview

Draw.io code blocks are rendered as diagram previews in VS Code's built-in Markdown preview.

1. Basic Fenced Diagram (Unlocked)

Click the CodeLens above the block to edit, preview, or lock this diagram.

text
/* Detailed source-code truncated for AI context efficiency. */
```drawio&#xa;&lt;mxfile&gt;...&lt;/mxfile&gt;&#xa;```
/* Detailed source-code truncated for AI context efficiency. */

2. Locked Fenced Diagram

This diagram should show as locked. Use the CodeLens to unlock it before editing.

drawio locked
<mxfile>
  <diagram id="locked-fenced" name="Locked">
    <mxGraphModel>
      <root>
        <mxCell id="0"/>
        <mxCell id="1" parent="0"/>
        <mxCell id="2" value="LOCKED" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;fontSize=16;fontStyle=1;" vertex="1" parent="1">
          <mxGeometry x="100" y="100" width="200" height="80" as="geometry"/>
        </mxCell>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

3. HTML Comment Diagram (Unlocked)

Alternative syntax using HTML comments. Should also show CodeLens actions.

4. Locked HTML Comment Diagram

5. Multiple Diagrams in Sequence

Testing that multiple consecutive blocks are each detected independently.

drawio
<mxfile>
  <diagram id="multi-a" name="Box A">
    <mxGraphModel dx="560" dy="807" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="0" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <mxCell id="2" parent="1" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=24;" value="A" vertex="1">
          <mxGeometry height="80" width="80" x="100" y="100" as="geometry" />
        </mxCell>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>
drawio
<mxfile>
  <diagram id="multi-b" name="Box B">
    <mxGraphModel dx="345" dy="-83" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="0" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <mxCell id="2" parent="1" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;fontSize=24;" value="D" vertex="1">
          <mxGeometry height="80" width="80" x="71" y="111" as="geometry" />
        </mxCell>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

6. Empty Diagram Placeholder

Insert a new diagram here using the Draw.io: Insert Diagram command (Ctrl+Shift+P).

7. Regular Markdown (No Diagrams)

This section has no diagrams. The extension should not show any CodeLens here.

  • Bullet point one
  • Bullet point two
javascript
// Regular code block — should be ignored by the extension
console.log("not a diagram");

A blockquote with no diagrams.

drawio
<mxfile>
  <diagram id="default" name="Page-1">
    <mxGraphModel dx="552" dy="67" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="0" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <mxCell id="2" parent="1" style="whiteSpace=wrap;html=1;" value="" vertex="1">
          <mxGeometry height="60" width="120" x="-273" y="-27" as="geometry" />
        </mxCell>
        <mxCell id="3" parent="1" style="ellipse;whiteSpace=wrap;html=1;" value="" vertex="1">
          <mxGeometry height="60" width="60" x="-3" y="-27" as="geometry" />
        </mxCell>
        <mxCell id="4" edge="1" parent="1" source="2" style="edgeStyle=none;curved=1;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;fontSize=12;startSize=8;endSize=8;" target="3" value="">
          <mxGeometry relative="1" as="geometry" />
        </mxCell>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

8. Mermaid Conversion

Click the "Convert to draw.io" CodeLens above the mermaid block to convert it to a draw.io diagram. The original mermaid source is preserved in the draw.io model root cell metadata under mermaidSource.

mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

9. Last Diagram on Page

Testing that resizing the last diagram on the page works.

drawio
<mxfile>
  <diagram id="multi-a" name="Box A">
    <mxGraphModel dx="560" dy="807" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="0" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <mxCell id="2" parent="1" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;fontSize=24;" value="A" vertex="1">
          <mxGeometry height="80" width="80" x="100" y="100" as="geometry" />
        </mxCell>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

10. Linked Image Files (`.drawio.svg` / `.drawio.png`)

Besides fenced and HTML-comment blocks, an ordinary Markdown image link to a same-repository .drawio.svg or .drawio.png file is rendered and edited inline like a code block — except edits are written back to the linked image file, not into this Markdown. draw.io embeds the editable diagram XML inside the image itself (the SVG content attribute, or a PNG tEXt chunk), so each file is at once a normal image and a fully editable diagram.

A link is treated as an editable diagram only when it is on its own line and resolves to a local file inside this workspace folder; remote URLs, out-of-repo paths, and non-draw.io images stay as plain images. The Preview button on a linked diagram opens the file in VS Code's image-preview tab (rather than the draw.io viewer), and external changes to the file — from the standalone draw.io editor, git, or any other tool — merge into any open inline editing session, just like edits to the Markdown itself.

Unlike inline blocks, linked files are real image files: they double as standalone SVG/PNG assets, can be reused across many documents, carry their own version history, and display in any tool that renders linked images (VS Code's built-in Markdown preview, GitHub, GitLab, …) with no extension required. The trade-offs are that the diagram lives in a separate file, you can't set a display size in the link, and the file stores the rendered image as well as the XML (so it's larger than a bare inline block). See showcase.md for the full inline-vs-linked comparison.

The Code Link feature lets you link Draw.io nodes and edges to source code symbols.
Just name a node or edge #MySymbol where MySymbol is the name of the symbol you want to link to.
When code link is enabled (see the status bar) and you double click on a node or edge whith such a label, you will jump to the symbol definition.

Disable Code Link or select a node and press F2 if you want to change the label.

This feature works with any programming language that implements the VS Code workspace symbol search.
In TypeScript, symbols are functions, classes, consts, interfaces, ...

Code Links also work for *.drawio.png and *.drawio.svg files which are plain *.png and *.svg files with embedded Draw.io metadata that can be put on Github.
The Code Link Feature does not work on Github though.

Code Link supports hierarchical document symbols. First, select the node, then navigate to the document and run the "Link Symbol With Selected Node" command. Select your symbol from the dropdown. This will link the node to a symbol as well as the current docment URI.

Hierarchy levels are delimited by the dot "." and you can choose to edit the paths by pressing "Ctrl+M" within the Draw.io editor.

You can also run "Link Workspace Symbol With Selected Node" to link a symbol path without linking to the specific docment URI. This way, documents can be moved freely without breaking the code link. However, some symbol providers don't cooperate with exporting workspace symbols -- when this occurs, a warning will be shown.

Since you can directly paste images into Draw.io diagrams, you can use this feature to connect
screenshots of react components to their source:

Applications

This feature can be used in many ways:

  • for documentation
  • for quick code navigation (like visual bookmarks)
  • for diagram based code tours

Thank You

Thank you to Draw.io for being so open and enabling this kind of stuff, thank you to all the Contributors of this extension and thank you so much for my Sponsors on Github that really motivate me implementing features like this!

Plugins (`docs/plugins.md`)

VS Code Draw.io Integration - plugins

The plugins feature lets you load Draw.io plugins, just as you can by opening
the online version of Draw.io with the ?p=svgdata query parameter:
https://www.draw.io/?p=svgdata.

Draw.io has a list of sample plugins
which can be copied, or you may create your own.

Enabling a plugin in the Draw.io Integration

Plugins currently needs to be loaded from an absolute path in the Draw.io
Integration extension. Thus for compatibility reasons (e.g., in a repository
shared between multiple people), the plugin likely needs to be added to the
workspace folder where your diagrams are located as well. To facilitate this,
the path can be specified using the ${workspaceFolder} variable, effectively
allowing you to specify a relative path within your workspace.

Plugins are added using the hediet.vscode-drawio.plugins configuration
property. Adding this to the workspace settings makes sure that the plugin is
automatically loaded for anyone that edits Draw.io files inside this workspace.

Example:

  1. Download the Draw.io sample plugin svgdata.js, and place it in the root of
    the workspace.

  2. Add the following to the workspace settings:

    json
    "hediet.vscode-drawio.plugins": [
    {
        "file": "${workspaceFolder}/svgdata.js"
    }
],

  3. Open any Draw.io file

  4. Accept or deny loading of the plugin

    If this is the first time after adding the plugin definition, or if the
    plugin was changed, then the Draw.io Integration will show you a dialogue
    box, asking you to allow or disallow loading of the given plugin.

    What ever action you choose, is written to the
    hediet.vscode-drawio.knownPlugins property, in the user settings (scope)
    by the Draw.io Integration extension.

    Your decision is explicitly only read and written to the user scope, to
    ensure that a redistributed workspace can't load a plugin without you
    previously having accepted the specific version of a plugin (determined
    through the hash of the file).

    Example:

    json
    "hediet.vscode-drawio.knownPlugins": [
    {
        "pluginId": "file:///full/path/to/workspace/svgdata.js",
        "fingerprint": "<sha256>",
        "allowed": true // or false if you disallowed it
    }
],

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#diagram Browse diagram catalog → #drawio Browse drawio catalog → #hacktoberfest Browse hacktoberfest catalog → #vscode-extension Browse vscode-extension catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →