Skip to content

Instantly share code, notes, and snippets.

@kevinjalbert
Created June 1, 2023 03:22
Show Gist options
  • Save kevinjalbert/b5f37afe5efc0e38b9ae4cdbcb85247a to your computer and use it in GitHub Desktop.
Save kevinjalbert/b5f37afe5efc0e38b9ae4cdbcb85247a to your computer and use it in GitHub Desktop.
I want to talk about a tool called Excalidraw, which is a diagramming tool that I've used in personal and work scenarios. It's really flexible, fast, and enjoyable to use. Overall, I have had great experiences with it. Excalidraw also has a set of collaborative features.
But what I really want to highlight is the ability to save diagrams as artifacts like PNG or SVG files while still retaining the ability to modify the diagrams within Excalidraw. This is possible through a feature called embedded scene. When exporting a PNG or SVG, you can embed the Excalidraw scene data inside the file itself. It's super cool because you can take this file, reopen it within Excalidraw, and continue modifying the diagram.
In collaborative or documentation settings, this feature is powerful because you can version control the file. If you put it in a Git repository, you can show it in rendered documentation sites as a regular PNG or SVG file. Another bonus, especially for VS Code users, is the Excalidraw extension. It allows you to modify the file within the Excalidraw environment from your IDE editor. So if you have architecture diagrams or flow diagrams in your repository, you have an easy way to modify them and commit the changes, minimizing friction and ensuring up-to-date documentation diagrams.
There are a few gotchas I've encountered. If you pass the PNG file with embedded scene data through compression or minification tools like ImageOptim, that information will be lost. So if you're committing files to a repository, make sure they are not processed by such tools to preserve the embedded metadata.
GitHub has been experimenting with something called Blocks, an experimental preview feature. It allows you to specify that certain files can be rendered or edited within the GitHub interface. With Excalidraw files, you could make Excalidraw appear as an editor within the GitHub interface. This is powerful because it enables non-technical users to modify diagrams easily and allows those without VS Code as their primary editor to make changes effortlessly.
Another nice feature is that with the VS Code plugin, you can use a GitHub code space to quickly open a VS Code editor with the extension and modify the files as needed.
In summary, Excalidraw is a great tool that I enjoy using. The ability to embed scene data in the final artifact is convenient, as it eliminates the need to handle both the exported image and the JSON data separately. While other tools like MermaidJS or text rendering tools have their merits, sometimes it's easier to work with a what-you-see-is-what-you-get editing or diagramming tool.
There are other powerful collaboration tools like Miro or Figma, but in my experience, they don't integrate well into a repository setting. That's why I appreciate Excalidraw, as it allows diagrams to stay close to the code.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment