Diagrams Panel

What is the Diagrams Panel?

The Diagrams Panel provides centralized management of Draw.io and Excalidraw diagrams with quick creation, organization, and embedding capabilities. Create diagrams directly from VS Code and embed them seamlessly in your notes.

Overview

The Diagrams Panel allows you to:

• Quick Creation: Create Draw.io or Excalidraw diagrams with one click
• Centralized Storage: All diagrams organized in Diagrams folder
• Auto-Embed: Embed syntax automatically copied to clipboard
• Visual Organization: Diagrams grouped by type (Draw.io / Excalidraw)
• Metadata Display: See file size, modification date, and usage stats

Accessing the Panel

The Diagrams Panel appears in the sidebar as “DIAGRAMS” section, showing all your diagram files organized by type.

Panel Sections

Draw.io Diagrams

Shows all .drawio files:

📐 Draw.io (3)
  └── architecture.drawio
      Modified: 2 days ago | 45 KB
  └── database-schema.drawio
      Modified: 1 week ago | 32 KB
  └── system-flow.drawio
      Modified: 3 days ago | 28 KB

Excalidraw Diagrams

Shows all .excalidraw files and exported formats:

🎨 Excalidraw (4)
  └── wireframe.excalidraw
      Modified: Today | 12 KB
  └── ui-mockup.excalidraw
      Modified: Yesterday | 18 KB
  └── concept.excalidraw.svg
      Modified: 3 days ago | 8 KB
  └── flowchart.excalidraw.png
      Modified: 1 week ago | 125 KB

Quick Creation Workflow

Creating a Draw.io Diagram

1. Click the + icon in the Diagrams panel toolbar
2. Select “Create Draw.io Diagram”
3. Enter diagram name (e.g., “architecture”)
4. Diagram created at Diagrams/architecture.drawio
5. Embed syntax copied to clipboard: ![[architecture.drawio]]
6. Paste in note and click to edit in Draw.io editor

Creating an Excalidraw Diagram

1. Click the + icon in the Diagrams panel toolbar
2. Select “Create Excalidraw Diagram”
3. Enter diagram name (e.g., “wireframe”)
4. Diagram created at Diagrams/wireframe.excalidraw
5. Embed syntax copied to clipboard: ![[wireframe.excalidraw]]
6. Paste in note and click to edit in Excalidraw editor

Commands

Create Draw.io Diagram

Command: Noted: Create Draw.io Diagram

Creates a new Draw.io diagram file with empty canvas, stores it in the Diagrams folder, and copies the embed syntax to clipboard.

Result: Diagrams/diagram-name.drawio created with embed syntax ![[diagram-name.drawio]] copied

Create Excalidraw Diagram

Command: Noted: Create Excalidraw Diagram

Creates a new Excalidraw diagram file with empty canvas, stores it in the Diagrams folder, and copies the embed syntax to clipboard.

Result: Diagrams/diagram-name.excalidraw created with embed syntax ![[diagram-name.excalidraw]] copied

Insert Diagram

Command: Noted: Insert Diagram

Opens a quick picker showing all available diagrams. Select one to insert its embed syntax at cursor position.

Features:

• Searchable list of all diagrams
• Shows diagram type icon (Draw.io or Excalidraw)
• Displays file metadata
• Inserts ![[diagram-name]] at cursor

Open Diagram

Command: Noted: Open Diagram

Click any diagram in the panel to open it in the appropriate editor:

• .drawio files open in Draw.io Integration extension
• .excalidraw files open in Excalidraw extension

Refresh Diagrams

Command: Noted: Refresh Diagrams

Manually refresh the diagrams panel to detect new or changed diagram files.

Diagram Types and Rendering

Raw Diagram Files

Draw.io (.drawio):

• Opens in Draw.io Integration editor
• Embeds show as clickable link in custom preview
• Shows “Export as .svg or .png to embed in preview” message
• Click to open in editor

Excalidraw (.excalidraw):

• Opens in Excalidraw editor
• Embeds show as clickable link in custom preview
• Shows “Export as .svg or .png to embed in preview” message
• Click to open in editor

Exported Diagram Files

SVG (.excalidraw.svg, .drawio.svg):

• Renders inline as vector image in custom preview
• Scalable without quality loss
• Perfect for documentation

PNG (.excalidraw.png, .drawio.png):

• Renders inline as raster image in custom preview
• Good for sharing and presentations

Automatic Diagram Discovery

v1.31.7+: Noted automatically searches for diagrams in a sibling Diagrams/ folder, even if it’s not in your VS Code workspace!

How It Works

When you embed a diagram like ![[my-diagram.drawio]], Noted searches:

1. Relative to current note - Same folder as your note
2. Sibling Diagrams folder - If your note is in Notes/, it checks Diagrams/ ✨ NEW
3. Workspace folders - All folders in your VS Code workspace
4. Recursive search - Deep search through workspace

Example Setup

WorkNotes/
├── Notes/
│   └── 2025/
│       └── 10-October/
│           └── 2025-10-27.md
└── Diagrams/
    ├── architecture.drawio
    ├── flowchart.excalidraw
    └── wireframe.excalidraw.svg

In 2025-10-27.md, you can simply write:

![[architecture.drawio]]
![[flowchart.excalidraw]]
![[wireframe.excalidraw.svg]]

Noted automatically finds diagrams in ../../../Diagrams/ without needing to add WorkNotes/ to your workspace!

Custom Preview Command

Command: Noted: Open Preview (with Diagram Support)

Opens a custom markdown preview panel with full diagram embed support:

• ✅ Renders exported diagrams (.svg, .png) inline
• ✅ Shows clickable links for raw diagrams (.drawio, .excalidraw)
• ✅ Proper permissions for sibling Diagrams folder access
• ✅ Live updates as you edit

Why use custom preview? VS Code’s built-in markdown preview doesn’t support markdown-it plugins for diagram embeds. The custom preview solves this by:

• Processing embeds before markdown rendering
• Setting proper webview resource permissions
• Supporting files outside workspace folders

Configuration

Diagrams Folder Location

Setting: noted.diagramsFolder

Default: "Diagrams"

Description: Folder name where diagram files are stored. Can be just a folder name or a full path.

Example:

{
  "noted.diagramsFolder": "Diagrams"  // Sibling folder (recommended)
}

Change to organize diagrams differently:

{
  "noted.diagramsFolder": "assets/diagrams"  // Subfolder
}

Or use a full path:

{
  "noted.diagramsFolder": "/Users/yourname/Documents/Diagrams"  // Absolute path
}

Requirements

Draw.io Integration

Extension: Draw.io Integration

Install:

1. Open Extensions (Cmd+Shift+X)
2. Search for “Draw.io Integration”
3. Click Install

Excalidraw

Extension: Excalidraw

Install:

1. Open Extensions (Cmd+Shift+X)
2. Search for “Excalidraw”
3. Click Install

Use Cases

Architecture Documentation

Create system architecture diagrams with Draw.io:

# System Architecture

Our microservices architecture:

![[architecture.drawio]]

## Database Design

Entity relationships:

![[database-schema.drawio]]

UI/UX Design

Create wireframes and mockups with Excalidraw:

# Feature: User Dashboard

## Wireframes

Initial concept:
![[dashboard-wireframe.excalidraw]]

Refined design:
![[dashboard-v2.excalidraw.svg|Dashboard Mockup]]

Process Flows

Document workflows and processes:

# Deployment Process

## CI/CD Pipeline

![[cicd-flow.drawio]]

## Release Workflow

1. Code review
2. Testing (see [[test-strategy]])
3. Staging deployment
4. Production release

![[release-process.drawio]]

Technical Diagrams

Create technical diagrams for documentation:

# API Design

## Request Flow

![[api-flow.excalidraw]]

## Authentication Sequence

![[auth-sequence.drawio]]

## Data Model

![[data-model.drawio.svg|Database Schema]]

Tips and Best Practices

Naming Conventions

Use descriptive, consistent names:

Good:

• user-authentication-flow.drawio
• database-schema-v2.drawio
• dashboard-wireframe.excalidraw

Avoid:

• diagram1.drawio
• untitled.excalidraw
• test.drawio

Organization Strategies

By Feature:

Diagrams/
├── auth-flow.drawio
├── auth-sequence.drawio
├── user-dashboard.excalidraw
└── user-profile.excalidraw

By Type:

Diagrams/
├── architecture/
│   ├── system-overview.drawio
│   └── microservices.drawio
├── wireframes/
│   ├── dashboard.excalidraw
│   └── settings.excalidraw
└── flows/
    ├── signup.drawio
    └── checkout.drawio

Version Control

Include version numbers in diagram names:

# Feature Evolution

Initial design:
![[feature-v1.excalidraw]]

Current design:
![[feature-v2.excalidraw]]

Future concept:
![[feature-v3.excalidraw]]

Export for Presentations

Export diagrams to SVG or PNG for:

• Documentation that needs to be self-contained
• Presentations and slide decks
• Sharing with non-VS Code users
• Version control (track visual changes)

Workflow:

1. Create and edit diagram: architecture.drawio
2. Export to SVG: architecture.drawio.svg
3. Embed exported version: ![[architecture.drawio.svg]]
4. Update source when needed

Linking Diagrams and Notes

Connect diagrams to relevant notes:

# Database Migration

See architecture diagram: ![[database-schema.drawio]]

Related notes:
- [[migration-plan]]
- [[data-model-changes]]
- [[rollback-strategy]]

Troubleshooting

Diagram Not Showing in Panel

Problem: Created diagram doesn’t appear in panel

Solutions:

1. Click Refresh button in panel toolbar
2. Ensure file is in Diagrams folder
3. Check file extension (.drawio or .excalidraw)
4. Restart VS Code if needed

Cannot Edit Diagram

Problem: Clicking diagram doesn’t open editor

Solutions:

1. Draw.io files: Install Draw.io Integration
2. Excalidraw files: Install Excalidraw
3. Right-click diagram → “Open With…” → Select editor
4. Verify extensions are enabled

Embed Not Working in Custom Preview

Problem: Diagram embed shows broken image or link

Solutions:

1. Verify diagram file exists in Diagrams folder (sibling to Notes/)
2. Check file path is correct (case-sensitive)
3. Ensure embed syntax is correct: ![[diagram-name.ext]]
4. Use Noted: Open Preview (with Diagram Support) command (not built-in preview)
5. For exported diagrams (.svg, .png), verify the export was successful
6. Check console output for path resolution logs
7. If using custom folder structure, verify noted.diagramsFolder setting

Path Resolution Order:

1. Same folder as note
2. Sibling Diagrams folder (automatic)
3. Workspace folders
4. Recursive workspace search

Embed Works in Hover but Not Preview

Problem: Hover preview shows diagram but custom preview doesn’t

Solution: This is expected behavior for raw diagrams (.drawio, .excalidraw):

• Raw diagrams show as clickable links in preview (cannot render natively)
• Export diagrams to .svg or .png to see them rendered inline
• Hover previews work differently than custom preview rendering

Diagrams Folder Not Created

Problem: Diagrams folder doesn’t exist

Solution: Create first diagram - folder will be created automatically

Or manually create:

mkdir -p Notes/Diagrams

Related Features

• Embeds: Learn about embedding diagrams in notes
• Wiki Links: Link diagrams to related notes
• Templates: Create note templates with diagram placeholders
• Graph View: Visualize relationships between notes and diagrams

Keyboard Shortcuts

No default keyboard shortcuts are assigned. You can customize shortcuts in VS Code:

1. Open Keyboard Shortcuts (Cmd+K Cmd+S)
2. Search for “Noted: Create”
3. Assign shortcuts for diagram commands

Suggested shortcuts:

• Create Draw.io: Cmd+K D (Mac) / Ctrl+K D (Win/Linux)
• Create Excalidraw: Cmd+K E (Mac) / Ctrl+K E (Win/Linux)
• Insert Diagram: Cmd+K I (Mac) / Ctrl+K I (Win/Linux)

Next Steps

1. Install Extensions: Get Draw.io Integration and/or Excalidraw
2. Create First Diagram: Click + in Diagrams panel
3. Embed in Note: Paste copied syntax into any note
4. Organize: Develop naming conventions and folder structure
5. Explore: Try both diagram types to find what works best

Start visualizing your ideas with the Diagrams Panel! 🎨