Paste Image MD - VS Code Extension

A VS Code extension that automatically handles pasting images from the clipboard into markdown files. When you press Ctrl+V (or Cmd+V on Mac) with an image in your clipboard, it will:

1. Save the image as a file in your specified directory
2. Insert the appropriate markdown syntax with the correct path
3. Handle HEIC format conversion automatically
4. Provide smart duplicate filename handling

Features

• Smart Paste Detection: Automatically detects when you're pasting an image vs text
• HEIC Support: Automatically converts Apple HEIC format to your preferred format
• Configurable Image Directory: Save images to a custom directory (default: ./images)
• Multiple Insert Modes: Choose between markdown, HTML, or path-only insertion
• Cross-platform: Works on Windows, macOS, and Linux
• Customizable Naming: Configure image file naming patterns with duplicate handling
• Image Optimization: Built-in compression and format conversion using Sharp
• Alt Text Support: Optional prompting for accessibility-friendly alt text
• Quality Control: Adjustable image quality for JPEG/WebP formats

Usage

1. Copy an image to your clipboard (screenshot, image from browser, etc.)
2. Open a markdown file in VS Code
3. Press Ctrl+V (or Cmd+V on Mac) where you want to insert the image
4. The extension will save the image and insert the markdown syntax automatically

Configuration

Access settings via File > Preferences > Settings and search for "Paste Image MD":

clipboardImagePaste.imageDirectory

• Default: "./images"
• Description: Directory to save pasted images (relative to workspace root or absolute path)

clipboardImagePaste.imageNameFormat

• Default: "image-{timestamp}"
• Description: Format for image names
• Placeholders:
  • {timestamp}: Current timestamp
  • {random}: Random string

clipboardImagePaste.imageFormat

• Default: "png"
• Options: "png", "jpg", "jpeg", "webp"
• Description: Format to save images in

clipboardImagePaste.insertMode

• Default: "markdown"
• Options:
  • "markdown": ![image](https://github.com/mav-mit/paste-image-md/raw/HEAD/path/to/image.png)
  • "html": <img src="https://github.com/mav-mit/paste-image-md/raw/HEAD/path/to/image.png" alt="image" />
  • "path-only": path/to/image.png

clipboardImagePaste.promptForAltText

• Default: false
• Description: Prompt for alt text when pasting images for better accessibility

clipboardImagePaste.imageQuality

• Default: 85
• Range: 1-100
• Description: Image quality for JPEG/WebP formats (higher = better quality, larger file)

Installation

From Source

1. Clone this repository
2. Run npm install to install dependencies
3. Run npm run compile to build the extension
4. Press F5 to run the extension in a new Extension Development Host window

Building VSIX Package

1. Install vsce globally: npm install -g vsce
2. Build the package: vsce package
3. Install the generated .vsix file

Development Setup

1. Prerequisites:

   • Node.js (version 16 or higher)
   • VS Code

2. Clone and Setup:

   git clone https://github.com/mav-mit/paste-image-md.git
   cd paste-image-md
   npm install
   

3. Build:

   npm run compile
   

4. Debug:

   • Open the project in VS Code
   • Press F5 to start debugging
   • This opens a new VS Code window with the extension loaded

Platform-specific Requirements

Windows

• No additional requirements (uses PowerShell)

macOS

• No additional requirements (uses built-in osascript)
• HEIC format automatically supported

Linux

• Requires xclip for clipboard access: sudo apt-get install xclip

File Structure

clipboard-image-paste/
├── src/
│   └── extension.ts          # Main extension code
├── package.json              # Extension manifest
├── tsconfig.json            # TypeScript configuration
└── README.md                # This file

Commands

• clipboardImagePaste.paste: Manually trigger image paste (also bound to Ctrl+V in markdown files)

Troubleshooting

Image not detected in clipboard

• Ensure you've copied an actual image (not just a file path)
• Try copying the image again
• Check that your platform meets the requirements listed above

Permission errors

• Make sure VS Code has permission to write to the specified image directory
• Check that the directory path is correct and accessible

Extension not activating

• Make sure you're in a markdown file (.md or .mdx)
• Check the VS Code output panel for any error messages

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details

Performance & Security

• Local Processing: All image processing happens locally on your machine
• No Data Collection: No telemetry or user data is collected
• Efficient Memory Usage: Images are processed in streams to minimize memory footprint
• Cross-platform Native: Uses platform-specific APIs for optimal performance