Attachment Link Rules

by Viggo Meesters
5
4
3
2
1
Score: 51/100

Description

Choose link or embed syntax for dropped attachments by file extension.

Reviews

No reviews yet.

Stats

0
stars
686
downloads
0
forks
91
days
0
days
3
days
7
total PRs
0
open PRs
0
closed PRs
7
merged PRs
5
total issues
0
open issues
5
closed issues
28
commits

Latest Version

4 days ago

Changelog

Maintenance 0.2.3: checked on Obsidian 1.15.1 desktop (macOS arm64), with unchanged runtime code. Adds the checked-version documentation and reproducible official lint tooling while retaining existing repository guards.

Exact reviewed source: 7ee0c720f629576274860608b40dfb0de0653fa9. The QA document records actual fixture oracles, exercised actions, additional smoke coverage and limits. Clean local validation and independent source/runtime/visual review passed; the official exact-SHA source preview completed.

Mobile, minimum-version, native resize and real authentication/keychain behavior were not verified. Final public asset readback, official release review and fresh Community installation are checked separately.

README file from

Github

Attachment Link Rules hero

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.

Settings preview

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:

  1. Open Settings → Community plugins → Browse.
  2. Search for Attachment Link Rules.
  3. Install and enable it.

Manual installation

Copy these release assets into .obsidian/plugins/attachment-link-rules/ inside a test vault first:

  • main.js
  • manifest.json
  • styles.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.pdf produces [[report.pdf]] with the default settings;
  • dropping diagram.png produces ![[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.js
  • manifest.json
  • styles.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.