Image Insert Hotkey · 图片快捷插入

English | 中文

---

中文

在 Obsidian 中通过快捷键快速插入图片。按下快捷键弹出系统文件选择器，选择图片后自动复制到库中，并在光标位置插入 Markdown 图片语法。

功能

核心功能

1. 快捷键插入图片 — 默认 Ctrl+I（macOS）或 Alt+I，可在 Obsidian 快捷键设置中自定义
2. 文件选择窗口 — 按下快捷键后弹出系统文件选择器，默认筛选常见图片格式
3. 智能插入 — 选择图片后自动在光标位置换行并插入 ![注释](路径) 格式的 Markdown。若图片在库外则自动复制到库中

可选功能

1. 图片注释模板 — 默认使用文件名（不带后缀）作为 alt text。支持动态变量：

   • ${filename} — 文件名（不带后缀）
   • ${format} — 文件格式（如 png、jpg）
   • ${fullname} — 完整文件名（带后缀）
   • 使用 \${ 转义 ${ 字符
   • 配置项末尾有 ? 图标，鼠标悬浮查看变量说明

2. 路径类型 — 可选择相对路径（相对于当前笔记）或绝对路径（相对于库根目录）

3. 额外文件格式 — 除默认的 jpg、jpeg、png、gif、bmp、webp、svg 外，可自行添加扩展名（逗号分隔）

4. 恢复默认配置 — 一键恢复所有设置为出厂默认值

5. 中英文支持 — 插件命令名称、设置项、提示信息均支持英文和中文切换

文件结构

.
├── src/
│   ├── main.ts           # 插件入口：命令注册、文件选择、图片复制与插入逻辑
│   ├── settings.ts       # 设置接口、默认值、设置标签页 UI
│   └── i18n.ts           # 所有用户界面字符串（英文、中文）
├── styles.css            # 设置页样式
├── esbuild.config.mjs    # 构建配置
├── manifest.json         # Obsidian 插件清单
├── versions.json         # 最低 Obsidian 版本兼容映射
├── package.json
└── tsconfig.json

架构

插件类 ImageInsertHotkeyPlugin（src/main.ts）继承自 Obsidian 的 Plugin，在 onload() 中注册 insert-image 命令并绑定默认快捷键。触发时创建隐藏的 <input type="file"> 元素并设置 accept 属性为允许的图片格式，从而打开系统文件选择器。

选择文件后，通过 Electron 的 webUtils.getPathForFile() API 获取文件绝对路径，与库根路径对比判断文件是否已在库中。外部文件通过 app.vault.createBinary() 复制到库中（目标文件夹可在设置中配置，未配置则使用当前笔记所在目录）。文件名重复时自动追加 -1、-2 等后缀。

insertMarkdown() 方法处理两种光标场景：若光标在空行则直接插入；否则移动到行尾后换行插入。生成的 Markdown 格式为 ![alt](path)，其中 alt 文本由用户配置的模板生成，路径支持相对/绝对两种模式。

设置模块（src/settings.ts）中 loadSettings() 将存储数据与 DEFAULTS 浅层合并，设置对象的 version 字段用于未来数据迁移。设置标签页 ImageInserterSettingTab 渲染所有配置项，修改语言设置后会立即重新渲染整个标签页以切换界面语言。getAllowedExtensions() 将内置格式列表与用户额外配置的格式合并。

所有用户界面字符串集中在 src/i18n.ts，包含 en（英文）和 zh（中文）两套，通过 getStrings(lang) 根据语言设置返回对应字符串集。

关键流程： 快捷键 → 文件选择器 → 获取文件路径 → 判断库内/库外 → 复制到库（如需要）→ 生成 alt 文本（模板变量替换 + 转义处理）→ 计算路径（相对/绝对）→ 插入 Markdown

构建

npm install
npm run dev        # 开发模式（监听文件变化，内联 sourcemap）
npm run build      # 生产构建（类型检查 + 压缩，无 sourcemap）

使用 esbuild 将 src/main.ts 打包为 main.js（CommonJS，目标 ES2020）。obsidian、electron 标记为外部依赖（由 Obsidian 运行时提供）。

安装（开发）

# 符号链接方式
ln -s "$(pwd)" "/path/to/your-vault/.obsidian/plugins/image-insert-hotkey"

# 或手动复制构建产物
cp main.js manifest.json styles.css "/path/to/your-vault/.obsidian/plugins/image-insert-hotkey/"

然后在 Obsidian 中：设置 → 第三方插件 → 启用 "Image insert hotkey"。

环境要求

• Node.js 18+
• Obsidian ≥ 1.5.0

---

English

Insert images into Obsidian notes via a configurable hotkey. Opens a system file picker, copies external images into the vault, and inserts Markdown image syntax at the cursor.

Features

Core

1. Hotkey image insertion — Default Ctrl+I (macOS) or Alt+I (other platforms), customizable in Obsidian's hotkey settings
2. System file picker — Opens the native file picker filtered to common image formats
3. Smart insertion — Automatically inserts ![alt](path) Markdown at the cursor. Files outside the vault are copied in first

Options

1. Alt text template — Defaults to the file name (without extension). Supports variables:

   • ${filename} — File name without extension
   • ${format} — File format (e.g. png, jpg)
   • ${fullname} — Full file name with extension
   • Escape ${ with \${
   • A ? help icon at the end of the setting shows available variables on hover

2. Path type — Choose relative path (to current note) or absolute path (from vault root)

3. Extra file extensions — Beyond the built-in defaults (jpg, jpeg, png, gif, bmp, webp, svg), add your own comma-separated extensions

4. Reset to defaults — One-click restore of all settings to factory defaults

5. i18n — All UI strings support English and Chinese

File structure

.
├── src/
│   ├── main.ts           # Plugin entry: command registration, file picker, copy & insert logic
│   ├── settings.ts       # Settings interface, defaults, settings tab UI
│   └── i18n.ts           # All user-facing strings (English, Chinese)
├── styles.css            # Settings tab styles
├── esbuild.config.mjs    # Build configuration
├── manifest.json         # Obsidian plugin manifest
├── versions.json         # Minimum Obsidian version compatibility map
├── package.json
└── tsconfig.json

Architecture

The plugin class ImageInsertHotkeyPlugin (src/main.ts) extends Obsidian's Plugin. It registers the insert-image command in onload() with platform-specific default hotkeys. When triggered, it creates a hidden <input type="file"> element with accept set to allowed image formats, opening the system file picker.

On file selection, the absolute filesystem path is obtained via Electron's webUtils.getPathForFile() API. If the file is already inside the vault it is linked directly; otherwise it is copied in via app.vault.createBinary(). The destination folder is configurable via the "asset folder" setting (falls back to the current note's directory). Duplicate file names get -1, -2 suffixes automatically.

insertMarkdown() handles two cursor scenarios: blank line (insert directly) or populated line (move to end of line, then insert with newline). The inserted Markdown is ![alt](path), where alt text is generated from the user's template and the path can be relative or absolute.

The settings module (src/settings.ts) shallow-merges stored data with DEFAULTS on load. The version field enables future data migration. The settings tab ImageInserterSettingTab renders all configuration items; changing the language re-renders the entire tab. getAllowedExtensions() merges built-in extensions with user extras.

All UI strings live in src/i18n.ts with en and zh sets, returned by getStrings(lang).

Key flow: Hotkey → file picker → get file path → check if in vault → copy to vault (if needed) → generate alt text (template substitution + escape handling) → compute path (relative/absolute) → insert Markdown

Build

npm install
npm run dev        # Dev mode with watch and inline sourcemaps
npm run build      # Production build (type-check + minify, no sourcemaps)

esbuild bundles src/main.ts to main.js (CommonJS, target ES2020). obsidian and electron are externals provided by the Obsidian runtime.

Install (development)

# Symlink approach
ln -s "$(pwd)" "/path/to/your-vault/.obsidian/plugins/image-insert-hotkey"

# Or copy build artifacts
cp main.js manifest.json styles.css "/path/to/your-vault/.obsidian/plugins/image-insert-hotkey/"

Then in Obsidian: Settings → Community plugins → Enable "Image insert hotkey".

Prerequisites

• Node.js 18+
• Obsidian ≥ 1.5.0