✅ How Image Overlays Work

Due to VS Code's limitations compared to Emacs overlays, the extension uses Hover Previews - Full-size image preview when hovering over image links

Thumbnails are automatically generated and cached for performance, using ImageMagick or native macOS tools when available.

✅ Basic Image Links

The simplest way to include an image is with a basic link:

[[./_static/logo.svg]]

This displays the image inline and can be clicked to open.

✅ File Protocol Links

You can explicitly use the file: protocol:

[[file:./_static/logo.svg]]

Both formats work identically - the file: prefix is optional for local files.

✅ Links with Descriptions

Add descriptive text that appears as a clickable link:

[[./_static/logo.svg][My beautiful diagram]]
[[file:./_static/logo.svg][Demo Screenshot]]

The description text is shown in the editor, while the image overlay appears in the gutter or inline.

✅ Absolute vs Relative Paths

Both absolute and relative paths are supported:

# Relative to current file
[[./_static/logo.svg]]


# Absolute paths
[[file:/Users/jkitchin/Dropbox/projects/scimax_vscode/docs/_static/logo.svg]]
[[file:~/Dropbox/projects/scimax_vscode/docs/_static/logo.svg]]

The ~ (tilde) is expanded to the home directory on Unix-like systems.

✅ Remote Images

Remote image URLs are not displayed as overlays but are still valid links:

These links work for navigation but won't show thumbnails in the editor.

✅ ATTR_ORG Keyword

Control how images are displayed using the #+ATTR_ORG: keyword above the image link:

#+ATTR_ORG: :width 400
[[_static/logo.svg]]

✅ Supported Attributes

✅ Export-Specific Attributes

For LaTeX and HTML export, use backend-specific attributes:

See Export Documentation for more details on export attributes.

✅ Adding Captions

Add captions that appear in exports:

✅ Global Toggle

Toggle image overlays for all org files:

• Command: Scimax: Toggle Image Overlays

• Command ID: [[cmd:scimax.imageOverlays.toggle]]

✅ Per-File Toggle

Toggle image overlays for the current file only:

• Command: Scimax: Toggle Image Overlays for Current File

• Command ID: scimax.imageOverlays.toggleCurrentFile

This is useful when you want overlays disabled for one specific large document but enabled globally.

✅ Via Configuration

Permanently enable or disable in your settings.json:

{
  "scimax.imageOverlays.enabled": true
}

Set to false to disable by default.

✅ scimax.imageOverlays.enabled

Enable or disable inline image thumbnails globally.

{
  "scimax.imageOverlays.enabled": true
}

✅ scimax.imageOverlays.maxWidth

Maximum width in pixels for thumbnail icons. Thumbnails are scaled down to fit within these dimensions while maintaining aspect ratio.

{
  "scimax.imageOverlays.maxWidth": 128
}

✅ scimax.imageOverlays.maxHeight

Maximum height in pixels for thumbnail icons.

{
  "scimax.imageOverlays.maxHeight": 128
}

✅ scimax.imageOverlays.renderMode

Controls where image thumbnails are displayed:

• gutter - Show thumbnail in the editor gutter (line margin) - recommended

• after - Show emoji and dimensions inline after the link text

• both - Show both gutter thumbnail and inline decoration

{
  "scimax.imageOverlays.renderMode": "gutter"
}

• Use gutter for a clean, unobtrusive experience

• Use after if you prefer inline indicators

• Use both for maximum visibility

✅ scimax.imageOverlays.onlyWhenCursorNotInLink

Hide the overlay when your cursor is inside the image link. This prevents the thumbnail from obscuring the link text you're editing.

{
  "scimax.imageOverlays.onlyWhenCursorNotInLink": true
}

Set to false to always show overlays, even when editing.

✅ scimax.imageOverlays.excludePatterns

Regex patterns for image paths to exclude from overlay display. Useful for hiding certain directories or file patterns.

{
  "scimax.imageOverlays.excludePatterns": [
    "\\.tmp/",
    "/archive/",
    "draft-.*\\.png"
  ]
}

Examples:

• "\\.tmp/" - Exclude images in .tmp directories

• "^http" - Exclude remote URLs (already excluded by default)

• "screenshot-.*" - Exclude files starting with "screenshot-"

✅ scimax.imageOverlays.maxOverlaysPerDocument

Maximum number of image overlays to display per document. This prevents performance issues in documents with hundreds of images.

{
  "scimax.imageOverlays.maxOverlaysPerDocument": 500
}

If your document exceeds this limit, you'll see a warning message.

✅ scimax.imageOverlays.showDimensions

When using after or both render modes, show image dimensions (e.g., "800x600") in the inline decoration.

{
  "scimax.imageOverlays.showDimensions": true
}

✅ scimax.imageOverlays.cacheEnabled

Enable thumbnail caching for faster loading. Thumbnails are stored in the extension's global storage directory.

{
  "scimax.imageOverlays.cacheEnabled": true
}

Set to false to disable caching (may impact performance).

✅ Jupyter Kernel Output

Jupyter kernels automatically save image output to the .ob-jupyter/ directory:

import matplotlib.pyplot as plt
import numpy as np

plt.plot([1, 2, 3, 4], [1, 4, 9, 16])
plt.show()

These images are automatically displayed as overlays when image overlays are enabled.

See Jupyter Documentation for more details on Jupyter integration.

✅ Scimax: Toggle Image Overlays

Toggle image overlays globally for all org files. When disabled, no thumbnails are shown but links remain functional.

✅ Scimax: Toggle Image Overlays for Current File

Toggle image overlays for the currently active org file only. Useful for temporarily hiding overlays in specific documents.

✅ Scimax: Refresh Image Overlays

Manually refresh all image overlays in visible editors. This can be useful if:

• You've modified image files externally

• Overlays aren't updating correctly

• You've changed configuration settings

✅ Scimax: Clear Image Overlay Cache

Clear the thumbnail cache. This will:

• Delete all cached thumbnails

• Free up disk space

• Force thumbnails to be regenerated on next display

Useful if thumbnails are corrupted or you want to reclaim space.

✅ Scimax: Show Image Overlay Cache Statistics

Display information about the thumbnail cache:

• Number of cached thumbnails

• Total cache size in KB

Useful for monitoring cache usage.

✅ Images Not Showing

If image overlays aren't displaying:

1. Check if overlays are enabled:

2. Verify the image file exists:

3. Check the file extension:

4. Try refreshing:

5. Check exclude patterns:

✅ Overlays Disappear When Editing

This is normal behavior when scimax.imageOverlays.onlyWhenCursorNotInLink is true (default). The overlay hides when your cursor is inside the link to prevent obscuring the text you're editing.

To always show overlays:

{
  "scimax.imageOverlays.onlyWhenCursorNotInLink": false
}

✅ Performance Issues

If you experience slow performance:

1. Reduce the overlay limit:

2. Reduce thumbnail size:

3. Use gutter mode only:

4. Disable overlays for specific files:

✅ Thumbnails Are Blurry or Corrupted

1. Clear the cache:

2. Check if ImageMagick is installed:

3. Verify the original image isn't corrupted:

✅ Relative Paths Not Resolving

If relative paths aren't working:

1. Use ./ prefix for clarity:

2. Check your working directory:

3. Use absolute paths as a workaround:

✅ Hover Preview Not Working

If hover previews aren't showing:

1. Check hover delay:

2. Verify hover provider is active:

3. Try a different image format:

✅ Minimal Configuration

For basic image overlay functionality:

{
  "scimax.imageOverlays.enabled": true,
  "scimax.imageOverlays.renderMode": "gutter"
}

✅ Power User Configuration

For maximum visual feedback:

{
  "scimax.imageOverlays.enabled": true,
  "scimax.imageOverlays.maxWidth": 128,
  "scimax.imageOverlays.maxHeight": 128,
  "scimax.imageOverlays.renderMode": "both",
  "scimax.imageOverlays.onlyWhenCursorNotInLink": true,
  "scimax.imageOverlays.showDimensions": true,
  "scimax.imageOverlays.maxOverlaysPerDocument": 500,
  "scimax.imageOverlays.cacheEnabled": true
}

✅ Performance-Focused Configuration

For large documents with many images:

{
  "scimax.imageOverlays.enabled": true,
  "scimax.imageOverlays.maxWidth": 64,
  "scimax.imageOverlays.maxHeight": 64,
  "scimax.imageOverlays.renderMode": "gutter",
  "scimax.imageOverlays.onlyWhenCursorNotInLink": true,
  "scimax.imageOverlays.showDimensions": false,
  "scimax.imageOverlays.maxOverlaysPerDocument": 100,
  "scimax.imageOverlays.cacheEnabled": true,
  "scimax.imageOverlays.excludePatterns": ["archive/", "\\.tmp/"]
}

✅ Taking a Screenshot

Press F10 in an org or markdown file to take a screenshot:

1. Press F10 - the screen capture tool activates

2. Select the area you want to capture (or press Escape to cancel)

3. The screenshot is saved to a screenshots/ directory next to your file

4. An image link is automatically inserted at the cursor position

✅ macOS Permission Setup

The first time you use the screenshot command on macOS, you may need to grant screen recording permission to VS Code:

1. Press F10 to trigger the screenshot

2. macOS will show a permission dialog or the capture will fail silently

3. Go to System Settings > Privacy & Security > Screen Recording

4. Enable the checkbox for Visual Studio Code

5. Restart VS Code for the permission to take effect

6. Try F10 again

✅ Inserted Link Format

For org-mode files, the inserted link includes a width attribute:

#+attr_org: :width 800
[[./screenshots/screenshot-2026-01-23-14-30-45.png]]

For markdown files:

![screenshot](./screenshots/screenshot-2026-01-23-14-30-45.png)

The width is automatically determined from the image dimensions (capped at 800 pixels).

✅ Screenshot Directory

Screenshots are saved to a screenshots/ subdirectory relative to the current file. The directory is created automatically if it doesn't exist.

Filenames follow the pattern: screenshot-YYYY-MM-DD-HH-MM-SS.png

✅ Linux Screenshot Tools

On Linux, the extension tries these tools in order and uses the first one found:

1. gnome-screenshot -a (GNOME desktop)

2. scrot -s (lightweight, widely available)

3. flameshot gui (feature-rich, popular choice)

4. maim -s (modern alternative to scrot)

5. import (ImageMagick, works everywhere)

Install at least one of these tools for screenshot functionality.

✅ Command Reference

✅ Thumbnail Generation

Thumbnails are generated using:

1. ImageMagick (convert command) - Preferred, works on all platforms

2. macOS sips - Native macOS tool, used as fallback on Mac

3. Direct copy - If no tools available, original images are used

Thumbnails are cached in the extension's global storage directory with filenames based on:

• MD5 hash of the original image path

• Configured thumbnail dimensions

• Original file extension

✅ Cache Location

Thumbnails are stored in:

• Linux: ~/.config/Code/User/globalStorage/scimax-vscodeimage-overlay-cache

• macOS: ~/Library/Application Support/Code/User/globalStorage/scimax-vscodeimage-overlay-cache

• Windows: %APPDATA%\Code\User\globalStorage\scimax-vscode\image-overlay-cache\

✅ Performance Considerations

• Thumbnail generation is asynchronous and doesn't block the editor

• The cache prevents regenerating thumbnails on each file open

• The maxOverlaysPerDocument setting prevents memory issues with large documents

• Overlays are debounced during typing to avoid excessive updates

• Gutter mode is more performant than after/both modes

✅ VS Code Limitations

Unlike Emacs, VS Code cannot:

• Display arbitrary-sized inline images in the editor

• Replace link text with actual image content

• Provide true "overlay" functionality at the text level

The implementation uses VS Code's decoration API with gutter icons as the closest approximation to Emacs overlays.