Note, Image, and Diagram Embeds

What are Note, Image, and Diagram Embeds?

Embed entire notes, specific sections, images, and diagrams directly into your notes with ![[embed]] syntax. Create reusable content and rich, interconnected documents with visual elements.

Quick Start

Embed a note:

![[meeting-notes]]

Embed a section:

![[project-overview#Goals]]

Embed an image:

![[screenshot.png]]

Embed a diagram:

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

Note Embeds

Full Note Embeds

Include the entire content of another note:

# Project Status

## Latest Updates
![[daily-standup]]

## Roadmap
![[project-roadmap]]

Result: The complete content of each note appears inline.

Section Embeds

Embed specific sections from notes:

# Sprint Planning

## Current Goals
![[project-overview#Goals]]

## Team Capacity
![[team-info#Availability]]

Supported Section Formats:

Markdown Headings:

# Section Title
## Subsection
### Sub-subsection

Text-Style Headings:

SECTION TITLE:
Goals:
NEXT STEPS:

Custom Display Text

Use pipe syntax for custom labels:

![[meeting-notes|Latest Meeting]]
![[api-docs#Authentication|How to Authenticate]]

The display text appears instead of the note name in the embed.

Section Matching

Section matching is case-insensitive for convenience:

![[note#goals]]      ← Matches "Goals", "GOALS", "goals"
![[note#API]]        ← Matches "api", "Api", "API"

Finding Sections

Hover over an embed to see:

• Available sections in the note
• Preview of the section content
• Quick “Open note” link

Example hover tooltip:

Note: project-overview
Available sections:
- Overview
- Goals
- Timeline
- Team

[Open note →]

Image Embeds

Supported Formats

Embed images in these formats:

• PNG (.png)
• JPEG (.jpg, .jpeg)
• GIF (.gif)
• SVG (.svg)
• WebP (.webp)
• BMP (.bmp)
• ICO (.ico)

Image Syntax

Simple embed:

![[screenshot.png]]

With caption:

![[diagram.png|Architecture Diagram]]

Image Paths

Noted supports flexible path resolution:

Absolute paths:

![[/Users/john/Pictures/screenshot.png]]

Relative to note:

![[./images/photo.jpg]]
![[../assets/logo.png]]

Relative to workspace:

![[assets/screenshots/feature.png]]

Smart Resolution:

1. Tries the exact path first
2. Searches the note’s directory
3. Searches workspace folders
4. Reports error if not found

Image Metadata

Hover over an image embed to see:

• Image preview (full size)
• File size
• Dimensions (when available)
• File path

Example hover:

[Image preview shown]

logo.png
Size: 45.2 KB
Path: /workspace/assets/logo.png

[Open in system viewer →]

Diagram Embeds

Supported Formats

Embed diagrams created with popular diagramming tools:

Draw.io (diagrams.net):

• .drawio - Raw Draw.io diagram files

Excalidraw:

• .excalidraw - Raw Excalidraw diagram files
• .excalidraw.svg - Excalidraw exported as SVG
• .excalidraw.png - Excalidraw exported as PNG

Required Extensions

To create and edit diagram files, install one of these VS Code extensions:

Draw.io Integration (hediet.vscode-drawio):

• Full Draw.io editor in VS Code
• Create and edit .drawio files
• Export to PNG, SVG, and other formats

Excalidraw (pomdtr.excalidraw-editor):

• Hand-drawn style diagrams
• Create and edit .excalidraw files
• Export to .excalidraw.svg or .excalidraw.png

Diagram Syntax

Embed a Draw.io diagram:

![[system-architecture.drawio]]

Embed an Excalidraw diagram:

![[user-flow.excalidraw]]

Embed exported diagrams (render inline):

![[diagram.excalidraw.svg]]
![[flowchart.excalidraw.png]]

With custom caption:

![[architecture.drawio|System Architecture]]
![[wireframe.excalidraw|Login Flow Mockup]]

How Diagrams Render

Raw diagram files (.drawio, .excalidraw):

• Show as clickable links in embeds
• Click to open in the respective editor
• Perfect for editable, working diagrams

Example:

📊 Draw.io diagram: architecture.drawio
Click to open in Draw.io editor

Exported diagram files (.svg, .png):

• Render inline as images
• Display directly in notes and previews
• Best for final, presentation-ready diagrams

Diagram Paths

Like images, diagrams support flexible path resolution:

Relative to note:

![[./diagrams/architecture.drawio]]
![[../assets/wireframe.excalidraw]]

Relative to workspace:

![[diagrams/system-design.drawio]]
![[assets/mockups/login.excalidraw.svg]]

Absolute paths:

![[/Users/john/Documents/diagrams/flowchart.drawio]]

Diagram Organization

Organize diagrams by project or type:

assets/
  └── diagrams/
      ├── architecture/
      │   ├── system-overview.drawio
      │   └── database-schema.drawio
      ├── wireframes/
      │   ├── login-flow.excalidraw
      │   └── dashboard.excalidraw
      └── exported/
          ├── system-overview.drawio.svg
          └── login-flow.excalidraw.png

Diagram Workflow

Option 1: Working Diagrams

Embed raw diagram files for documents that need frequent updates:

1. Create architecture.drawio in Draw.io extension
2. Embed in notes: ![[architecture.drawio]]
3. Click to edit anytime
4. No export needed - always up-to-date!

Option 2: Published Diagrams

Export diagrams for final documentation:

1. Create diagram in editor
2. Export as .svg or .png
3. Embed exported file: ![[diagram.drawio.svg]]
4. Renders inline in notes and previews
5. Re-export when diagram changes

Best of Both:

Keep both versions for flexibility:

# System Architecture

**Working diagram:** ![[architecture.drawio]]
**Published view:** ![[architecture.drawio.svg]]

Diagram Metadata

Hover over a diagram embed to see:

• Diagram type (Draw.io or Excalidraw)
• File size
• Preview (for exported formats)
• Required editor extension
• Quick “Open diagram” link

Example hover:

📊 Excalidraw Diagram: wireframe.excalidraw

[Preview shown for .svg/.png]

File info:
- Path: /workspace/diagrams/wireframe.excalidraw
- Size: 12.3 KB
- Editor: Excalidraw (pomdtr.excalidraw-editor)

[Open diagram →]

Live Updates (Transclusion)

Embeds update automatically when source content changes:

1. Edit source note:

   # meeting-notes
   Discussed new feature
   

2. Source is embedded elsewhere:

   # Project Log
   ![[meeting-notes]]
   

3. Edit and save meeting-notes → Embed updates in Project Log instantly!

What updates:

• Note content changes
• Section content changes
• Image file changes
• Diagram file changes (for exported formats)

When updates happen:

• On file save
• On file change (even from outside VS Code)
• Automatically in the background

Note for diagrams: Raw diagram files (.drawio, .excalidraw) show as links, so they don’t need live updates. Exported formats (.svg, .png) update when you re-export the diagram.

Visual Indicators

Embeds show inline icons for quick identification:

• 📄 Note embeds
• 🖼️ Image embeds
• 📊 Diagram embeds

These appear in the editor as decorations next to embed syntax.

Use Cases

Reusable Snippets

Create once, embed everywhere:

# common-troubleshooting

## Database Connection
1. Check credentials
2. Verify network access
3. Test connection string

Use in multiple notes:

# support-ticket-123
![[common-troubleshooting#Database Connection]]

# support-ticket-456
![[common-troubleshooting#Database Connection]]

Update common-troubleshooting → All embeds update automatically!

Meeting Agendas

Embed recurring sections:

# weekly-standup-template

## Standard Agenda
1. Wins
2. Challenges
3. Next Week

---

# standup-2024-10-23
![[weekly-standup-template#Standard Agenda]]

**Wins:**
- Launched feature X

Documentation

Build comprehensive docs from smaller notes:

# api-documentation

## Authentication
![[auth-guide]]

## Endpoints
![[api-endpoints#User Management]]
![[api-endpoints#Data Access]]

## Examples
![[api-examples]]

Image Galleries

Create visual documentation:

# feature-screenshots

## Login Flow
![[screens/login.png|Step 1: Login]]
![[screens/auth.png|Step 2: 2FA]]
![[screens/dashboard.png|Step 3: Dashboard]]

## Admin Panel
![[screens/admin-users.png|User Management]]
![[screens/admin-settings.png|Settings]]

Technical Documentation with Diagrams

Combine notes, images, and diagrams:

# system-design

## Architecture Overview
![[docs/architecture-overview]]

## System Diagram
![[diagrams/system-architecture.drawio.svg|Complete System Architecture]]

## Database Schema
![[diagrams/database-schema.drawio.svg|Entity Relationship Diagram]]

## User Flow
![[diagrams/user-journey.excalidraw.svg|User Journey Map]]

## Screenshots
![[screens/dashboard.png|Dashboard View]]
![[screens/analytics.png|Analytics Panel]]

Project Dashboards

Aggregate information from multiple notes:

# project-dashboard

## Current Sprint
![[sprint-5#Goals]]
![[sprint-5#Progress]]

## Team Status
![[team-alice#This Week]]
![[team-bob#This Week]]
![[team-charlie#This Week]]

## Metrics
![[metrics/burndown.png|Sprint Burndown]]
![[metrics/velocity.png|Team Velocity]]

Best Practices

1. Use Sections for Specificity: Embed specific sections rather than entire long notes
2. Descriptive Display Text: Use |Display Text for clarity
3. Organize Images: Keep images in dedicated folders (e.g., assets/, images/)
4. Organize Diagrams: Keep diagrams in a dedicated diagrams/ folder with subfolders by type
5. Relative Paths: Use relative paths for portability across machines
6. Keep Sources Clean: Maintain source notes as single sources of truth
7. Version Control: Commit notes, images, and diagrams to git
8. Diagram Exports: Keep both raw and exported versions for flexibility
9. Choose Diagram Format: Use .drawio for flowcharts/UML, .excalidraw for sketches/wireframes

Tips & Tricks

Preview Before Embedding

Hover over any [[note]] link to preview content before deciding to embed.

Find All Embeds

Search for ![[ to find all embeds in your workspace:

Command: Noted: Search Notes
Query: ![[

Embed Chains

Embeds can contain other embeds:

# note-a
Content A

# note-b
![[note-a]]
Content B

# note-c
![[note-b]]
Content C

note-c will show: Content A → Content B → Content C

Image and Diagram Organization

Organize visual assets by project or date:

assets/
  ├── 2024-10/
  │   ├── screenshot-1.png
  │   └── screenshot-2.png
  ├── diagrams/
  │   ├── architecture.drawio
  │   ├── architecture.drawio.svg
  │   ├── wireframe.excalidraw
  │   └── wireframe.excalidraw.png
  └── project-alpha/
      ├── mockups.png
      └── system-design.drawio

Reference with relative paths:

![[../assets/2024-10/screenshot-1.png]]
![[../assets/diagrams/architecture.drawio.svg]]

Embed Status Updates

Create a “status” note that’s embedded in many places:

# project-status
🟢 All systems operational
Last updated: 2024-10-23

Embed in relevant notes:

![[project-status]]

Update once → All references show new status!

Troubleshooting

Embed Not Showing

Check that:

• Source note exists and is saved
• Section name matches exactly (case-insensitive, but must exist)
• Syntax is correct: ![[note]] or ![[note#Section]]

Image Not Displaying

Verify:

• Image file exists at the path
• File extension is supported
• Path is correct (try absolute path first)
• File isn’t corrupted

Diagram Not Showing

For raw diagram files:

• Ensure you have the required VS Code extension installed
• Check that the diagram file exists at the path
• Syntax should be: ![[diagram.drawio]] or ![[diagram.excalidraw]]

For exported diagram files:

• Verify the exported file exists (.svg or .png)
• Check file extension matches exactly
• Re-export if diagram was recently updated

Performance

For large embeds:

• Consider embedding specific sections instead of entire notes
• Use compressed images (WebP is efficient)
• Export large diagrams as PNG for faster loading
• Limit number of embeds per note (10-20 is reasonable)

Related Features

• Wiki-Style Links - Link to notes without embedding
• Connections Panel - See where notes are embedded
• Graph View - Visualize note relationships
• Templates - Create reusable note structures

---

Build rich, interconnected documentation with embeds! 📄🖼️📊