README file from
GithubAttachment Link Rules
Choose whether dropped attachments become normal links or embeds based on their file extension.
A PDF can land as [[report.pdf]] while an image still lands as ![[diagram.png]]. Native attachment storage, filenames, destinations, and the user's Wiki link or Markdown link preference remain intact.
Highlights
- PDF and office files default to normal links without
!. - Images, audio, and video default to embeds with
!. - Configure extension lists in the settings screen.
- Unlisted extensions retain the syntax generated by the app.
- Works with external file drops and native vault-file drops because storage stays native.
- Uses public APIs only and does not modify existing notes or attachments.
Default rules
Normal links: pdf doc docx xls xlsx ppt pptx zip 7z rar
Embeds: png jpg jpeg gif webp svg avif bmp mp3 wav m4a ogg flac mp4 webm mov
If an extension appears in both lists, the normal-link rule wins. Extensions are case-insensitive and may be separated by spaces or commas.
How it works
The app performs its normal drop operation first, including choosing the attachment folder, resolving duplicate filenames, and generating Wiki or Markdown link syntax. The plugin then inspects only the newly inserted text and adds or removes the leading ! according to the configured extension rules.
This avoids private editor internals and avoids reimplementing attachment storage.
External drops are observed for up to 60 seconds so slower copies can finish. Only inserted links matching the dropped filenames or native numbered duplicates are considered. Internal vault/text drops get a single deferred check. Existing links are protected when other edits happen at the same time; if identical links make attribution ambiguous, their syntax is retained. Changing files, unloading the plugin or completing the expected insertions ends observation.
Installation
Install from the Community directory, or copy the three release files for a manual test-vault installation. No package manager or external service is required at runtime.
Community plugins
Install the published plugin:
- Open Settings → Community plugins → Browse.
- Search for Attachment Link Rules.
- Install and enable it.
Manual installation
Copy these release assets into .obsidian/plugins/attachment-link-rules/ inside a test vault first:
main.jsmanifest.jsonstyles.css
Restart the app or reload community plugins, then enable Attachment Link Rules.
Usage
Drag an attachment into an open Markdown note as usual. The app stores the file and inserts its normal link. The plugin then applies the configured rule to the newly inserted syntax:
- dropping
report.pdfproduces[[report.pdf]]with the default settings; - dropping
diagram.pngproduces![[diagram.png]]; - dropping an unlisted extension keeps the native result.
The same rule engine supports Wiki links and Markdown links. Existing links elsewhere in the note are left untouched.
Configuration
Open Settings → Attachment Link Rules:
On Obsidian 1.13 and later, these options are also indexed by the built-in settings search. Older supported versions continue to use the same settings through the legacy-compatible interface.
- Link extensions removes the leading
!. - Embed extensions ensures the leading
!is present. - Unlisted extensions keep native behavior.
- Restore defaults resets the two lists.
Development and verification
npm install
npm run lint
npm run typecheck
npm test
npm run build
npm run community:check
npm run sync:test-vault -- --target /absolute/path/to/obsidian-test-vault/.obsidian/plugins/attachment-link-rules
npm run smoke:test-vault -- --vault /absolute/path/to/obsidian-test-vault --report /absolute/local/path/report.json
npm run check runs the complete local source and Community preflight. GitHub Actions are intentionally not required; the repository's deterministic gate is documented in Local validation. Current Community scorecard findings and their disposition are recorded in Community scorecard notes.
The test-vault sync requires an explicit obsidian-test-vault plugin folder and refuses the main Syncthing vault. The runtime smoke uses the Obsidian CLI and an explicitly marked test vault; it preserves settings and the active note. See local validation.
Privacy and security
The plugin performs no network requests, collects no telemetry, and does not read attachment contents. Live network access exists only in the development-time Community uniqueness checker.
See SECURITY.md for reporting guidance.
Release
The release tag must equal manifest.json.version. Each release contains exactly:
main.jsmanifest.jsonstyles.css
See community submission notes and CHANGELOG.md.
License
MIT © 2026 Viggo Meesters.
Cooperating with Mail Drop (0.2.0)
With Mail Drop 0.10.0 or later, choose Use attachment rules in Mail Drop. Mail Drop saves and names external files; Attachment Link Rules chooses link or embed syntax. Internal vault drags keep native storage and naming. Email entries remain owned by Mail Drop. No second attachment copy is created.
For images only as embeds, set Embed extensions to png jpg jpeg gif webp svg avif bmp, and Unlisted extensions to Use links. Keep document types in Link extensions. Audio, video, unknown extensions and extensionless files then use normal links. Existing settings and the public default rules remain unchanged unless you choose this configuration.
Importers can use the optional synchronous document event attachment-link-rules:format-v1 with mutable detail {version:1, fileName, link, handled:false}. The plugin applies its current rules to the supplied native Wiki or Markdown link and sets handled:true. No listener means the caller keeps native syntax. Dispatch on the target note's owner document. The provider also registers for detached windows and removes its listeners on unload.
Before consuming a drop, a cooperating importer dispatches attachment-link-rules:managed-drop-v1 on that document with {version:1,event:originalDragEvent}. The normal drop observer skips that event, including when it ran first. This prevents a second rewrite of a whole mail block and avoids depending on the observer's short retry window for slow file I/O. These events do not install, store or rename attachments.
Runtime evidence identifies the source and bundle hashes for this release.
Obsidian 1.15.1 assessment: checked source, local results and remaining host validation.