EzImage

---

EzImage for Obsidian solves the fundamental pain point of image management in Obsidian: by default, pasted images are saved as local files that clutter your vault. EzImage intercepts every paste and drop event, uploads the image to your cloud storage, and inserts a clean Markdown link — keeping your vault free of binary files.

✨ Features

• 🖼️ Seamless Paste Interception — Paste an image anywhere in your notes; EzImage intercepts the event before Obsidian can save it locally, uploads it, and inserts ![image](url) at the cursor.
• 🖱️ Drag & Drop Support — Drag image files directly from Finder / Explorer into the editor for automatic upload.
• 📉 Automatic WebP Compression — Powered by browser-image-compression. Images are converted to WebP and resized before upload, reducing file size without visible quality loss.
• 📂 Flexible Path Templates — Full control over the upload path using variables: {yyyy} {MM} {dd} {timestamp} {random} {name} {ext}.
• ☁️ Cloudflare R2 — Zero egress fees, S3-compatible API, global CDN. More providers coming.
• 🔒 Local Signing — AWS Signature V4 is computed entirely on-device using the Web Crypto API. Your credentials never leave your machine.

📦 Installation

Method A: Community Plugins (Recommended)

1. Open Obsidian → Settings → Community Plugins → Browse.
2. Search for EzImage and click Install, then Enable.

Method B: Manual (BRAT / direct)

1. Download main.js and manifest.json from GitHub Releases.
2. Copy both files to <your-vault>/.obsidian/plugins/ezimage/.
3. Reload Obsidian and enable the plugin under Settings → Community Plugins.

⚙️ Configuration

Open Settings → EzImage and fill in your Cloudflare R2 credentials:

Field	Description
Account ID	Found on the right sidebar of your Cloudflare dashboard
Access Key ID	R2 API token — requires Object Read & Write permission
Secret Access Key	Paired secret for the access key
Bucket Name	The R2 bucket to upload images into
Public URL	Your bucket's public URL, e.g. https://pub-xxx.r2.dev or a custom domain

How to get R2 credentials

1. Go to Cloudflare Dashboard → R2 → Manage API tokens.
2. Create a token with Object Read & Write permission scoped to your bucket.
3. Copy Account ID, Access Key ID, and Secret Access Key.
4. Make sure your bucket has Public Access enabled (or use a custom domain with a Worker).

Image Processing Options

Option	Default	Description
Compress Images	true	Convert to WebP before upload
Max Width	1920	Resize if wider than this (px). 0 = no limit
Quality	85	WebP quality (1–100)
Path Template	{yyyy}/{MM}/{timestamp}-{random}.{ext}	Upload path pattern

Template variables: {yyyy} {MM} {dd} {hh} {mm} {ss} {timestamp} {random} {name} {ext}

🚀 Usage

Action	How
Paste image	Copy any image → paste in editor — upload happens automatically
Drag & drop	Drag image file(s) from your file manager into the editor
Upload from file	Command Palette → EzImage: Upload Image from File
Upload clipboard	Command Palette → EzImage: Upload Clipboard Image
Context menu	Right-click in editor → EzImage options

Note: EzImage only intercepts events when R2 is configured. If credentials are missing, Obsidian's default behaviour (local save) is preserved.

🗺️ Roadmap

• Cloudflare R2 support
• Automatic WebP compression
• Paste & drag-drop interception
• Flexible path templates
• AWS S3 / generic S3-compatible providers
• Aliyun OSS & Tencent COS
• GitHub / Gitee image hosting mode
• Upload history panel

🤝 Contribution & Feedback

Found a bug or have a feature request? Please open an issue.

Pull requests are welcome. See the development setup below.

Development

git clone https://github.com/keepwonder/ezimage-obsidian.git
cd ezimage-obsidian
npm install

# Watch mode (outputs main.js)
npm run dev

# Production build
npm run build

Copy main.js and manifest.json into your vault's plugin folder to test locally.

---

📞 Contact & Support

💬 Feedback

Scan the QR code below to add the author on WeChat, please mention "EzImage":

☕ Support the Author

If EzImage has improved your workflow, feel free to buy me a coffee!

---

Developed with ❤️ by Kiang