Excalidraw

Excalidraw

【English | 简体中文】

👉👉👉 Check out and contribute to the new Obsidian-Excalidraw Community Wiki

The Obsidian-Excalidraw plugin integrates Excalidraw, a feature rich sketching tool, into Obsidian. You can store and edit Excalidraw files in your vault, you can embed drawings into your documents, and you can link to documents and other drawings to/and from Excalidraw. For a showcase of Excalidraw features watch the videos below.

Excalidraw for Obsidian keeps evolving; it is extremely feature‑rich and can feel intimidating at first. The Video Walkthrough below should ease that initial overwhelm. For a comprehensive, searchable knowledge base covering features, settings, scripting, workflows, and visual thinking methods, explore the public NotebookLM workbook (a must‑have learning resource).

Excalidraw Essentials is a free course to get started with Excalidraw.

If you are curious about the Visual PKM philosophy behind the plugin, consider my book Sketch Your Mind and the Visual Thinking Workshops. To learn about all the different options available and how they fit together, check out the Welcome to the Sketch Your Mind Ecosystem introduction page. Finally, keep the Excalidraw Plugin Wiki and the NotebookLM workbook at hand, those are essential companions.

Native CLI for coding agents

With Obsidian 1.12.2+ and CLI enabled, local agents can discover, create, inspect, edit, save, render, and run explicitly trusted local scripts through Excalidraw. Older Obsidian versions remain supported. Select Excalidraw: Show CLI and agent instructions in the command palette, or start with obsidian vault="My vault" obsidian-excalidraw-plugin:help. See the CLI reference and portable agent skill.

Disclaimer / Disclosure: Plugin Access and Privileges

I treat privacy as a top priority. Apart from the few technical limitations outlined below, Excalidraw is 100% local and runs without network access. Most of the findings published on sites such as obsidianpluginaudit.com, plugin.observer, and community.obsidian.md/plugins can be misleading without proper context.

Obsidian is fundamentally a locally executed web application. Automated code scanners apply the same vulnerability rules used for public-facing websites, even though the risk model inside a local Obsidian vault is very different. For example, patterns such as innerHTML or outerHTML manipulation are considered problematic on public websites because they can expose visitors to malicious third-party content. In a local-first application such as Obsidian, these risks are significantly different in nature and impact.

Excalidraw for Obsidian is a large and feature-rich tool with many integrations and performance optimizations. Below, I explain how the most common findings reported by these scanners are actually used within the plugin.

When evaluating these findings, please keep the following in mind:

1. Obsidian.md currently does not provide plugin developers with proper mechanisms for deploying local assets such as fonts, auxiliary packages, or official APIs for certain features like Obsidian Publish or PDF generation. As a result, plugin developers sometimes need to rely on workaround solutions such as IPC calls or dynamic code execution (eval) to deliver functionality users expect.

2. Excalidraw for Obsidian is not maintained by a company or engineering team. It is a one-person hobby project and an open-source contribution developed alongside a full-time job. If you would like to support continued development and improved code quality, the best way is through financial support via Ko-fi. Open-source software is not truly “free.” The cost is usually paid in developer time, personal energy, or by supporters who help sustain the project. I will continue striving to improve the codebase, but expectations around enterprise-grade engineering standards for a free community contribution can easily become unrealistic and unsustainable without corresponding support structures.

3. In general, I recommend using the minimum number of plugins necessary for your workflow. Personally, I use around 10–15 plugins and disable plugins when not actively needed. This is not because I distrust plugin safety, but because most Obsidian plugins are hobby-driven community projects, and I believe users should maintain realistic expectations regarding maintenance, complexity, and long-term support.

• Plugin might make requests to external domains:

  • To see the complete list of URLs referenced in the code, either used as links, images, or in API calls, open the Obsidian Developer Console (CTRL+SHIFT+i or CMD+OPT+i) and run ExcalidrawAutomate.printURLsInCodebase()
  • The plugin works fully offline and locally by default.
  • If you configure API keys for AI features and explicitly use those features, the corresponding AI providers are contacted.
  • The Taskbone OCR service requires a separate API key and explicit user opt-in in plugin settings.
  • Iframely is optionally used to resolve reader-friendly webpage titles when dragging website links into Excalidraw. This feature is disabled by default.
  • The Ko-fi support button, when enabled, downloads its image asset from cdn.ko-fi.com.
  • The CJK font package exceeds 12 MB in size. To avoid significantly increasing plugin startup time and bundle size, these fonts are downloaded from GitHub only when required.

• requestUrl and fetch calls:

  • Used for AI integrations and Taskbone OCR functionality.
  • Excalidraw supports embedding images from external sources (local URIs and public URLs). requestUrl is used to retrieve those images when needed.
  • The Excalidraw Script Library accesses GitHub to download scripts only when the user explicitly chooses to install them.

• Excalidraw accesses files in your vault:

  • To detect legacy .excalidraw files and support conversion workflows.
  • To search for and load custom fonts stored inside the vault.
  • To populate file picker dialogs such as “Insert any file.”

• Clipboard access:

  • Allows users to copy and paste Excalidraw scenes between Obsidian and excalidraw.com.
  • Allows users to copy links to scene elements and paste them into markdown documents as embeds.

• Local Storage:

  • Excalidraw stores image caches locally to improve loading performance for large and complex scenes.
  • Mermaid text-to-diagram chat history is stored locally.
  • Backup versions of drawings are stored locally to support crash recovery.

• Dynamic Code Execution:

  • Excalidraw dynamically loads user-created scripts and scripts installed from the Script Library.
  • Excalidraw also dynamically loads parts of the Excalidraw React component and supporting packages. This improves startup performance and supports functionality such as desktop popout windows.

• Electron remote module privilege IPC bridge calls:

  • Used to access Electron’s built-in PDF generation capabilities so users can export drawings as PDFs.
  • This avoids bundling additional large PDF libraries, reducing plugin size and improving performance.
  • The process also enables Electron’s native file-save dialog when exporting PDFs.

• Document-level keyboard listener:

  • Comes from the core excalidraw.com component to support keyboard shortcuts and interactions.

• Direct Node.js file system access allowing access outside the vault:

  • Used exclusively to support embedding images located outside the Obsidian vault into Excalidraw scenes.

Video Walkthrough

Here's my complete catalog of videos:

Beta testing

The plugin follows a monthly release schedule. If you want to receive more frequent updates with new features (e.g. shiny new stuff available on excalidraw.com, but not yet in Obsidian) and minor bug fixes, then join the beta community.

Features

• The plugin integrates Excalidraw seamlessly into Obsidian, including Command Palette actions, File Explorer features, Option Menu commands, and the Ribbon Button.
• CTRL/CMD+Click on the ribbon button or in the file explorer to create / open drawings in a new pane.

Settings

Settings will allow you to customize Excalidraw to your needs. The plugin comes with tons of settings. I tried adding meaningful explanations to these settings, so please be patient and look for the setting, for most requests, a setting already exists.

Plugin settings are grouped into the following sections:

• Basic settings: such as default folders to use.
• Saving: compression and autosave timer.
• Filename: configure the automatically created Excalidraw filename.
• Display: settings that affect the handling of Excalidraw (e.g.: left-handed mode, theme settings, mouse wheel and pinch zoom settings, zoom to fit settings).
• Links and transclusions: Settings that affect how links and embedded items behave on the Excalidraw canvas.
• Markdown-embed settings: These settings control how markdown documents from your Vault embedded into Excalidraw drawings will behave.
• Embed & Export: Settings that control how Excalidraw images are displayed when embedding them into markdown documents.
• Auto-export Settings: You can configure Excalidraw to create a PNG or SVG copy of your drawing each time it gets saved.
• Compatibility features: Check these settings if you edit the Excalidraw drawings outside Obsidian (e.g. in LogSeq, Visual Studio, on the web, etc.).
• Experimental features: There are advanced features that are implemented as "clever" hacks. Features include defining a fourth font, adding a custom icon to distinguish Exalidraw files in the Obsidian file explorer, OCR settings, and more.
• Settings for installed Scripts: Some of the scripts you install from the Script Library come with settings. Script settings are installed the first time you run the script. So to access settings for a script, install the script, run it for the first time and then look for the settings in plugin settings.

Templates

• Template for new drawings. The template will restore stroke properties. This means you can set up defaults in your template for stroke color, stroke width, opacity, font family, font size, fill style, stroke style, etc. This also applies to ExcalidrawAutomate. With versions 1.6.13 or higher make sure to enable "Decompress Excalidraw JSON in Markdown View" in the settings before editing the JSON in the template. This can be disabled after the canges are performed.
  • Via the template, you can customize the color palette used by Excalidraw.
    • Switch to Markdown view.
    • Scroll down to the bottom of the file and find "AppState": {.
    • Find "colorPalette": { at the end of the AppState section.
      • You may specify the 3 palettes used in Excalidraw by adding any or all of the following 3 variables:
        • "canvasBackground":[], "elementBackground":[], "elementStroke": [].
        • Add a comma-separated list of valid HTML colors (e.g. #FF0000 for red) in the array for each of the variables.
      • To change the previewed colors, a "topPicks": { may be specified containing the same three keys:
        • "canvasBackground":[], "elementBackground":[], "elementStroke": [].
        • Note that the corresponding arrays must contain 5 elements.
    • See my videos above for further help.

Export

• If portability is important to you:

  • Auto-export SVG and/or PNG files, including the keep-in-sync feature, so you can embed SVG/PNG into your documents instead of embedding excalidraw files.
  • You can override export settings for an individual file by adding the excalidraw-autoexport frontmatter key. Valid values for this key are none, both, 'png', and svg.

• Specify the default width of embedded drawings.

• Compatibility features to auto-export and keep in sync markdown excalidraw files and legacy .excalidraw files.

• Experimental feature to add custom TAG to file explorer to mark drawing files.

• Enable / disable autosave.

Embedding your drawings into markdown documents

• You can customize the size and position of the embedded images using the
  • ![[image.excalidraw|100]],
  • ![[image.excalidraw|100x100]],
  • ![[image.excalidraw|100|left]],
  • ![[image.excalidraw|right-wrap]], formatting options.
  • ![[<filename.excalidraw>|<width>x<height>|<alignment>]].
  • You can add your custom alignment via CSS.
  • Any text that appears in <alignment> will be added to the rendered SVG element style and to the wrapper DIV element.
  • See styles.css for more insight.
• Excalidraw drawings do not display in Obsidian Publish. If you want to use Excalidraw in your published documents, you can configure in plugin settings, under Embed & Export, to automatically insert a PNG or SVG version of the drawing in your document when creating a new file. See type of file to insert into document
  • Under Export settings, you can also configure to automatically export a dark and light version of the image, in case your published site supports dark and light modes.

Hyperlinks and Drag & Drop support

Hyperlinks

• Supports hyperlinks, e.g.
  • https://zsolt.blog,
  • [Obsidian](https://obsidian.md), and
  • Internal links, e.g. [[My file in vault|Alias]] in drawing text.
• Links will update when files are moved or renamed, if you have the Obsidian setting Files & Links/Automatically Update Internal Links enabled.
• Links in drawings will show up in the backlinks of documents.
• Transclusions are supported:
  • ![[myfile#^blockref]] will convert the drawing into the transcluded text of the block
  • ![[myfile#section]] also works, this will transclude the section.
  • You can also specify word wrapping for transcluded text by adding the max character count: in curly brackets right after the transclusion e.g. ![[myfile#^blockref]]{40} will wrap text at 40 characters.
• For convenience, you can also use the command palette to insert links into drawings.
• CTRL/CMD + hover to bring up the Obsidian quick preview for the link. (On Mac, it is CTRL+CMD+hover).
• Using the block reference, you can also reference & transclude text that appears on drawings, in other documents.

Drag & Drop support

• You can drag files from the Obsidian file explorer, and they will become links to those files in Excalidraw. See the table above for the various modifier key combinations.
• Note: Anchoring an image to 100% of its size is a very niche feature with a very particular behavior that I built primarily for myself.
  • (even more so than other features in Excalidraw Obsidian - also built primarily for myself 😉).
  • This will reset your embedded image to 100% size every time you open the Excalidraw drawing, or in case you have embedded an Excalidraw drawing on your canvas inserted using this function, every time you update the embedded drawing, it will be scaled back to 100% size.
  • This means that even if you resize the image on the drawing, it will reset to 100% the next time you open the file, or you modify the original embedded object. This feature is useful when you decompose a drawing into separate Excalidraw files, but when combined onto a single canvas you want the individual pieces to maintain their actual sizes. I use this feature to construct book-on-a-page summaries from atomic drawings.
• You can drag and drop text from Markdown views onto Excalidraw.
• You can drag and drop web addresses from your browser, and they will become links.
• You can drag and drop YouTube links and thumbnails, and they will be YouTube links with thumbnails in Excalidraw.

LaTeX

Insert LaTeX formulas using the Command Palette action "Insert LaTeX formula". You can edit formulas either in Markdown view or by CTRL/CMD + Click on the formula.

Image support

• On iOS and Android, you can add images from your camera by pressing the add image button in Excalidraw.
• You can copy/paste images into your drawing. Images will be saved in your vault.
• You can drag and drop images as explained above.
• URL link to images on the web: You can drag images from a webpage to Excalidraw. If you hold down the CTRL button while dropping the image to Excalidraw, the image will not be saved to your vault. Excalidraw will load the image from the URL. Note that if you do not have internet access or if these images are deleted from the internet, they will also disappear from your drawing.
• If you page an image URL to excalidraw (simply click copy on the url, then click paste on the excalidraw canvas), the image will be inserted with a link to the image on the web. Again, the image won't be saved to your vault, only the link.
• If you drop a YouTube video link, it will be converted into a thumbnail photo with an element link pointing to the video.

Block referencing parts of images

For more details, see this video

• When referencing an element on the canvas in a link pointing to an Excalidraw file using
  • The elementId or the section header (i.e. a Text Element containing the # <Section title>)
    • e.g. [[file#^elementID]],
  • You can add the group= prefix,
    • e.g. [[file#^group=elementID]] or
  • The area= prefix,
    • e.g. [[file#area=Section heading]].
  • If the group= prefix is found, Excalidraw will select the group of elements in the same group as the element referenced by the elementID (block reference) or the section heading.
  • If the area= prefix is found, Excalidraw will insert a cutout of the image around the referenced element.
  • You can append ,padding=N to area=, group=, frame=, and clippedframe= image references to override the exported image padding, e.g. ![[file#^area=elementID,padding=120]]. For area=, the value also controls how far around the referenced element Excalidraw searches for surrounding elements. Use padding=0 for no added margin. This works with both SVG and PNG previews.
  • Referencing the elementID of a text element without the group= or area= prefix will transclude the element as plain text. Referencing a non-Text Element (e.g. rectangle, ellipse, etc.) without the group= or area= prefix will result in an Obsidian error. since these elementIds are not present in the Excalidraw markdown file as block references.

Markdown

• Since 1.2.0, drawing files are stored in Markdown files.
  • You can add tags to drawings.
  • You can add metadata to the YAML front matter of drawings.
  • Anything you add between the frontmatter and the # Text Elements heading will be ignored by Excalidraw, i.e. you can add whatever you like here, and it will be preserved as part of the document.
  • Excalidraw documents now show up in graph view.
  • The following front matter keys will customize how the drawing is displayed - overriding general settings:
    • excalidraw-link-prefix: "📍" preview prefix for internal links
    • excalidraw-url-prefix: "🌐" preview prefix for external links
    • excalidraw-link-brackets: true|false whether or not to display brackets around links in preview
    • excalidraw-default-mode: view|zen Open this document in view mode or zen mode by defult. The default view mode is excellent for presentation slides.
  • Frontmatter tags to customize image export at a file level 519. If these keys are present, they will override the default Excalidraw embed and export settings.
    • excalidraw-export-transparent: true: true == Transparent / false == with background.
    • excalidraw-export-dark: true == Dark mode / false == light mode.
    • excalidraw-export-padding: Specify the export padding for the image.
    • excalidraw-export-pngscale: This only affects export to PNG. Specify the export scale for the image. The typical range is between 0.5 and 5, but you can experiment with other values as well.
• Since 1.6.13, enable "Decompress Excalidraw JSON in Markdown View" in the settings if you want to change any JSON content.

Embed complete markdown files into your drawings

Drag the desired file from the Obsidian file explorer and hold down SHIFT while dropping the file onto the canvas.

• Use the command palette action: Insert markdown file from vault
• Use custom woff, woff2, or TTF font to display the document, you can set the default font to use under Excalidraw Settings.
• You can set a custom CSS for rendering the snapshot image of your markdown document. Only operating system-standard fonts are supported as the font-family (Win10, Mac & iOS), plus you can set one additional custom font using the setting explained above.
  • (for a demonstration, watch this video and check out this
  • sample css).
  • To help with styling, you can observe the SVG snapshot of the markdown document created by Excalidraw.
    • Open Obsidian Developer Console (CTRL+Shift+i/CMD+OPT+i) and
    • Execute the following command: ExcalidrawAutomate.mostRecentMarkdownSVG
• You can control the appearance of the embedded markdown file on a file by file bases by adding the following front matter keys to your markdown document:
  • excalidraw-font: Virgil|Cascadia|font_file_name.extension
  • excalidraw-font-color: css-color-name|#HEXcolor|any-other-html-standard-format,
    • You can find css color names here.
  • excalidraw-border-color: css-color-name|#HEXcolor|any-other-html-standard-format
  • excalidraw-css: "css-filename|css snippet"
• Switch to markdown view or use WIN+CTRL/CMD+CTRL click on the image to edit the properties of the embed:
  • [[filename#^blockref|WIDTHxMAXHEIGHT]]

Custom Font, Custom Pen, OCR support, SVG import

• In plugin settings, you can add a custom fourth font. For more details, see this video
• The plugin includes OCR support using Taskbone OCR. For more details, see this video
• You can convert SVG files into Excalidraw drawings (with some limitation). For more details, see this video
• You can define custom pens and higlighters and pin them to the sidebar. For more details, see this video. Using ExcalidrawAutomate, you can add support for auto-toggling pen & support for hardware eraser buttons.

Script Engine

• Since 1.5.0, you can easily execute ExcalidrawAutomate macros and assign command palette shortcuts to them, using the ScriptEngine. You will find an intro video and a growing library of ready to install scripts here.
• You can organize scripts into groups on the Obsidian Tools Panel in Excalidraw by moving scripts and accompanying SVG icon files to folders. See the demo video.

Other

• Left-handed mode
• Includes full
  • QuickAdd,
  • Templater and
  • Dataview support through ExcalidrawAutomate.
  • Check out the detailed help + examples.
  • I also have a YouTube ExcalidrawAutomate Playlist with lots of examples.
• REQUIRES AN OBSIDIAN SYNC SUBSCRIPTION: Full drawing file history and synchronization between devices
• Multilanguage support: if you'd like to help out by translating the plugin, please get in contact with me.

Feedback, questions, ideas, problems

Join the conversation about the Excalidraw plugin on forum.obsidian.md

Please head over to GitHub to report a bug or request an enhancement.

Say Thank You

If you are enjoying Excalidraw, then please support my work and enthusiasm by buying me a coffee on https://ko-fi/zsolt.

Please also help spread the word by sharing about the Obsidian Excalidraw Plugin on Twitter, Reddit, or any other social media platform you regularly use.

You can find me on Twitter @zsviczian, and on my blog zsolt.blog.

Friends of Excalidraw

If you enjoy Excalidraw, consider giving ExcaliBrain a try (also available via Obsidian Community Plugins).