Embed Link

Embed Link

English | 中文

Embed Link is an Obsidian plugin that turns pasted (and on desktop, dropped) URLs into web page cards, video previews, or Markdown 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.

The plugin handles a single URL on an empty line only. Any file paste or drop, 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):

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.

Commands

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

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:

Settings

Under Obsidian Settings → Embed Link:

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
├── cache/                           # parser metadata cache
├── media/                           # download images + aspect ratio
└── ui/                              # URL suggest menus, settings tab
tests/                               # Vitest
.github/workflows/release.yml        # tag → draft release
docs/superpowers/specs/              # design notes