Custom Attachment Location

Paste a screenshot into Obsidian and it lands in one shared folder as Pasted image 20250101120000. A year later that folder holds a thousand files whose names say nothing about which note they belong to.

This plugin decides where each attachment is stored and what it is called, from a pattern of tokens such as {{noteFileName}} and {{date:{momentJsFormat:'YYYYMMDD'}}}. Keeping that true as notes are renamed, moved and deleted is the job of its companion, Advanced Rename and Delete Handler, which this plugin requires and installs for you in one click.

More screenshots

Demo vault

The documentation is a demo vault. Every feature has a note that explains what it does and why you would want it, and walks you through it with a file you supply.

Start reading here — it is plain markdown, so it works on GitHub with nothing installed.

A copy of the vault ships with every release. You can access it via any of the following:

1. Running the Custom Attachment Location: Open demo vault command.
2. Downloading obsidian-custom-attachment-location-demo-vault.zip from the Releases. It unzips into a single obsidian-custom-attachment-location-demo-vault-<version> folder.
3. Browsing its source in demo-vault/ in this repository.

What it does

• Choose the folder each new attachment goes into, from a pattern: beside the note, a folder per note, a folder per year. A fresh install follows Obsidian's own setting until you pick a pattern. 01 Attachment folder location
• Choose the file name, so an attachment says where it came from; by default only pasted images are renamed. Paired signatures and subtitles follow their base through copies and stay protected while the group is used. 02 Attachment file naming
• Patterns and tokens, the vocabulary both are written in, including prompting at paste time, reading frontmatter and your own JavaScript tokens. 03 Tokens and patterns · 04 Custom tokens · 09 Token reference
• Catch attachments other plugins create, such as an image pasted into an Excalidraw drawing, and move and rename them too. 06 Settings
• Rename a note's attachments where they are, by a pattern of their own, with the links following: one command, no folder moves. 02 Attachment file naming
• Collect attachments a note already has into the folder your settings say, for a note, a folder or the whole vault, optionally merging identical files. 05 Collect attachments
• Delete unused attachments, after a confirmation, optionally including folders whose note is gone. 08 Delete unused attachments
• Undo a bulk command with git: in a vault kept in git, each collect, delete, move or prune run can be recorded as its own commit, so one revert undoes it. Off by default, desktop only. 06 Settings
• Keep it true over time: attachments follow their note on rename, move and delete, through Advanced Rename and Delete Handler. 06 Settings
• Link display text: show an attachment's name or its original arrival name after renaming, using a token template. 07 Link display text
• Jump between a note and its attachments, both ways. 10 Navigation
• Remember original file names, locally by default, with optional cross-device synchronization in a configurable @Plugin sync data (DO NOT REMOVE) folder, which the plugin explains with a README.md and lists in Obsidian's Excluded files. Original name storage covers setup, hidden folders and safe relocation.

Tokens

Moved to 09 Token reference. For what a pattern is, start at 03 Tokens and patterns.

Custom tokens

Moved to 04 Custom tokens.

Markdown URL format

Moved to 06 Settings, under markdownUrlFormat.

See also

My other Obsidian resources

Last searched for similar plugins on 2026-10-26.

For plugin developers

This plugin publishes an API another plugin can call: attachment folder and path reads, a collect action, its full path resolver and a collect-settings handover. It is declared in api.d.ts, with its contract in api-contract.ts. Plugin API explains how to reach it, with or without @mnaoumov/obsidian-lib, and why vault.getConfig('attachmentFolderPath') is not a seam to read.

Installation

The plugin is available in the official Community Plugins repository.

Beta versions

To install the latest beta release of this plugin (regardless if it is available in the official Community Plugins repository or not), follow these steps:

1. Ensure you have the BRAT plugin installed and enabled.
2. Click Install via BRAT.
3. An Obsidian pop-up window should appear. In the window, click the Add plugin button once and wait a few seconds for the plugin to install.

Debugging

By default, debug messages for this plugin (id: obsidian-custom-attachment-location) are hidden.

If you need to enable them refer to the documentation.

Attributions

In Oct 2021, the plugin was created by RainCat1998.

From July 2024, the plugin is maintained by Michael Naumov.

From December 2025, the project repository is hosted at mnaoumov/obsidian-custom-attachment-location.

The original author's repository is preserved as an archive of issues/PRs/discussions/releases at RainCat1998/obsidian-custom-attachment-location.

Changelog

All notable changes to this project will be documented in the CHANGELOG.

Contributing

Contributions are welcome — see CONTRIBUTING to get set up.

Support

Filing an issue (for AI agents and humans)

Open issues through the issue forms, not as blank issues.

To report a bug from inside Obsidian, run the Custom Attachment Location: Report a bug command. It opens the bug form with the plugin version, the Obsidian version and your operating system already filled in.

Filing from the CLI or the API (gh issue create --body, or an AI agent filing for you) skips the form, and gh issue create --template cannot load an issue form. In that case, open the matching form in .github/ISSUE_TEMPLATE/, copy every field as a ### <label> heading in the form's order, and fill in each one. Always state the plugin version, the Obsidian version and your operating system.

License

Copyright (c) RainCat1998, Michael Naumov.