MdAssetSync

English | 简体中文

MdAssetSync imports external Markdown files into Obsidian while preserving the original disk location used to resolve local assets. A link such as ./assets/image.png is resolved from the external Markdown file's original folder, then the image or optional attachment is copied into the location configured in Obsidian.

This plugin requires Obsidian 1.13.0 or later on desktop and uses Node.js filesystem access.

Features

• Select one or more external .md files, or select a folder to recursively import its .md and .markdown files. Hidden folders and node_modules are skipped.
• Start an import from the MdAssetSync ribbon button on the left sidebar or from the command palette.
• Resolve relative image paths from the original Markdown folder, including ./ and ../.
• Resolve absolute local paths on Windows and macOS.
• Resolve Markdown inline images, reference-style images, Obsidian embeds, HTML <img> sources, and local file:// URIs.
• Preview Markdown counts, image counts, and detected issues before confirming an import.
• Optionally download http/https images into the Vault attachment location for offline notes.
• Optionally copy local PDF, office, audio, video, archive, or custom attachment types referenced from the Markdown.
• Choose between disabled, PDF and office documents, all local attachments, or a custom extension list.
• Follow Obsidian's native Files and links → Default location for new attachments setting.
• Choose a separate destination folder for imported Markdown; the default is the vault root.
• Rewrite images as standard Markdown links: ![alt](relative/path.png).
• Preserve non-image attachment link, wiki-link, and wiki-embed syntax while rewriting only the local path.
• Reuse an existing attachment when both the file name and MD5 match.
• Handle same-name files with different content using append-MD5, overwrite, or skip strategies.
• Keep network images, base64 images, and remote attachment links unchanged.
• Show import progress and classify imported files, reused assets, missing assets, conflicts, and errors in an import-result dialog.

Installation

GitHub release

1. Download main.js and manifest.json from the 1.1.2 GitHub release.
2. Create or open <Vault>/.obsidian/plugins/md-asset-sync/.
3. Copy main.js and manifest.json into that folder.
4. Restart Obsidian or reload third-party plugins.
5. Enable MdAssetSync in Settings → Community plugins.

Build from source

Node.js 18 or newer is required.

npm install
npm run build

Copy main.js and manifest.json to the plugin folder in the vault.

Usage

1. Configure Settings → Files and links → Default location for new attachments in Obsidian.
2. In Settings → Community plugins → MdAssetSync, choose whether non-image attachments should be synchronized.
3. Click the MdAssetSync image icon on the left ribbon, or run MdAssetSync: Import external Markdown and sync assets from the command palette.
4. Choose Markdown files to select one or more files, or Folder to recursively import Markdown from a folder.
5. Search for and choose where the Markdown files should be written in the vault. The picker prioritizes the current note's folder, the last-used destination, and the vault root.
6. Review the preview summary and detected issues, then choose Import or cancel.
7. Wait for the import to finish and review the result notification and import-result dialog.

The Markdown destination and the attachment destination are independent. Changing the Markdown target folder does not change where assets are stored.

Privacy and file access

MdAssetSync needs local filesystem access to import files from outside the Vault. It reads only the external Markdown files you explicitly select and the local assets referenced by those files. Unless you enable remote image downloads, this plugin does not upload content, make network requests, or collect telemetry.

Imported Markdown, images, and attachments are written to the Vault through Obsidian's Vault API. MdAssetSync lists Vault folders only to populate the searchable Markdown destination picker and reads the active note's folder to offer it as a shortcut; it does not use direct filesystem access to inspect Vault note contents.

Attachment behavior

Existing attachments are checked by MD5 when the file names match. Matching content is reused. Different content follows the configured same-name strategy.

Non-image attachments

Use Sync non-image attachments in the plugin settings to choose a mode:

Custom extensions can be separated with commas or spaces. Leading dots are optional, and values are normalized case-insensitively. For example:

pdf, docx, xlsx, epub, .drawio

Supported non-image syntax includes:

• [guide](./files/guide.pdf)
• [report][doc] with [doc]: ../files/report.xlsx
• [[manual.pdf|Open manual]]
• ![[recording.mp3]]
• <a href="./files/data.csv">Open data</a>

Images are always rewritten to ![](). Non-image attachments retain their original link or embed syntax so Obsidian can keep opening or previewing the correct file type.

Plugin language

Open Settings → Community plugins → MdAssetSync and choose Plugin language:

• English
• 简体中文

The default is English. The command, settings, dialogs, progress messages, notifications, and import-result dialog use the selected language.

Supported asset paths

Supported:

• ![image](./assets/photo.png)
• ![image](../shared/photo.png)
• ![image](<my images/photo one.png>)
• Reference images such as ![image][photo] with [photo]: ./photo.png
• Obsidian embeds such as ![[./assets/photo.png]] and ![[photo.png|alt text]]
• HTML images such as <img src="./photo.png" alt="image">
• Local URIs such as file:///C:/Images/photo.png
• Windows absolute paths such as C:/Images/photo.png
• macOS absolute paths
• Percent-encoded local paths containing spaces
• [guide](./files/guide.pdf) for optional non-image attachments
• [[manual.pdf|Open manual]] and ![[recording.mp3]] for optional non-image attachments

Not processed:

• HTTP and HTTPS URLs
• data: base64 images
• Other network or application URI schemes
• Image files in the non-image attachment flow; they are handled only by image syntax

Limitations

• Desktop only.
• HTML image sizing and styling attributes are discarded when converted to standard Markdown.
• Images inside inline code and fenced code blocks are preserved without processing.
• Markdown, Canvas, and Base files are not copied as attachments.
• All-local mode can copy large audio, video, or archive files; choose a narrower mode when this is not desired.
• External Markdown files must remain readable during the import.
• If an imported Markdown file already exists in the destination folder, MdAssetSync adds an -import-N suffix rather than overwriting it.

Release notes

See CHANGELOG.md.

License

This project is licensed under the GNU General Public License v3.0 only.

MdAssetSync 1.0.0 was distributed under the MIT License. GPL-3.0-only applies to version 1.0.1 and later.