IPyDrawio

demo	docs	install	build
[][binder]			[![build][workflow-badge]][workflow] ![coverage][cov-badge]

Drawio diagrams for JupyterLab. Forked with ❤️ from QuantStack/jupyterlab-drawio.

Install · History · Roadmap · Contribute · Open Source

This is BETA software. Native drawio files created with these tools should work with any other drawio client, but any UI/API is liable to change at any time.

Installation

mamba install -c conda-forge ipydrawio  # recommended, or...
conda install -c conda-forge ipydrawio  # or...
pip install ipydrawio[all]

Features

ipydrawio
- full support for JupyterLab
- best-effort support for JupyterLiteⓁ and RetroLabⓡ
- Edit multi-page [documents][]
- with nearly the same UI and features as diagrams.net
- in many file formats
  - Drawio/mxgraph XML, SVG, PNG
  - or Jupyter Notebooksⓡ
- with all the Drawio templatesⓡ
  - plus some Jupyter ones
- Jupyter [rich display][] output
- Jupyter Widgets
- Basic collaborative editing
- requires the --collaborative flag, added in JupyterLab 3.1+
- token sharing, a la jupyterlab-link-share, or a custom connector (no known yet)
- no presence indicators for other editors
ipydrawio-export
- Export print-quality PDF from diagramsⓁⓡ
- optionally include editable Drawio XML as a PDF attachment
- BEWARE: some heavy, maybe fragile dependencies, mamba recommended
```
mamba install -c conda-forge ipydrawio-export  # recommended, or...
conda install -c conda-forge ipydrawio-export  # or...
pip install ipydrawio ipydrawio-export
```
ipydrawio-mathjax
- include rich LaTeX and AsciiMath typesetting in diagrams

ⓡ: unavailable in RetroLab Ⓛ: unavailable in JupyterLite

Examples

Note	Screenshot/Example
Screenshot of drawio "minimal" UI with export options	[![poster-min]][poster-min]
The beginning of an interactive computational poster
A mixed computational/creative roadmap for this project	~~Screenshot Needed~~

Usage

Please see the docs for full information

Try on [][binder]
- or follow the Installation instructions and Start JupyterLab
Open a diagram, by doing one of:
- Creating a
  Diagram_ from the [Launcher][]
- Uploading a diagram created on diagrams.net with the [File Manager][] and double clicking it
- Building diagrams by interactively computing in IPython with ipydrawio.Diagram
- Use the application/x-drawio MIME renderer
Use the [Command Palette][] to Export Diagram to various formats
- NOTE: some of the built-in UI features of drawio don't work properly inside an IFrame in JupyterLab, and are difficult to robustly disable: please see Diagram options available in the Command Palette and various Main Menu menus.

Configuring

UI Themes

Your default theme can be changed in the JupyterLab Main Menu:

open Settings
open Diagram Theme
select your theme
all open documents will change to this theme (prompting if not saved)
all future documents will use this theme

The different themes have some advantages and disadvantages:

theme	default	full menu	layers	pages	light	dark	rough
`atlas`		✔️	✔️	✔️	✔️
`dark`		✔️	✔️	✔️		✔️
`kennedy`		✔️	✔️	✔️	✔️
`min`	✔️		✔️	✔️	✔️	⚙️
`sketch`			✔️		✔️	⚙️	✔️

Note that rough will change how many shapes look

Drawio Configuration and URL parameters

Use Advanced Settings to modify drawio embedding parameters

See the schema for full details of the (known) supported options as well as the upstream docs for all parameters, though IPyDrawio might not support them... yet.

PDF: Lab and Server extensions

ipydrawio-export can generate print-quality PDF. This approach relies on a headless browser, powered by @jgraph/draw-image-export2, puppeteer, and nodejs.

native dependencies as required to appease puppeteer
- if running in docker, this can be a bit trial-and-error
- for more, see the binder and CI.
nodejs>=18,<19 from conda or your system package manager
- NOTE: this relies on being able to install puppeteer (and other arbitrary dependencies with jlpm for now when first used
pip install ipydrawio-export or conda install -c conda-forge ipydrawio-export

For example to install all the dependencies:
conda install -yc conda-forge ipydrawio-export ipydrawio-mathjax

Optionally, pre-install the dependencies:

jupyter ipydrawio-export provision

By default this will install to {JUPYTER_DATA_DIR}/ipydrawio_export, but can be tuned with:

the $IPYDRAWIO_DATA_DIR environment variable

IPyDrawioExportManager.drawio_export_workdir in jupyter_config.json

Additionally, the (large) chromium browser download can be tuned with the $IPYDRAWIO_PUPPETEER_CACHE_DIR or $PUPPETEER_CACHE_DIR environment variables.

Once installed, you can use the in-browser tools Export Diagram as PDF as well as the command line:

jupyter ipydrawio-export <name of document>

Open Source

License

All files herein, unless otherwise noted, are free software licensed under Apache 2.0.

Copyright

The copyright holders of this extension are the contributors to this repository.

Portions of the JupyterLab components are derived from QuantStack/jupyterlab-drawio.

The copyright holders of drawio and drawio-export is jgraph.

The original source code vendored in this package from:

Copyright 2023 ipydrawio contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

[binder]: http://mybinder.org/v2/gh/deathbeds/ipydrawio/main?urlpath=lab/tree/docs/Poster.dio.svg

[workflow-badge]: https://github.com/deathbeds/ipydrawio/workflows/.github/workflows/ci.yml/badge.svg [workflow]: https://github.com/deathbeds/ipydrawio/actions?query=branch%3Amain+workflow%3A.github%2Fworkflows%2Fci.yml

[cov-badge]: https://codecov.io/gh/deathbeds/ipydrawio/branch/main/graph/badge.svg?token=9B74VKHQDK

[documents]: https://github.com/deathbeds/ipydrawio/blob/main/docs/Diagram%20Document.ipynb [rich display]: https://github.com/deathbeds/ipydrawio/blob/main/docs/Diagram%20Rich%20Display.ipynb

[poster-min]: https://raw.githubusercontent.com/deathbeds/ipydrawio/main/docs/_static/images/poster.png

roadmap: https://nbviewer.jupyter.org/github/deathbeds/ipydrawio/blob/main/docs/ROADMAP.ipynb [command palette]: https://jupyterlab.readthedocs.io/en/stable/user/commands.html?highlight=command%20palette [launcher]: https://jupyterlab.readthedocs.io/en/stable/user/files.html?highlight=Launcher#creating-files-and-activities