Scimax VS Code

✅ Overview

Scimax VS Code integrates with the Excalidraw VS Code extension to provide seamless support for creating and editing diagrams directly from org-mode documents.

✅ Prerequisites

Install the Excalidraw extension from the VS Code marketplace:

Extension IDName
pomdtr.excalidraw-editorExcalidraw Editor

You can install it via:

  • Command Palette: Extensions: Install Extensions → search "Excalidraw"

  • Or run: code --install-extension pomdtr.excalidraw-editor

✅ Supported File Formats

Excalidraw supports multiple file formats, all of which work with this integration:

ExtensionDescriptionHover Preview
.excalidrawNative Excalidraw format (JSON)Via exports
.excalidraw.jsonExplicit JSON formatVia exports
.excalidraw.svgSVG with embedded Excalidraw scene dataYes
.excalidraw.pngPNG with embedded Excalidraw scene dataYes

  • These formats show hover previews directly

  • They embed the full Excalidraw scene data, so they remain fully editable

  • They can be displayed in exports (HTML, LaTeX, Markdown)

✅ Hover Preview

When you hover over an Excalidraw link, a tooltip appears showing:

  1. Drawing name - The filename or link description

  2. Visual preview - For all Excalidraw file types:

  3. Element count - Number of shapes in the drawing

  4. File information - Size and last modified date

The hover preview for .excalidraw files renders a simplified SVG showing:

  • Rectangles, ellipses, and diamonds with their colors

  • Lines and arrows with arrowheads

  • Freedraw paths

  • Text and image placeholders

For best results, the extension first looks for companion export files (same name with .svg or .png extension). If none exist, it generates a preview from the JSON data.

✅ Click to Edit

Clicking an Excalidraw link opens the drawing in the Excalidraw visual editor.

✅ Existing Files

When you click a link to an existing Excalidraw file:

  1. The file opens in the Excalidraw editor

  2. You can edit the drawing visually

  3. Changes are saved automatically

✅ New Files (Auto-creation)

When you click a link to a non-existent Excalidraw file:

  1. The file is automatically created with an empty drawing

  2. Parent directories are created if needed

  3. The new drawing opens in the Excalidraw editor

This makes it easy to create new diagrams - just write the link and click it:

# This file doesn't exist yet - clicking creates it
[[new-diagram.excalidraw][My New Diagram]]

✅ Fallback Behavior

If the Excalidraw extension is not installed:

  1. The file opens as a text document (showing JSON)

  2. A message suggests installing the Excalidraw extension

✅ Commands

CommandDescriptionInvocation
scimax.org.openExcalidrawOpen Excalidraw DrawingClick on link

The command is automatically invoked when clicking Excalidraw links. It can also be called programmatically:

vscode.commands.executeCommand('scimax.org.openExcalidraw', {
    file: '/path/to/drawing.excalidraw'
});

✅ Workflow Tips

✅ Organizing Drawings

Keep drawings organized alongside your org files:

project/
├── notes.org
├── diagrams/
│   ├── architecture.excalidraw.svg
│   ├── dataflow.excalidraw.svg
│   └── ui-mockup.excalidraw.png
└── docs/
    └── design.org

✅ Export for Sharing

Excalidraw's .excalidraw.svg and .excalidraw.png formats are ideal because:

  • They display correctly in web browsers and image viewers

  • They can be embedded in HTML/PDF exports

  • They retain full editability (scene data is embedded)

✅ Version Control

All Excalidraw formats are text-based (JSON or JSON-embedded), making them suitable for version control with git. The .excalidraw.svg format shows meaningful diffs for the SVG portions.

✅ Troubleshooting

✅ Drawing won't open in visual editor

  • Ensure the Excalidraw extension is installed: pomdtr.excalidraw-editor

  • Check that the file extension is correct (.excalidraw, .excalidraw.json,

  • Try reloading VS Code window

✅ No hover preview appears

  • All Excalidraw file types now show hover previews

  • For .excalidraw files, a simplified SVG is generated from the JSON

  • The file must exist on disk for preview to work

  • Empty drawings show "Empty drawing" instead of a preview