EzImage

EzImage

---

EzImage for Obsidian solves the fundamental pain point of image management in Obsidian: pasted images pollute your vault with local binary files, or worse, reference paths that break across machines. EzImage intercepts every paste and drop event and either uploads the image to your cloud storage (inserting a clean Markdown URL) or saves it to the vault via a wikilink — whichever mode you prefer, switchable at any time from the status bar.

✨ Features

• 🖼️ Seamless Paste Interception — Paste an image anywhere in your notes; EzImage intercepts the event before Obsidian, then either uploads it or saves it locally depending on the current mode.
• 🖱️ Drag & Drop Support — Drag image files directly from Finder / Explorer into the editor. EzImage copies the file into your vault or uploads it — not just references the original path.
• ☁️ Upload Mode — Images are uploaded to Cloudflare R2 and a ![image](https://raw.githubusercontent.com/keepwonder/ezimage-obsidian/HEAD/url) link is inserted. Zero local files, zero broken paths.
• 💾 Local Save Mode — Images are saved to your vault's configured attachment folder and inserted as ![[wikilink]]. Fully managed by Obsidian's native structure.
• ⚡ Mode Toggle — Switch between Upload and Local Save mode via the Settings toggle or Command Palette (EzImage: Toggle Local Save Mode). The status bar always shows the current mode at a glance.
• 📉 Automatic WebP Compression — Powered by browser-image-compression. Images are converted to WebP and resized before upload, reducing file size without visible quality loss. EXIF metadata is stripped automatically during conversion.
• 🔏 EXIF Metadata Stripping — When compression is disabled, EzImage redraws the image via Canvas before upload, removing GPS location, device info, and other metadata. No extra dependency required.
• 🛡️ Upload Reliability — Failed uploads are automatically retried up to 2 times with back-off. Credential errors surface a clear "check Settings" message; network errors prompt to check your connection.
• 📂 Flexible Path Templates — Full control over the upload path using variables: {yyyy} {MM} {dd} {timestamp} {random} {name} {ext}.
• 🌐 Language Support — Settings UI available in English and 中文, or auto-detected from Obsidian.
• 🔒 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 credentials and preferences.

Cloudflare R2

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

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

General

🚀 Usage

Status Bar

The status bar item is a read-only indicator of the current mode:

To switch modes, use the Settings toggle or Command Palette → EzImage: Toggle Local Save Mode (bindable to a hotkey). The tooltip follows your configured language.

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

🗺️ Roadmap

• Cloudflare R2 support
• Automatic WebP compression with EXIF stripping
• Paste & drag-drop interception
• Flexible path templates with live preview
• Local Save mode with status bar indicator
• Language support (EN / 中文)
• File size limit & input validation
• Auto-retry on network errors
• EXIF metadata stripping (when compression is off)
• 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!

---