Ipydrawio: diagrams in JupyterLab... with pages, layers, widgets, PDF export

Hey folks, it’s been mentioned/demoed a few times, but I wanted to point out the latest (and in some sense, first) release of ipydrawio, which reads and edits multi-page, multi-layer drawio drawings in JupyterLab 3, with a few Jupyter-specific suprises. Today, ipydrawio 1.0.1 is readily-installable from pip, conda (watch out! its 40-70mb!) and ready-to-try on binder with all the fixin’s. It looks something like…


What’s it do?

  • reuse all the drawio templates, shapes, configuration options, and UI themes, even offline
  • opens and saves editable drawio/mxgraph .xml, .png, .svg in JupyterLab 3 that work on diagrams.net, confluence, etc.
    • also reads/writes to .ipynb metadata… but nothing else reads it :blush:
      • and it’s a Jupyter Widget!
      • and a MIME renderer!
    • with the companion ipydrawio-export, also generates .pdf
      • warning: yep, another headless browser thing that needs nodejs. but i didn’t have to write it :man_shrugging:

How’d we get here?

The good folks at QuantStack/jupyterlab-drawio got the ball rolling with drawio in Jupyter, and have been keeping the lights on (it recently got JupyterLab 3 support) but we had some… ambitions. What is now ipydrawio started as a couple pull requests to support features for demos, but eventually kinda had to stand on its own, though under the same name, in hopes we could unify the code bases again. Welp, that didn’t happen. :blush:

When JupyterLab 3 came out, it became much more possible to distribute (all those shapes, whew!)… webpack would just crash, etc. It’s taken a while, but we’re in a much more fun place now!

Where to next?

Aside from the usual (more docs, more tests), stuff we’ve thought of: make it work with other extensions like jupyter-videochat and jupyterlab-lsp, doing some Jupyter mockup templates, and closer integration with Notebook rich displays. Come on by GitHub if there’s more we can do together to make computational diagramming fun in Jupyter!


Via here, some of the drawio extensions provide mechanisms for scripting the creating of particular diagrams. For example, create draw.io diagrams from csv files. You can also use PlantUML to generate draw.i diagrams.

One of the ways I try to maximise generative reuse potential in notebooks is to script diagrams using things like blockdiag magics.

It would be really interesting to explore how scripted diagrams could be defined in notebook magic cells and then used to generate images within or via drawio.

1 Like

Yeah… to the extent possible, the code tries not to interact too closely with any API other than what is exposed by the IFrame embed API. Documentation of the full drawio is… sparse.

The PlantUML thing needs a server, and no doubt there is a configuration flange, sprocket, etc. to set the URL. However, as a bit of a diagram snob, I’ve never liked how the plantuml stuff actually looks at the end without a lot of tweaking, so I personally won’t be rushing to get that working any time soon, though it would be entirely possible with the extension API.

The XML format, on the other hand, is very robust (if also not particularly documented). On the kernel side, the direction I am interested in is building it, such as with graphviz2drawio.

Re: trying to just stick to the embed APi, ok, makes sense.

The graphviz2drawio uses XML and the filesystem, I guess, so you can “drive” image creation in drawio that way; I guess I always hankered after the idea of an API to the drawio drawing engine that I could just pass scripts to and get layed out diagrams back, with an option to also drop into the editor if required (though again for reuse my preference is that the script, and maybe a style file, is complete enough to render the diagram you want).

That’s awesome we are using draw.io + Jupyter to mindmap all our processes at www.naas.ai! Thank you :+1:

1 Like

@bollwyvl that looks really cool! A colleague of mine saw drawio and immediately asked me whether collaborative drawing would be also feasible. Do you think it would be possible to combine it with
the real-time collaboration version of JupyterLab with little extra effort?

1 Like

little extra effort

PRs welcome from your colleague, but :laughing: yeah, naw, it’s not going to be “little.” Diagram editing has all the complexity of the notebook, plus multiple pages, multiple layers, wysiwyg, etc. Unless it plugs seamlessly into the drawio file sync stuff, yeah, well…

The first thing I see spending effort on is, as mentioned, integration with jupyterlab-videochat, as Jitsi has a JSON bus we should be able to put anything on, including the (basically undocumented) file sync mechanism built into drawio, as we would then inherit the trust, video, schreenshare, chat, etc. mechanisms from two production-ready systems rather than having to do them whole cloth or wait for other extensions to exist.

As to something in Lab core: I’m highly unlikely to spend any development time integrating with a pre-release feature, and if it comes to a separate “version”… it might not be something that we can support… but the whole API is basically exposed, so there’s nothing preventing someone from writing an alternate store vs the existing ones (mime, document, jupyter widgets).

Thank you very much for your quick assessment!