zsviczian/obsidian-excalidraw-plugin: Edit Excalidraw in Obsidian

zsviczian/obsidian-excalidraw-plugin: Edit Excalidraw Drawings Directly in Obsidian

Developers, researchers, and visual thinkers who rely on Obsidian for knowledge management often hit a wall when they need to sketch diagrams, wireframes, or concept maps. Switching between a dedicated drawing tool and your note-taking app breaks flow, fragments context, and creates version-control headaches. The obsidian-excalidraw-plugin by Zsolt Viczián solves this by embedding the full Excalidraw sketching engine directly inside Obsidian—no context switching, no external files to track, and deep bidirectional linking between your drawings and your notes.

This article breaks down what the plugin actually does, how it works under the hood, and where it fits in a developer's workflow. All details are sourced from the project's README and repository metadata.

What is zsviczian/obsidian-excalidraw-plugin?

The obsidian-excalidraw-plugin is an open-source Obsidian plugin that integrates Excalidraw—the popular hand-drawn style sketching tool—into Obsidian as a first-class citizen. It is maintained by Zsolt Viczián as a solo hobby project alongside a full-time job, not by a company or engineering team.

Repository facts:

• Stars: 7,317 | Forks: 470
• Primary language: TypeScript
• License: GNU Affero General Public License v3.0 (AGPL v3.0)
• Last commit: July 14, 2026
• Repository: https://github.com/zsviczian/obsidian-excalidraw-plugin

The plugin stores drawings as markdown^{↗ Smart Converter} files within your Obsidian vault, enabling version control, synchronization via Obsidian Sync, and full integration with Obsidian's linking and search capabilities. Since version 1.2.0, drawings are stored in markdown format with YAML frontmatter, making them readable in Obsidian's graph view and searchable alongside your other notes.

The project's scale and feature density reflect both its maturity and its complexity. Viczián explicitly notes that the codebase includes "clever hacks" and workarounds necessitated by Obsidian's plugin API limitations—such as dynamic code execution for script loading and Electron IPC calls for PDF export—rather than enterprise-grade architectural purity.

Key Features

The plugin's feature set is extensive and technically specific:

Native Obsidian Integration The plugin registers command palette actions, file explorer context menus, ribbon button controls, and option menu commands. CTRL/CMD+Click on the ribbon button or in the file explorer creates or opens drawings in a new pane.

Bidirectional Linking & Transclusion Drawings support Obsidian's [[wikilink]] syntax, including aliases. Links update when files are moved or renamed (with Obsidian's automatic link updating enabled). Drawings appear in document backlinks. Transclusions work via ![[myfile#^blockref]] and ![[myfile#section]], with optional word-wrapping control via {40} syntax.

Markdown Embedding with Customization Embedded drawings support dimensional and alignment controls: ![[image.excalidraw|100]], ![[image.excalidraw|100x100]], ![[image.excalidraw|100|left]], ![[image.excalidraw|right-wrap]]. Custom CSS alignment classes can be added through the wrapper DIV and SVG element styles.

LaTeX Formula Support Mathematical expressions can be inserted via command palette and edited in markdown view or via CTRL/CMD + Click.

Script Engine & Automation Since version 1.5.0, the plugin includes ExcalidrawAutomate macros accessible through a ScriptEngine. Users can assign command palette shortcuts to custom scripts and organize them into groups on the Obsidian Tools Panel.

OCR, Custom Fonts, SVG Import, Custom Pens

• Taskbone OCR integration (requires separate API key)
• Fourth custom font support (WOFF, WOFF2, TTF)
• SVG-to-Excalidraw conversion (with documented limitations)
• Custom pen and highlighter definitions with sidebar pinning

Export & Synchronization

• Auto-export to PNG/SVG with keep-in-sync option
• Frontmatter-controlled per-file export overrides (excalidraw-autoexport: none|both|png|svg)
• Dark/light mode export pairs for published sites
• Compressed JSON storage with optional decompression for manual editing

Mobile Support Full functionality on iOS and Android, including camera image capture.

Use Cases

1. System Architecture Documentation

Developers documenting microservices or infrastructure can create living architecture diagrams that link directly to runbooks, API specs, and incident post-mortems stored in Obsidian. The group= and area= block reference prefixes enable zooming to specific components when referenced from other notes.

2. Research Notebooks with Visual Reasoning

ML practitioners and researchers can sketch model architectures, annotate data pipeline flows, and embed mathematical notation via LaTeX—all within the same vault as their experimental logs. The markdown storage format ensures drawings version alongside code and prose.

3. Product Design & UX Wireframing

The hand-drawn aesthetic of Excalidraw communicates "work in progress" effectively. Designers can create wireframes, link them to user research notes, and export PNGs for stakeholder presentations while maintaining editable source files in the project vault.

4. Personal Knowledge Management (PKM) & Visual Thinking

The plugin's origin in Viczián's "Sketch Your Mind" philosophy supports zettelkasten practitioners who think visually. Book-on-a-page summaries can be decomposed into atomic drawings and reassembled at 100% scale using the niche "anchor to 100%" feature.

5. Automated Documentation Pipelines

Using ExcalidrawAutomate with Dataview, Templater, or QuickAdd, developers can generate diagrams from structured data—automatically updating visualizations when underlying notes change.

Installation & Setup

The plugin is distributed through Obsidian's Community Plugins registry. Manual installation from GitHub is also supported.

Standard Installation (Recommended):

1. Open Obsidian Settings → Community Plugins
2. Disable Safe Mode if enabled
3. Click Browse and search "Excalidraw"
4. Install and Enable the plugin

Manual Installation (for beta releases or development):

# Clone the repository into your vault's plugins folder
cd /path/to/your/vault/.obsidian/plugins/
git clone https://github.com/zsviczian/obsidian-excalidraw-plugin.git

# Install dependencies and build
cd obsidian-excalidraw-plugin
npm install
npm run build

Beta Testing Access: The plugin follows a monthly stable release schedule. For more frequent updates, join the beta community and use the BRAT plugin or manual git checkout of the latest commits.

Post-Installation Configuration:

Key settings to review:

• Basic settings: Default folder paths for new drawings
• Saving: Compression level and autosave interval
• Display: Left-handed mode, theme sync, zoom behavior
• Links and transclusions: How embedded items behave on canvas
• Markdown-embed settings: Rendering of vault documents dropped onto canvas
• Auto-export: Background PNG/SVG generation for portability

The plugin ships with extensive settings; Viczián emphasizes that most feature requests already have corresponding configuration options.

Real Code Examples

The README documents several specific syntax patterns and API calls rather than extensive code samples. Below are the verifiable examples with explanations.

Block Reference Syntax for Image Elements

<!-- Reference a specific element on an Excalidraw canvas -->
[[file#^elementID]]

<!-- Select the group containing the referenced element -->
[[file#^group=elementID]]

<!-- Insert a cutout around the referenced element/section -->
[[file#area=Section heading]]

The group= prefix selects all elements in the same group as the referenced item, useful for highlighting related components in architecture diagrams. The area= prefix creates a cropped view—particularly valuable for focusing attention on specific regions without maintaining separate diagram files. Note that area= is unsupported when embedding as PNG in markdown documents; this reflects a rendering pipeline limitation rather than a bug.

Frontmatter Export Overrides

---
# Override global export settings for this specific drawing
excalidraw-export-transparent: true    # true = transparent background
excalidraw-export-dark: false          # false = light mode export
excalidraw-export-padding: 10          # pixels of padding around export
excalidraw-export-pngscale: 2          # scale factor (typical range 0.5-5)
---

These frontmatter keys enable per-document export control without changing global settings. For documentation pipelines where some diagrams need transparent backgrounds for slide decks while others need white backgrounds for printed reports, this eliminates manual export reconfiguration.

Embedded Markdown with Dimensional Control

<!-- Basic size control -->
![[diagram.excalidraw|100]]

<!-- Explicit width x height -->
![[diagram.excalidraw|100x100]]

<!-- Alignment with width -->
![[diagram.excalidraw|100|left]]

<!-- Text wrapping with custom class -->
![[diagram.excalidraw|right-wrap]]

The pipe-delimited syntax extends Obsidian's native embed format. The alignment string is injected into both the SVG element's style attribute and the wrapper DIV, enabling CSS-based responsive behavior. Custom alignment classes can be defined in your theme's CSS or the plugin's styles.css.

ExcalidrawAutomate API Inspection

// In Obsidian Developer Console (CTRL+SHIFT+i / CMD+OPT+i)

// View URLs referenced in the codebase
ExcalidrawAutomate.printURLsInCodebase();

// Inspect the most recent markdown SVG snapshot
ExcalidrawAutomate.mostRecentMarkdownSVG;

These developer-facing APIs support security auditing and debugging. The printURLsInCodebase() method addresses transparency concerns about external network requests—relevant for air-gapped or security-conscious deployments.

Advanced Usage & Best Practices

Template-Driven Consistency Create a template drawing with your preferred stroke properties, color palette, and font settings. New drawings inherit these defaults. The color palette is configurable via JSON in the template's AppState.colorPalette section—enable "Decompress Excalidraw JSON in Markdown View" (v1.6.13+) to edit this directly.

Performance Optimization for Large Vaults The plugin caches images locally to improve loading for complex scenes. For vaults with hundreds of drawings, consider:

• Enabling compressed JSON storage
• Using the autosave timer to balance crash recovery against I/O overhead
• Periodically clearing the local storage cache if scene loading degrades

Security Posture The maintainer provides explicit transparency about the plugin's security model. Key points for enterprise or sensitive deployments:

• The plugin is 100% local by default; network access only occurs for explicitly configured AI integrations, Taskbone OCR (with API key), or optional features like Iframely link resolution
• Dynamic code execution (eval) is used for script loading and React^{↗ Bright Coding Blog} component lazy-loading—this is architecturally necessary given Obsidian's API limitations, not an oversight
• The requestUrl and fetch calls are auditable via the printURLsInCodebase() API

Script Library Workflow Scripts from the community library extend functionality without core plugin bloat. Install scripts via the Script Engine Store, then organize them into folder-based groups on the Tools Panel. Scripts with settings expose configuration options after first execution.

Comparison with Alternatives

Trade-offs to consider:

• vs. Excalidraw Web: The web version offers real-time collaboration and a larger shape library, but lacks Obsidian's linking, search, and local-first architecture. Use the web version for collaborative sessions; use the plugin for personal knowledge bases.

• vs. Obsidian Canvas: Canvas is first-party, simpler, and integrates natively with no plugin dependency. However, it lacks the hand-drawn aesthetic, LaTeX support, script automation, and extensive export customization that Excalidraw provides. Canvas suits quick diagrams; Excalidraw suits permanent, referenced visual knowledge.

FAQ

Q: Is the plugin free? A: Yes, AGPL v3.0 licensed. The maintainer accepts Ko-fi donations to sustain development.

Q: Does it work offline? A: Fully. Network access only occurs for explicitly enabled features (AI integrations, OCR, script library downloads).

Q: Can I use this with Obsidian Publish? A: Excalidraw drawings don't render in Publish directly. Configure auto-export to PNG/SVG and embed those static images instead.

Q: How do I back up my drawings? A: They're markdown files in your vault—backed up by any Obsidian sync or git solution. Obsidian Sync subscription enables full file history.

Q: Is the codebase audited for security? A: Automated scanners flag patterns like innerHTML and eval, but the maintainer documents why each is necessary given Obsidian's API constraints. Review the detailed findings in the README's disclosure section.

Q: Can I contribute code? A: The project is a solo hobby effort. Contributions are welcome via GitHub issues and PRs, though the maintainer notes that enterprise-grade engineering standards may be unrealistic without corresponding support.

Q: What's the performance impact on large vaults? A: CJK fonts are downloaded on-demand rather than bundled (12MB+). Image caching improves scene loading. Compressed JSON reduces file sizes.

Conclusion

The zsviczian/obsidian-excalidraw-plugin occupies a specific and valuable niche: it brings production-quality sketching into the Obsidian ecosystem without sacrificing the local-first, linkable, searchable principles that make Obsidian effective for knowledge work. For developers, researchers, and visual thinkers who already center their workflows in Obsidian, it eliminates the friction of external drawing tools while adding capabilities—script automation, bidirectional transclusion, markdown-native storage—that no standalone sketching app provides.

The trade-off is complexity. With hundreds of settings, extensive customization options, and a codebase that includes necessary workarounds for platform limitations, the plugin rewards invested users more than casual dabblers. The AGPL v3.0 license ensures derivative work remains open, and the active maintenance (last commit July 2026) suggests continued evolution.

If your note-taking benefits from diagrams, wireframes, or visual reasoning—and you value keeping those visuals in the same system as your text—this plugin is worth the learning curve. Start with the free Excalidraw Essentials course, explore the community wiki, and install from the GitHub repository or Obsidian Community Plugins directly.