Obsidian paste image rename

:loudspeaker: Starting from 1.4.0, Paste image rename becomes a general-purpose renaming plugin

that can handle all attachments added to the vault.

This plugin is inspired by Zettlr, Zettlr shows a prompt that allows the user to rename the image, this is a great help if you want your images to be named and organized clearly.

Paste image rename plugin not only implements Zettlr's feature, but also allows you to customize how the image name would be generated, and eventually free you from the hassle by automatically renaming the image according to the rules.

Table of Contents

• Obsidian paste image rename

How to use

Basic usage

After installing the plugin, you can just paste an image to any document and the rename prompt will display:

By typing the new name and clicking "Rename" (or just press enter), the image will be renamed and the internal link will be replaced with the new name.

If you set "Image name pattern" to {{fileName}} (it's the default behavior after 1.2.0), "New name" will be generated as the name of the active file.

Set imageNameKey frontmatter

While adding a lot of images to one document, people possibly want the images to be named in the same format, that's where imageNameKey is useful.

First set a value for imageNameKey in frontmatter:

---
imageNameKey: my-blog
---

Then paste an image, you will notice that the "New name" has already been generated as "my-blog", which is exactly the value of imageNameKey:

You can change the pattern for new name generating by updating the "Image name pattern" value in settings.

For a detailed explanation and other features such as auto renaming, please refer to Settings.

Add prefix/suffix to duplicated names

The plugin will always try to add a prefix/suffix if there's a file of the same name.

Let's continue from the last section and paste the second image, the prompt will still show the new name as "my-blog", now if we just click "Rename", the file will be renamed as "my-blog-1.png", not "my-blog.png":

The -1 suffix is generated according to the default settings:

• Because "Duplicate number at start" is false, suffix is used rather than prefix
• "Duplicate number delimiter" - is put before the number 1

This feature is especially powerful if you enable "Auto rename" in settings, you can just add new images without thinking, and they will be renamed sequentially by the pattern and imageNameKey set.

Batch renaming process

New in 1.3.0

You can use the command "Batch rename embeded files in the current file" to rename images and other attachments (even notes) in the current file.

The image above demonstrates how to rename all the foo-1.png, foo-2.png… png files to bar-1-png, bar-2.png… with this feature.

You can also rename the images to the same name, and let the plugin handle the name deduplication for you. See a video demonstration here: https://i.imgur.com/6UICugX.mp4

Batch rename all images instantly

New in 1.5.0

The command "Batch rename all images instantly (in the current file)" will rename all the images in the current file according to "Image name pattern" in settings.

This is a shortcut for using Batch renaming process with certain arguments, makes everyday image renaming much easier.

Note that this command has no confirmation, please use it with caution!

Handle all attachments

New in 1.4.0

Paste image rename is not just a plugin for pasted images, it has the potential to handle all attachments that are added to the vault, no matter whether they are pasted or dragged.

To use this feature, you need to enable the "Handle all attachments" option in settings.

Additionally, you can configure the "Exclude extension pattern" to ignore files that match the given extension pattern.

FAQ

• Q: I pasted an image but the rename prompt did not show up.

Settings

• Image name pattern

- Available variables: - {{fileName}}: name of the active file, without ".md" extension. - {{imageNameKey}}: this variable is read from the markdown file's frontmatter, from the same key imageNameKey. - {{DATE:$FORMAT}}: use $FORMAT to format the current date, $FORMAT must be a Moment.js format string, e.g. {{DATE:YYYY-MM-DD}}.

- Examples

Here are some examples from pattern to image names (repeat in sequence), variables: fileName = "My note", imageNameKey = "foo": - {{fileName}}: My note, My note-1, My note-2 - {{imageNameKey}}: foo, foo-1, foo-2 - {{imageNameKey}}-{{DATE:YYYYMMDD}}: foo-20220408, foo-20220408-1, foo-20220408-2

• Duplicate number at start (or end)

• Duplicate number delimiter

• Auto rename

• Handle all attachments

• Exclude extension pattern

• Disable rename notice

Maintenance and verification

The current backlog, priorities, acceptance criteria, and verified progress are tracked in docs/maintenance-plan.md.

Run npm ci, npm test, and npm run build to execute the isolated regression suite and produce the plugin bundle in build/. Tests mock only the Obsidian runtime boundary; actual Obsidian testing should use a disposable vault and preserve a baseline copy.

Safety behavior in the maintenance candidate

• Enable Obsidian's Automatically update internal links before renaming so references

• Excluded folders takes one literal vault-relative folder per line. Automatic renaming

• Temporary/hidden files are ignored automatically. An invalid extension exclusion pauses

• In batch rename, click Preview after changing an input, then Rename all.
• Naming patterns must currently produce a filename, without folder separators. The plugin

Automatic insertion timing

Automatic handling starts after the workspace finishes loading and waits until the new attachment is linked or embedded in the Markdown note that was active when it was created. Old copied timestamps and slow imports are accepted. Files already referenced before creation (such as sync restores), unrelated unreferenced files, and insertions with no new parsed reference within 30 seconds are left unchanged. You can still use manual batch rename afterward. This protects insertion order but cannot identify every external plugin's intent; use folder exclusions for managed importer/sync folders.

Pattern examples and compatibility

Patterns describe the filename stem; the original attachment extension is appended. Do not append .png or another extension to the pattern itself.

• {{fileName}}-{{DATE:YYYY-MM-DD-HHmmss}} includes both date and time. DATE

• {{frontmatter:permalink}} reads the permalink frontmatter field. Its value must

• Multiple DATE/frontmatter variables are supported, including numeric zero and false.
• Markdown link destinations may contain %20 for spaces. This is normal URL encoding;

• Generated and manually entered stems are sanitized for forbidden filename/link

Original names and slugs

• Use original name in the rename prompt copies the attachment's current stem into

• {{attachmentName}} and {{originalAttachmentFileName}} mean the attachment stem

• {{fileNameSlug}} and {{FileNameSlug}} trim the note name, lowercase it, and replace

Existing patterns and automatic defaults are unchanged.

Optional naming controls

• Rename input selection can put the caret at the start, at the end (default), or

• Duplicate number minimum digits accepts 1–12 (default 1). New numbers can be

• {{nearestHeading}} and {{headerName}} use the nearest heading of any level before

• {{UUID}} creates a version-4 UUID once per file operation. Repeated UUID tokens in