Embed Link

English | 中文

Embed Link is an Obsidian plugin that turns pasted (and on desktop, dropped) URLs and non-media files into web page cards, video previews, Markdown links, or filename wiki links.

• Display name: Embed Link
• Plugin ID: embed-link
• Minimum Obsidian version: 1.7.2
• License: GPL-3.0
• UI language: Follows the Obsidian app language. Codes that start with zh use Simplified Chinese; every other language uses English.

Install

This plugin is not in the community plugin directory yet. Install a GitHub release or a local build:

1. Download main.js, manifest.json, and styles.css from a release, or copy them from ./embed-link/ after ./build.sh.
2. Put those three files in your vault at .obsidian/plugins/embed-link/.
3. In Obsidian, turn off Restricted mode, then enable Embed Link under Settings → Community plugins.

To build from source, see Development.

Usage

Paste and drop run in Markdown editor views. Desktop intercepts both paste and drop. Mobile intercepts paste only (no file drop).

The plugin handles a single URL on an empty line, or a single non-media file. Image, audio, and video files, multiple files, mixed clipboard content, and URLs on a non-empty line are left to Obsidian.

Paste a URL

On an empty line, paste (or drop, on desktop) one http:// or https:// URL.

With Auto embed on paste off, a menu appears (labels follow the app language):

English	中文	Result
Web page card	网页卡片	An embed code block rendered as a card
Video preview	视频预览	 (title from parse, or hostname)
Markdown link	Markdown 链接	[title](url)
Plain text	纯文本	The raw URL

With Auto embed on paste on, a web page card is inserted immediately (no menu). Video preview stays menu-only.

Pasting a URL on a line that already has text does not intercept; Obsidian keeps the raw URL.

Paste a file

Paste (or drop, on desktop) a single non-media file such as a PDF or .docx. Image, audio, and video files are not intercepted.

With auto embed off, a menu appears:

English	中文	Result
Filename link	文件名链接	Copy into Obsidian’s default attachment folder; insert [[path|filename.ext]]
Default link	默认链接	Obsidian’s normal attachment link for that file

With auto embed on, a filename link is created immediately.

Copied files always use Obsidian’s default attachment folder, not the plugin image folder. Name conflicts get a numeric suffix (for example report 1.pdf).

Commands

Command palette names (prefixed with Embed Link:). Bind them under Settings → Hotkeys.

Command	What it does
Create web page card	Resolve a URL, then insert a web page card (Local parser, MicroLink fallback)
Create web page card (local parser)	Same, Local parser only (no fallback)
Create web page card (MicroLink parser)	Same, MicroLink only (no fallback)

URL resolve order: selected text if it is an http(s) URL → whitespace token under the cursor → clipboard text. On parse failure, a notice is shown.

Card actions

Hover a web page card:

Position	Control	Behavior
Top-right	Edit this block (Obsidian built-in)	Edit the embed code block source
Bottom-right (top → bottom)	Refresh	Re-parse the URL and update the block
	Copy	Copy the embed source to the clipboard
	Delete	Confirm, then remove the block and any local preview image file

Settings

Under Obsidian Settings → Embed Link:

Setting	Default	Description
Auto embed on paste	off	On an empty line, insert a web page card or filename wiki link immediately instead of showing a menu
Download images to vault	off	Save card preview images in the vault instead of hotlinking
Image folder path	empty	Folder for downloaded card images. Empty uses Obsidian’s default attachment path
Keep image aspect ratio	on	Preserve the original aspect ratio of card preview images
Use parser cache	on	Cache parsed URL metadata for repeat embeds and refreshes
Show favicon	on	Show the site favicon on cards when available
MicroLink API key	empty	Optional key for the MicroLink parser. Empty uses the free tier

Parser order is fixed: Local first, then MicroLink. There is no setting to swap engines. Cache is stored with plugin data; when cache is off, it is neither read nor written.

Development

For people who change the code, install locally, or publish a release. Plugin users can skip this chapter.

Build from source

Requires Node.js 18 or later.

git clone https://github.com/exbob/obsidian-embed-link.git
cd obsidian-embed-link
npm install
./build.sh

Then copy embed-link/ into the vault at .obsidian/plugins/embed-link/. That directory contains main.js, manifest.json, and styles.css. Enable Embed Link under Settings → Community plugins.

./build.sh clean only deletes main.js, main.js.map (if present), and ./embed-link/. It does not build. ./build.sh and bash build.sh are the same.

Windows: PowerShell cannot run ./build.sh directly. Use Git Bash or WSL.

• Git Bash (C:\Program Files\Git\usr\bin\bash.exe): use the same Node 18+ as PowerShell (typically /c/Program Files/nodejs). This repo’s build.sh invokes node esbuild.config.mjs production so it does not depend on the Windows npm shim (the Unix npm file under C:\Program Files\nodejs often fails in Git Bash with No such file or directory). npm run build still works in PowerShell.
• WSL (often C:\Windows\System32\bash.exe): may have a separate, older Node on PATH (for example v12). Prepending /mnt/c/Program Files/nodejs does not replace WSL’s node (Windows ships node.exe, not node). Install Node 18+ inside WSL, or run npm run build in PowerShell / ./build.sh in Git Bash instead.

npm run build from PowerShell writes main.js at the repo root. ./build.sh runs the same production build and stages main.js, manifest.json, and styles.css into ./embed-link/.

Develop and check

npm run dev       # watch source and rebuild
npm test          # unit / integration tests
npx tsc --noEmit  # typecheck
npm run build     # production build (writes main.js at the repo root only)
./build.sh        # production build and write embed-link/

Command IDs registered in code look like create-web-page-card. Obsidian prefixes the plugin id (for example embed-link:create-web-page-card). Use whatever the command palette actually shows.

Publish a new version

Bump version in manifest.json (and versions.json / package.json as needed), push the code, and create a Git tag that matches the version exactly, with no v prefix (for example 0.1.0, not v0.1.0). Pushing that tag runs GitHub Actions: test, typecheck, production build, then a draft GitHub Release with main.js, manifest.json, and styles.css. See the Obsidian plugin publishing docs.

Project layout

build.sh                             # production build into embed-link/; clean removes artifacts only
esbuild.config.mjs                   # bundler config
manifest.json                        # plugin manifest
styles.css                           # web page card styles
embed-link/                          # install directory to copy into a vault
src/
├── main.ts                          # entry, commands, lifecycle
├── types.ts                         # shared types
├── settings.ts                      # settings model and normalization
├── url-target.ts                    # command URL from selection / cursor / clipboard
├── i18n/                            # zh/en copy and t()
├── paste/                           # classify, empty-line, paste/drop router
├── parsers/                         # Local (primary) + MicroLink (fallback)
├── embed/                           # serialize, parse, render, hover actions
├── files/                           # copy non-media files + wiki links
├── cache/                           # parser metadata cache
├── media/                           # download images + aspect ratio
└── ui/                              # URL/file suggest menus, settings tab
tests/                               # Vitest
.github/workflows/release.yml        # tag → draft release
docs/superpowers/specs/              # design notes