Hey Everyone! Zsolt here. Welcome to Visual PKM! Today we are going to learn about the File Structure of Excalidraw in Obsidian.

But you might be thinking right now... Why THE HECK would I want to know that? Because, one key reason for why Excalidraw in Obsidian is so much more than just an illustration tool, comes from its file structure.

If you understand it, you have a superpower at your disposal. There are a lot of things I want to show you, but don't worry, this is all easy stuff and we'll get through it very quickly.

Trust me, you'll be much more powerful knowing all this, when it comes to visual thinking!

But there's another reason we need to talk. With the release of 2.2.0, I've made some important improvements to the file structure that will break backwards compatibility of your drawings.

I made the changes to better support hybrid notes, i.e., notes that have a drawing on one side of the imaginary paper, and Markdown text on the other... So make sure you update the plugin on all your devices to avoid surprises.

On a side note, if you are an Obsidian Insider, and have installed 1.6.

0, then drawings larger than 2MB will not open, because Obsidian stopped indexing large files.

This has nothing to do with Excalidraw updates, and the Obsidian devs have already fixed this in 1.6.1. My hope is that the update will be made public soon.

However, we'll touch on some file size related topics later in the video. So, why should you care about the file structure? Because then you'll have more control over your own data.

You'll understand about compatibility with excalidraw.com, get access to power features, keep file sizes and Obsidian sync quota under control, avoid synchronization conflicts and create better Templater templates, to name a few.

When it comes to file formats, you have two options: `*.excalidraw` files or `*.md` files. We will not spend too much time on `*.excalidraw` files.

Related features support niche use cases. But the most basic use case for `*.excalidraw` file support is compatibility with excalidraw.

com. If you download a drawing from Excalidraw.com, then drop that file into your Obsidian Vault, you'll be able to open it with the plugin. Note, however, the warning message that pops up.

You should convert the imported file to markdown to get all the benefits of the plugin. You can convert it by right-clicking the tab and selecting, "Convert to new format".

The `*.md` format comes with many benefits. Links in your drawings get updated by Obsidian. You get all the fancy backlink and outgoing link features.

Document properties are available. You get to add tags and notes on the back of the drawing, plus you can block reference text from your drawing in all your notes.

Switching to markdown view mode, you will observe three major parts of the note: Document properties at the top, back-of-the-card notes right below properties but above Excalidraw Data, and the Excalidraw Data section.

Let's look at these one by one, starting with properties. Depending on your Obsidian settings, properties may look different or be completely hidden.

This is how properties look in source mode, and how they look in the properties editor. Excalidraw comes with many predefined properties to choose from.

I'll share the link to this drawing in the video description, so you can come back to this list. However, the benefit of editing properties in source mode is the popup suggester. For example, you can override the default theme of a drawing by applying the `export-dark` property.

This will not only influence how the drawing gets rendered when embedding to markdown, but also how the drawing looks when you open it.

Now, let's talk about Excalidraw Data. The Drawing section contains your drawing in JSON. This is the same format as in the `*.excalidraw` file, except that images are not embedded in the JSON.

We'll talk about this in a moment. I want to draw your attention to the two code blocks: "compressed-json" and "json".

When in markdown view mode, you can use "Decompress current Excalidraw file" from the Command Palette to convert the compressed JSON into human-readable format. This is great when you manually want to tweak your JSON.

The decompress feature is also available via script using Excalidraw Automate. Compression is done using the open-source LZ-String package.

Starting from Excalidraw 2.2.0, compression is set as the default in Plugin Settings and converting compressed JSON to normal JSON when switching to markdown view mode is disabled by default.

I recommend these settings for keeping your drawings data smaller. The other feature we need to talk about is the markdown comment.

By default, the Drawing section is commented out to avoid it showing up in reading mode and when exporting to PDF or to the web. You may move the comment to the line right before Excalidraw Data.

This way Excalidraw Data will also be hidden in exports, BUT by doing so, block referencing text elements from your drawings will stop working because Obsidian does not index blocks in comments.

The Text Elements section is where all your text in the drawing is stored. When we block referenced the text in another note a moment ago, this was the block reference we were using.

Sometimes it is quicker to modify text in Text Elements in markdown view, rather than on the drawing. Modifications in the Text Elements section will take precedence over the Drawing JSON.

All you need to pay attention to is to leave the block references at the end of the lines intact.

Back-of-the-card notes are simply markdown sections at the top of your Excalidraw file. You may notice an extra hashtag appear above Excalidraw Data when adding a back-of-the-card note.

This happens when you have Excalidraw Data commented out. The extra hashtag will not be visible in exports, but it is required for avoiding the commented section from appearing when editing the back-of-the-card note.

For the most part, you don't need to worry about this, I just wanted to share in case some of you were wondering.

The last part of the file I wanted to show you is the Embedded Files section. Excalidraw in Obsidian does not save images to the Excalidraw JSON, but stores all the images separately in your Vault.

This is great, because this way you can reference and reuse images. You can even use shared images to navigate between drawings. I will link two related videos in the description below should you want to explore this idea further.

One neat, but currently hard to use feature is how you can recolor embedded SVG and Excalidraw images by providing a color map.

The other power feature is how you can anchor the size of an embedded Excalidraw drawing to 100% of its original size. I won't go into the many reasons why you might want to do that, but just note, that by adding a 100% following the pipe character you can enforce the size and disable resizing of the image in your scene.

Finally, if you embed LaTeX equations into your drawing, these will also show up under Embedded Files.

Sometimes it may be more convenient to edit them here. To complete our walkthrough, let's spend a minute to understand Autosave.

When Obsidian terminates, it does not await plugins to finish saving. To avoid half-saved files and synchronization conflicts, it is best to force save your drawing and closing the tab before exiting Obsidian.

This is especially useful when you work on many devices, like I do. When I finish working on my MacBook at night, I make sure Excalidraw is closed and Obsidian syncs before going to sleep.

This way, in the morning at my desktop or on my tablet I can safely continue working on the drawing. In plugin settings, under Saving, you can define different autosave intervals for desktop and for mobile.

Beyond the autosave interval Excalidraw will always save your drawing when switching tabs, before editing back of the card notes, and when closing a drawing or switching to markdown view mode.

Because Obsidian Sync stores all the previous versions of your markdown files, having large drawings that save too frequently can quickly eat up your quota.

I personally use the "Practically never" setting on desktop, but a frequent autosave on mobile. This is because on a mobile, it is easy to switch tasks, and you never know when iOS or Android will recycle the Obsidian process in the background.

So hopefully, you found this walkthrough helpful, and it also wasn't too painful.

If you liked this video, subscribe and hit that like button, and if you want to support me, you can find a link to my Ko-fi page in the description below.

Excalidraw-Obsidian File Structure: Breaking change in 2.2.0

A channel about visual tools and techniques for Personal Knowledge Management

Excalidraw-Obsidian File Structure: Breaking change in 2.2.0

Excalidraw-Obsidian File Structure: Breaking change in 2.2.0

Scripts