Markdown Image Manager

Obsidian Markdown Image Manager

English | 中文

Obsidian image management plugin — manage an image from paste or drag-and-drop through naming, compression, hosting upload, reference updates, browsing, reorganization, and guarded cleanup.

Note: The plugin supports both standard Markdown (![alt](https://raw.githubusercontent.com/ytahml/obsidian-image-manager/HEAD/image.png)) and Obsidian Wiki (![[image.png]]) image references.

The managed-paste format and reorganization conversion settings are independent of image hosting. Upload results use standard Markdown or a valid custom reference template.

---

Feedback & Support

Found a bug or have an idea? Open a GitHub issue so it can be tracked and discussed.

To help diagnose problems quickly, include:

• Obsidian and plugin versions
• Steps to reproduce, plus the expected and actual behavior
• Relevant error messages, logs, or screenshots with sensitive vault information removed

For private questions, contact [email protected]. If you find the plugin useful, consider giving the project a ⭐.

---

Contributing

Contributions are welcome. See CONTRIBUTING.md for the workflow.

---

Feature Overview

---

Image Lifecycle Management

Image management is more than uploading a file. The plugin follows an image through its local creation, reference insertion, optional upload and exact-reference replacement, later rename or reorganization, and finally guarded orphan cleanup.

• Managed mode is the default: this plugin creates the local attachment, applies its naming, path, and optional local-compression settings, then inserts the initial reference.
• Delegated mode lets Obsidian or an external attachment manager own that local work. The plugin observes only public Vault events and current resolvable references, then uses a best-effort transaction handoff for optional automatic upload; it does not integrate with a manager's private lifecycle.
• For each delegated paste or drop, the plugin requires a unique attachment-to-reference match. It revalidates the transaction before retries, replacement, and any local cleanup; stale or ambiguous work leaves the local file and reference unchanged. These checks cannot prove that an external manager has finished, so a later rename, move, or reference rewrite may occur after upload starts.
• If Keep Local Copy is disabled, cleanup uses Obsidian's trash only after the attachment is no longer protected by recent lifecycle changes and fresh scans still show no local references. The scan conservatively recognizes Markdown/Wiki links (including table-escaped Wiki size syntax), HTML, frontmatter, Canvas, and Excalidraw resources; ambiguous references are kept and cannot be selected for cleanup. This protects the current vault; it cannot establish that an image is unused outside the vault.

flowchart LR
    A["Paste or drag and drop"] --> B{"Local handling"}
    B -->|Managed| C["Create attachment\nand insert reference"]
    B -->|Delegated| D["Observe attachment and reference\nbest-effort handoff"]
    C --> E["Optional upload\nand exact-reference replacement"]
    D --> E
    E --> F["Continue local management\nor guarded trash cleanup"]

---

Tech Stack

Zero bundled runtime dependencies — npm packages are used only for development, type checking, testing, and building.

---

Installation

1. Open Settings → Community plugins in Obsidian and search for "Markdown Image Manager"
2. Alternatively, download a release package and extract it to .obsidian/plugins/md-image-manager/
3. Reload Obsidian if needed, then enable the plugin under Settings → Community plugins

---

Development

# Install dependencies
npm install

# Development mode (watch)
npm run dev

# Production build
npm run build

# Lint
npm run lint

# Automated tests
npm test

# Version update (choose the appropriate SemVer level)
npm version patch
# npm version minor
# npm version major

Build artifacts: main.js, manifest.json, styles.css

---

Project Structure

src/
├── main.ts                 # Plugin entry, command registration, event handling, core orchestration
├── settings.ts             # Settings panel UI
├── types.ts                # TypeScript type definitions and defaults
├── constants.ts            # Regular expressions, MIME type mappings
├── i18n/
│   ├── index.ts            # Internationalization system (locale switching, variable interpolation)
│   ├── en.ts               # English translations (300+ entries)
│   └── zh.ts               # Chinese translations (300+ entries)
├── modals/
│   ├── image-browser.ts    # Local/remote image browser shell
│   ├── remote-image-browser.ts # Remote scan orchestration and safety gates
│   ├── remote-image-grid.ts # Progressive card grid and viewport thumbnails
│   ├── remote-image-preview.ts # Remote preview and reference locations
│   ├── remote-folder-picker.ts # Provider virtual-folder picker
│   ├── remote-delete-confirm.ts # Guarded remote delete confirmation
│   ├── remote-delete-results.ts # Per-object delete results
│   ├── image-preview-modal.ts  # Image preview (metadata, reference list, upload actions)
│   ├── orphan-images.ts    # Orphan image detection and batch deletion
│   ├── hosting-config.ts   # Image hosting config form (4 providers)
│   ├── confirm-dialog.ts   # Generic confirmation dialog
│   ├── rename-image.ts     # Image rename dialog
│   └── image-name-prompt.ts # Image naming prompt on paste
├── uploaders/
│   ├── uploader-base.ts    # Uploader abstract base class
│   ├── uploader-factory.ts # Uploader factory (instantiate by type)
│   ├── upload-service.ts   # Unified direct, note, batch, and paste upload orchestration
│   ├── aliyun-oss.ts       # Aliyun OSS (OSS V4 signing)
│   ├── qiniu.ts            # Qiniu Cloud (Token auth, region endpoints)
│   ├── s3-compatible.ts    # S3 compatible storage (AWS SigV4)
│   ├── public-url.ts       # Public URL base normalization and joining
│   ├── custom-uploader.ts  # Custom HTTP endpoint
│   └── upload-queue.ts     # Concurrent upload queue (3 concurrent, 3 retries, progress callback)
├── remote/                 # Provider-independent remote sessions, safety policies, and native providers
├── oss/
│   └── sigv4.ts            # Shared OSS upload/list/preview/delete signing
├── qiniu/
│   └── auth.ts             # Upload, management, and private-preview authentication
├── s3/
│   └── sigv4.ts            # Shared S3 upload/list/preview/delete signing
└── utils/
    ├── ref-converter.ts    # Reference format parsing and conversion
    ├── reference-template.ts # Uploaded reference template validation and rendering
    ├── image-scanner.ts    # Image scanning, filtering, sorting
    ├── local-orphan-management.ts # Fresh local orphan validation and trash
    ├── path-utils.ts       # Path utilities, file size formatting, template variables
    ├── public-url.ts       # Markdown-safe Unicode URL display
    ├── orphan-finder.ts    # Orphan image detection, reverse reference query
    ├── image-optimizer.ts  # Canvas compression, format conversion
    ├── batch-rename.ts     # Batch rename (sync update all vault references)
    └── image-reorganizer.ts # Image archive organization (path template, reference update)

---

Settings Guide

General

• Language — Plugin display language (Chinese / English)
• Image Storage Path Template — Storage path for pasted images, supports variables:
  • {noteName} — Current note name
  • {notePath} — Current note path
  • {year}, {month}, {day} — Date
  • {filename} — Image filename
• Path Base — Resolve path template relative to "vault root" or "current note's directory"
• Managed Paste Reference Format — Choose whether attachments managed during paste or drop are inserted as standard Markdown (![alt](https://raw.githubusercontent.com/ytahml/obsidian-image-manager/HEAD/path)) or Wiki references (![[path]])
• Convert References When Reorganizing — Convert reorganized references to standard Markdown; when disabled, preserve the original reference format
• Skip Wiki References — Leave Wiki-format references out of image reorganization
• Image Hosting — Upload and generated references are independent of the two format settings and use standard Markdown or a valid custom reference template

Settings Combination Behavior:

Note: Wiki → Markdown conversion is one-way and cannot be automatically reversed.

Image Naming

• Naming Template — Supports variables: {noteName}, {date}, {time}, {timestamp}, {counter}, {year}, {month}, {day}
• Prompt for Image Name — Show name input dialog on paste

Compression

• Auto Compress — Automatically compress images on paste
• Compression Quality — 1-100, lower value = more compression

Gallery

• Thumbnail Size — 80-400 pixels
• Enable Image Browser — Show in sidebar and command palette (requires plugin reload after change)
• Reference Status Filter — Filter local cards by all, referenced, or orphan status after the reference scan completes

Image Hosting

Note: Image hosting is independent of the managed paste-reference format. Upload results use standard Markdown or a valid custom reference template.

• Add Image Hosting — Supports Aliyun OSS, Qiniu Cloud, S3 compatible storage, custom HTTP endpoint
• Upload Path Template — Supports {year}, {month}, {day}, {filename}, {ext}, {hash}, {timestamp}, {sourceDir}
• Public Access URL Base — Base URL used to access uploaded objects; it can include a bucket or directory path. Required for Qiniu
• Custom Reference Template — Optional upload-only template; {fileUrl} is required and file metadata or intrinsic dimensions can be included
• Auto Replace After Upload — Replace references after single-image upload; also sets the initial replacement choice in the scoped upload dialog
• Remote Object Management — Available for Aliyun OSS, Qiniu Kodo, and S3-compatible configurations; scanning remains explicit
• Management Prefix — Limits remote scanning to a bucket prefix; an empty value means the current bucket root and requires confirmation
• Other Reference URL Bases — One HTTP(S) base per line for recognizing CDN, legacy-domain, or alternate public URLs

Remote Management Safety

Aliyun OSS, S3-compatible, and Qiniu remote browsing list objects only after an explicit scan, with a visible loading state for longer scans. Results use an image card grid, and thumbnails load automatically as they approach the viewport; this can incur object-read, original-file transfer, and provider charges. Reference scanning covers Markdown images, plain links, HTML, frontmatter, Wiki wrappers, and raw URLs; every reliably mapped address counts as a reference. Double-click an image or use its Preview button to view its referencing notes and line numbers and jump directly to the source. Objects with no detected reference are labeled "Orphan image" and can be selected for deletion. This does not prove that websites, other vaults, or other applications do not use the object.

Remote object management supports Aliyun OSS, S3-compatible storage, and Qiniu Kodo. In Other reference URL bases, enter one HTTP(S) base per line, with each base ending where the object key begins; do not use commas or semicolons as separators. OSS ListObjectsV2 incurs API request charges; private preview uses a 300-second V4 presigned URL, while public preview uses the configured public access URL base. Grant only oss:ListObjects, oss:GetObject for private previews, and oss:DeleteObject when deletion is required. Archive, Cold Archive, and Deep Cold Archive objects are not previewed automatically. Qiniu requires its public access URL base for public previews and private download-token previews; use separate least-privilege credentials for upload, management, and private download where your Qiniu policy requires them.

Deletion requires selecting eligible objects, typing the exact selected count, and acknowledging that cloud deletion cannot be undone. Selection count is not capped; requests still run with at most two concurrent operations and are never retried automatically. Successful operations are shown as "Request successful"; whether storage space is released depends on the provider's deletion and versioning policy. Use a dedicated bucket or prefix, grant only the permissions required, and verify results by scanning the configured scope again. The plugin keeps up to 200 redacted local diagnostic records of completed delete requests; they never participate in remote-existence, reference, or deletion decisions, and do not contain presigned preview URLs or credentials.

Upload images referenced by notes

Use Upload referenced images from the command palette, or the same upload action on a note/folder's context menu. The command defaults to the entire vault; context-menu actions preselect the clicked note or recursive folder:

1. Choose all Markdown notes in the vault, a folder including subfolders, or one article.
2. Choose the hosting configuration and whether to replace local references. Review the unique-image count and skipped items before uploading.
3. When replacement is enabled, all Markdown notes referencing the same successfully uploaded image are updated, even outside the chosen scope. Local files follow Keep local copy for the current Managed/Delegated mode. When off, only successfully uploaded and replaced images with no remaining references after rescanning are moved to the Obsidian trash; files are kept when replacement is off, conflicts occur, or safety checks fail.

Scope selects notes, not attachment directories. Attachments stored elsewhere are included; unreferenced images and existing remote URLs are excluded. This replaces the older behavior of uploading every image file in the vault. Use single-image upload for an unreferenced image. Markdown images and Wiki embeds are supported; Canvas, HTML and frontmatter rewriting are not included.

Results distinguish upload success/failure, reference updates, conflicts/read/write failures, and local trash/retention/cleanup failures. Concurrent edits are preserved; a successful upload does not guarantee every reference was updated. Closing the progress window does not cancel requests already started.

Only implemented commands are registered. Duplicate scope-specific upload and Wiki-to-Markdown commands have been consolidated into one entry for each operation. If you had a hotkey bound to upload-note-images, convert-reference-format-vault, or convert-to-md, rebind it to Upload referenced images or Convert Wiki images to Markdown.

Auto Upload

• Local Image Management Mode — Choose Managed (this plugin owns local paste/drop handling) or Delegated (Obsidian or an external attachment manager owns local handling)
• Auto Upload on Paste — Automatically upload to default hosting on paste/drag & drop; Managed and Delegated modes save this preference independently
• Keep Local Copy — Shared by paste auto-upload, manual single-image upload, and scoped upload; Managed and Delegated modes save this preference independently. Editable even when paste auto-upload is off. Manual uploads only recycle eligible images, not empty folders.

Switching modes hides settings that do not apply to the selected paste/drop owner without resetting them. Shared path settings remain visible because explicit image reorganization uses them in both modes. In Delegated mode, automatic upload waits until it can uniquely match the created attachment with this paste/drop's newly inserted reference. It replaces only that exact reference and keeps the local file when the transaction becomes ambiguous or changes while an upload is in flight. This is a best-effort handoff based on public Obsidian events; it does not guarantee that an external attachment manager has completed all later processing.

---

Usage

Image Browser

The image browser manages both local images and remote objects from supported hosting configurations.

• Click the image icon in the left sidebar to open
• Switch between Local images and Hosting images
• Local images support search, sort (name/size/modified time/created time), reference-state filtering, safe orphan selection, and preview
• Remote images support explicit scan/continue/refresh, virtual folders, search, sort, reference-state filtering, viewport thumbnails, preview, and guarded orphan deletion
• Click an eligible card to select it; a later single click deselects it without clearing other selections. Ctrl/Cmd-click also toggles the current card without changing other selections
• Shift-click a card or checkbox to select or deselect the range from the anchor; only eligible orphan images can be selected. Checkboxes also support individual toggles. Updating search results resets the range anchor, not the existing selection
• Double-click a card or use its Preview button to preview, copy or insert a local reference, upload a local image, or jump to a referencing note. Double-clicking preserves the selection and range anchor from before the double click. The Preview button also works with touch and keyboard

Paste/Drag & Drop Images

1. In Managed mode, paste or drag & drop an image and the plugin saves it to the configured path and inserts a reference.
2. In Delegated mode, Obsidian or an external attachment manager performs that local step.
3. If Auto Upload on Paste is enabled, the plugin uploads only after it can validate the attachment and the new reference; it then replaces that exact reference.

Upload to Image Hosting

• Single upload: Command palette → Upload image to hosting
• Referenced images: Command palette → Upload referenced images (defaults to the entire vault), or right-click a Markdown note/folder to open the same dialog with that scope preselected
• Successful single-image uploads copy the generated reference to the clipboard

Reference Format Conversion (Wiki → Markdown)

• Command palette → Convert Wiki images to Markdown, then choose the entire vault (default), a recursive folder, or one note
• Right-click a Markdown note or folder → Convert Wiki images to Markdown to run directly on the clicked scope
• Open editors are converted from their live content; conflicting or concurrently changed notes are left unchanged and reported

Note: Conversion is one-way from Wiki images to Markdown. It does not move or delete images.

Orphan Image Detection

• Command palette → "Find Orphan Images"
• The dedicated orphan modal supports select all/deselect all and batch cleanup
• The local browser also supports all/referenced/orphan filtering and revalidates selected orphan images before moving them to Obsidian's configured trash

Image Rename

• Image browser preview → "Rename" button, or command palette → "Rename image", or right-click file → rename in file explorer
• Auto sync update all markdown references, preserving directory paths

Image Resource Organization

• Current Note: Command palette → "Organize Image Resources"
• Folder: Right-click folder → "Organize Image Resources"

Right-click Menu

• Markdown files: Upload referenced images (preselected note), reorganize images, convert Wiki images to Markdown directly
• Folders: Upload referenced images (preselected recursive folder), reorganize images, convert Wiki images to Markdown directly

---

Supported Image Hosting

---

Variable Reference

Image Naming Template

Image Path Template

Upload Path Template

Provider-specific upload paths override the global template. Aliyun OSS, Qiniu, and S3 use these templates; custom HTTP uploaders continue to use the URL returned by their configured JSON response path.

Custom Reference Template

Unknown variables, a missing {fileUrl}, or unavailable requested dimensions cause the uploaded reference to fall back to standard Markdown.

---

Known Limitations

• Does not support Markdown → Wiki format conversion (only Wiki → Markdown one-way conversion)
• Hosting results use standard Markdown or a valid custom reference template; the plugin does not generate Wiki-style hosting references
• Remote reference indexing scans Markdown files in the current vault
• Custom HTTP hosting is upload-only because it has no common list, preview, or delete protocol
• Clipboard writes use the browser navigator.clipboard API; mobile behavior still depends on the host platform and permissions
• Image hosting migration not yet implemented

---

License

Zero-Clause BSD (0BSD)