MH Image Utils

Summary

MH Image Utils is an Obsidian plugin that adds quality-of-life tools for working with images in notes. It provides a lightbox viewer, image captions, per-image alignment and sizing, GIF rendering support, image file renaming, and paste/drop rename rules.

The plugin is built from TypeScript source in src/. The root main.js file is a generated Obsidian bundle and should not be edited directly.

Purpose And Features

• Open note images in a fullscreen lightbox from Reading View, Live Preview, and Obsidian image tabs.
• Zoom, pan, pinch, reset zoom, navigate between note images, show filenames, and show a zoom indicator.
• Open the current lightbox image in Obsidian or reveal it in the file explorer.
• Show image labels from alt text below the image or in an image corner.
• Configure label display mode, color, background, font size, padding, border radius, gap, and text alignment.
• Use an image context menu to change labels, hide/show labels, hide/show borders, align images, resize images, reset size, rename image files, and open images.
• Render GIF embeds in Live Preview through a CodeMirror widget when possible, with fallback rendering for unresolved embeds.
• Rename images pasted or dropped into notes by rule, including target folder templates and filename templates.
• Optionally add a global counter prefix to saved pasted/dropped images.

The settings UI and rule editor expect MH-API-TEMPORARY to be installed and enabled, because this plugin uses its shared setting groups, modals, item lists, folder suggester, and condition evaluator.

How It Works / How To Use

Click an image in an enabled view to open the lightbox. Use the mouse wheel to zoom, drag to pan after zooming, press Esc to close, use the arrow keys to move between images, and use +, -, or 0 for zoom controls.

Labels come from image alt text. These examples are supported:

![[Images/photo.png|Trip photo]]
![[Images/photo.png|Trip photo|@center|50%]]
![Trip photo|@right|320px|@no-border](Images/photo.png)

Image-specific modifiers are written in the alt text after | separators:

• @left, @center, @right set image alignment.
• 50%, 320, or 320px set image width.
• @hide-label hides the caption for that image.
• @border forces the image border on.
• @no-border forces the image border off.

The plugin does not use frontmatter options. Per-image behavior is controlled through image alt text modifiers, and global behavior is controlled from the plugin settings.

Available settings include:

• Lightbox enabled state, Live Preview support, Reading View support, zoom step, minimum zoom, maximum zoom, cursor-centered or image-centered zoom, filename display, zoom indicator display, and background blur.
• Label mode: off, Live Preview only, Reading View only, or both.
• Label display mode: label only, image name when no label exists, image name plus label, or nothing.
• Label position: below the image or in a configured corner.
• Label style: text color, background color, font size, padding, border radius, label gap, and text alignment.
• Context menu and image border defaults.
• Rename rules enabled state, paste/drop handling, counter prefix, and current counter reset.

Rename rules can use filename variables:

{date}
{datetime}
{time}
{noteName}
{originalName}
{extension}

Target folders can use:

{noteName}
{noteFolder}

Example rename rule:

Pattern: {noteName}-{datetime}
Target folder: Assets/{noteName}

When an image is pasted into Daily Note.md, the saved image can become:

Assets/Daily Note/Daily-Note-2026-06-06-143012.png

Installation

For manual installation, copy these files into an Obsidian vault plugin folder such as .obsidian/plugins/mh-image-utils/:

main.js
manifest.json
versions.json
locales/

Enable MH Image Utils from Obsidian's Community Plugins settings. If the settings UI reports a missing dependency, install and enable MH-API-TEMPORARY as well.

Development

Install dependencies:

npm install

Run a development watch build:

npm run dev

Run TypeScript validation:

npm run typecheck

Create a production bundle:

npm run build

Validate the generated bundle syntax:

node --check main.js

Source code lives in src/. The build entrypoint is src/main.ts, and main.js is generated by esbuild with obsidian and CodeMirror packages kept external for the Obsidian runtime.