What it does
- Shows every attachment in one searchable list: images, PDFs, audio, video, documents, archives and any other file that isn't a note.
- Shows where each one is used. Notes, properties, Canvas boards and bases all count, and every reference shows its exact text and location.
- Finds broken attachment links, such as an image renamed outside Obsidian or a PDF moved to another folder.
- Repairs them one at a time. It suggests the file you probably meant, shows you the exact change, and only writes after you confirm. Every repair can be undone.
Safe by design
| |
|---|
| 🔍 Scanning never changes files | Attachment Lens only reads your vault until you choose Apply repair. |
| ✋ Nothing happens automatically | No replacement is ever chosen for you. You pick it, review it, then apply it. |
| 🎯 One reference per repair | A repair changes the characters of one link in one file. Everything else stays as it is, down to spacing and line endings. |
| 🛡️ Checked before and after writing | If the note changed since you looked at the preview, nothing is written. After writing, the file is read back to confirm the result. |
| ↩️ Undo that survives a restart | Undo last repair puts the original text back, also after you close Obsidian. It refuses if you've edited the file since, so newer work is never overwritten. |
| 📎 Attachments are never touched | No renaming, moving or deleting of attachment files, ever. |
| 🔒 Private | No network requests, no accounts, no telemetry. |
Install
From Obsidian
The quickest way: open Attachment Lens in the Community directory and choose Add to Obsidian. Obsidian opens the plugin's page, where you choose Install, then Enable.
Or from inside Obsidian:
- Open Settings → Community plugins and turn off Restricted mode if it's on.
- Choose Browse, search for Attachment Lens, and choose Install.
- Choose Enable.
Attachment Lens needs Obsidian 1.14 or newer on Windows, macOS or Linux. A mobile version is planned.
By hand
- From the latest release, download
main.js, manifest.json and styles.css.
- In your vault, create the folder
.obsidian/plugins/attachment-lens/ (if you renamed Obsidian's configuration folder, use that instead of .obsidian).
- Put the three files in it, then in Settings → Community plugins reload the list and turn on Attachment Lens.
Quick start
1. Open the panel and scan
Click the paperclip in the left ribbon, or run Attachment Lens: Open from the command palette (Ctrl/Cmd+P). The panel opens as a tab. Choose Scan vault.
The scan reads your notes, properties, Canvas boards and bases. It runs in small steps, so you can keep working, and Cancel scan stops it at any time. After the first scan, the results follow your changes automatically.
2. Browse your attachments
| Part | What it's for |
|---|
| Search | Type part of a file name or folder. Ctrl/Cmd+F jumps here. |
| Filters | All attachments, Broken references, No references detected and Uncertain references, each with a live count. |
| All types and Sort | Show only images, PDFs, audio, video, documents or archives, and sort by name, folder, size, date or number of references. |
| The list | Every attachment with its folder, size and number of references. Click a row or use the arrow keys. |
| Details | A preview for images, the path (with a copy button), type, size and date, and every place the file is used. Open source takes you to the exact line. |
3. Fix a broken link
Choose Broken references. Each row is a file that's linked somewhere but doesn't exist. Select one, then choose Repair… on the reference you want to fix.
Pick the file you meant. Suggestions are ranked by how similar their names and folders are, and each one says why it's there, for example Same name, .jpg instead of .jpeg. If the right file isn't listed, search all attachments underneath. When you've chosen, select Review change.
The review dialog shows exactly what will change, highlighted in context. Nothing is written yet. Choose Apply repair to write it, or Back to choose another file.
The banner confirms the repair was checked after writing. Changed your mind? Choose Undo repair.
Guide
| Filter | Shows |
|---|
| All attachments | Every attachment in the vault. |
| Broken references | Links to attachments that don't exist, grouped by the missing file. The count is the number of broken links. |
| No references detected | Attachments that nothing links to, as far as Attachment Lens can see. This doesn't prove a file is unused, because some places (such as HTML tags or plugin code) aren't scanned. See What gets scanned. |
| Uncertain references | Plain text that looks like a file name but isn't a link, such as a banner: dune.jpg property that a theme reads. |
When a link is broken, Attachment Lens compares the missing name with every attachment in the vault. It looks at:
- the same name in another folder (the most common cause: the file was moved),
- the same name with a different extension, such as
.jpeg and .jpg,
- names that match ignoring case, spaces, dashes and copy numbers (
photo 1.png, photo-copy.png),
- similar names, such as
results-table-v2 and results-table-v3,
- folders shared with the original link, and files near the note,
- whether the file has no other references, which often means it's the one that was moved.
Each suggestion shows the reasons that apply. A file of a different type is marked in orange. Similar names are a hint, not proof, so check the preview before you choose.
以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗
