S3 Image Sync

S3 Image Sync

中文说明

S3 Image Sync is a polished, modern, and mobile-friendly Obsidian plugin that scans local note images, uploads them to your S3-compatible cloud storage (Cloudflare R2, AWS S3, MinIO, etc.), and replaces local Markdown links with remote public URLs safely.

---

📢 Fork & Redesign Note

This repository is a highly refined and redesigned fork of the original perinchiang/obsidian-plugins-attachment-imagebed-manager.

All codebase refactoring, UI redesigns, and documentation rewrites in this fork were proudly assisted and generated by Gemini (the current AI model).

Key Improvements in this Fork:

1. Image-First Focus: Stripped away bloated non-image category logic (PDFs, docs, heavy media) to build a specialized, lightweight, and extremely reliable image uploader and sync engine.
2. PC & Mobile Responsive UI: Completely overhauled the upload modal's CSS grid to be fully fluid. Cards size adaptively (130px grid with 4:3 preview on desktop vs 100px square grid on mobile viewports) for a beautiful native look.
3. Premium Visual Enhancements:
   • Cards feature modern hover float transformations (translateY(-2px)) and elegant focus glow shadows.
   • Replaced the browser's default checkbox with a custom, overlay SVG checkmark (✓) displaying fluid scale/fade animations on select.
   • Replaced raw browser progress elements with a sleek, rounded HTML/CSS progress bar.
   • Redesigned the Delete Confirmation view into scrollable nested file-path cards.
4. Frictionless UX & Selection Performance: Rewrote the modal's state engine. Selection toggles are now handled directly through targeted DOM/CSS state adjustments (using cached Map lookups) instead of triggering a full page re-render. This completely preserves your scroll position and enables instantaneous (sub-1ms) selections!

---

Quick Start

1. Install the plugin and open Settings → S3 Image Sync
2. Under Step 1: Connect your cloud storage, choose a provider (Cloudflare R2 recommended)
3. Fill in your credentials and click Test connection
4. Open a note containing local images and click the cloud icon in the left ribbon — done!

Features

• S3-compatible storage: Cloudflare R2 (recommended), AWS S3, MinIO, or any S3-compatible provider.
• Cross-Platform Responsive: Fully functional on both Obsidian desktop and mobile, optimized with custom viewport CSS rules.
• Modern Gallery View: Browse local images easily with lazy-loading previews and smooth selection controls.
• Safe Replacement & Rollback: Atomic note writes with concurrent-edit detection; failed uploads are automatically rolled back.
• Upload Resilience: 3 retries with exponential backoff on transient network failures.
• Delete Policies: Ask before delete, immediate trash, or delayed delete (desktop only).
• Auto Scan: Periodic vault-wide scanning with quiet-period and image size filtering (desktop only).
• Dry-run Mode: Preview which images would be replaced without making changes.
• Code-block Aware: Images inside fenced code blocks and inline code are automatically ignored.

Installation

Manual Installation

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Copy them to <vault>/.obsidian/plugins/s3-image-sync/
3. Enable the plugin in Obsidian → Settings → Community Plugins.

Configuration

Step 1: Connect Your Cloud Storage

Choose your storage provider and fill in the credentials:

Click Test connection to verify your settings.

Upload Path Template Variables

The Upload path template allows you to dynamically customize the S3 object key (path) for uploaded files. The following variables are supported:

• {ext}: File extension (e.g. png, jpg).
• {hash}: 64-character full SHA-256 hash of the file.
• {hash-short}: 32-character short SHA-256 hash of the file.
• {hash2}: First 2 characters of the file hash (useful for folder partition/sharding).
• {filename}: Original file name (excluding extension).
• {yyyy}: Current year (4 digits, e.g. 2026).
• {MM}: Current month (2 digits, e.g. 06).
• {dd}: Current day (2 digits, e.g. 17).

Example: images/{yyyy}/{MM}/{dd}/{hash-short}.{ext} will upload a file to images/2026/06/17/a1b2c3d4e5f67890a1b2c3d4e5f67890.png.

Recommended Templates:

• By date: images/{yyyy}/{MM}/{dd}/{hash-short}.{ext}
• Keep original filename: attachments/{yyyy}/{MM}/{filename}-{hash-short}.{ext}

Step 2: General Settings

• Image folder: Only files under this folder are processed (default: 90-笔记系统/92-附件).
• Delete policy: What to do with local files after replacement:
  • Ask me each time (recommended) — shows an elegant confirmation dialog.
  • Delete immediately — trashes local files right away.
  • Delete after a delay — schedules deletion after configurable hours (desktop only).
• Auto-scan vault periodically: Automatically find and replace eligible images in the background (desktop only).
  • Scan interval: How often to scan (default: 30 minutes).
  • Skip recently modified files: Skip files modified within this time (default: 10 minutes).
  • Minimum file size: Ignore files smaller than this threshold in auto-scan.

License

MIT

---

中文说明

S3 Image Sync 是一款优雅、轻量且对移动端深度优化的 Obsidian 插件。它能自动扫描当前笔记中的本地图片，安全上传至 S3 兼容的云存储（如 Cloudflare R2、AWS S3、MinIO 等），并自动将笔记中的本地链接无缝替换为公共云端 URL。

---

📢 Fork 与全新重构声明

本项目是基于原版 perinchiang/obsidian-plugins-attachment-imagebed-manager 的重构与深度美化版本。

本项目分支中的所有代码重构、UI界面重新设计、交互逻辑改进及文档编写，均由 Gemini 提供协助并自主生成。

我们在原版基础上做出了如下核心改进：

1. 专注图片同步：砍掉了复杂沉重的通用附件分类（PDF、文档、大媒体）逻辑，代码体量大幅缩减，打造专门针对 Markdown 图片的轻量极致同步引擎。
2. PC & 移动端全兼容响应式 UI：全新重构了上传弹窗。卡片采用弹性网格适配（PC端 4:3 比例 130px 宽度网格，移动端自适应为 1:1 正方形 100px 网格），在手机等窄屏设备上视觉极为精致，告别局促。
3. 豪华视觉效果与交互微动效：
   • 卡片增加了现代化的物理悬浮动效（translateY(-2px)）和外发光精致投影。
   • 彻底移除了原生的浏览器复选框，改用高颜值的绝对定位 SVG 勾选框（✓），伴随平滑缩放与淡入淡出动画。
   • 进度条改用极简、圆润的 CSS 动效进度条，告别老旧的原生外观。
   • 优化了删除确认页，将要处理的路径包裹入独立滚动的精致子卡片容器中。
4. 零延迟状态机 & 保留滚动位置：重构了弹窗内的状态管理。现在勾选图片仅会通过缓存 Map 精准改变对应 DOM 的 CSS 样式类，完全不会触发全量重渲染，完美保留您的滚动条位置。即便有数百张图也支持瞬时（1毫秒内）无感响应。

---

快速上手

1. 安装插件，打开 设置 → S3 Image Sync
2. 在 第一步：连接云存储 中选择服务商（推荐 Cloudflare R2）
3. 填写凭据，点击 测试连接 验证
4. 打开一篇有本地图片的笔记，点击左侧栏的云图标 — 搞定！

核心功能

• S3 兼容存储: 支持 Cloudflare R2、AWS S3、MinIO 及任意 S3 兼容服务。
• 移动端兼容: 桌面端和移动端均可使用，移动端也拥有优雅、独立的响应式布局。
• 现代画廊视图: 通过懒加载预览和流畅的选择控件，轻松浏览本地图片。
• 安全替换 & 自动回退: 原子性文件写入，检测并发编辑；上传中途失败时自动删除已上传文件并回滚。
• 上传重试: 网络错误时自动进行 3 次指数退避重试。
• 删除策略: 每次询问 / 立即删除 / 延迟删除（仅桌面端）。
• 定期后台扫描: 定时全库静默扫描，支持文件修改保护静默期（仅桌面端）。
• 空运行模式: 无需实际更改即可预览哪些图片将被替换。
• 代码块感知: 智能忽略 fenced code block 和行内代码中的图片。

安装

手动安装

1. 从最新 Release 下载 main.js、manifest.json 和 styles.css。
2. 复制到 <vault>/.obsidian/plugins/s3-image-sync/ 目录下。
3. 在 Obsidian 设置 → 第三方插件 中启用 S3 Image Sync。

配置说明

第一步：连接您的云存储

选择您的存储服务商并填写凭据：

点击 测试连接 按钮以验证您的设置是否正确。

上传路径模板变量

通过上传路径模板来自定义图片在云存储中的保存路径（S3 Object Key）。支持以下动态变量：

• {ext}：文件扩展名/后缀 (如 png、jpg 等)。
• {hash}：64位完整 SHA-256 文件哈希值。
• {hash-short}：32位短 SHA-256 文件哈希值。
• {hash2}：SHA-256 文件哈希值的前2位字符（非常适合用于云存储的海量文件二级分流，避免单个文件夹下文件过多）。
• {filename}：原始文件名 (不含扩展名)。
• {yyyy}：4位当前年份 (如 2026)。
• {MM}：2位当前月份 (如 06)。
• {dd}：2位当前日期 (如 17)。

示例： images/{yyyy}/{MM}/{dd}/{hash-short}.{ext} 将保存为 images/2026/06/17/a1b2c3d4e5f67890a1b2c3d4e5f67890.png。

常用推荐模板：

• 按日期分类：images/{yyyy}/{MM}/{dd}/{hash-short}.{ext}
• 保留原始文件名：attachments/{yyyy}/{MM}/{filename}-{hash-short}.{ext}

第二步：常规设置

• 图片文件夹：仅处理该文件夹下的文件（默认：90-笔记系统/92-附件）。
• 删除策略：替换为远程链接后，原本地文件的处理方式：
  • 每次询问我（推荐）— 弹出一个精致的确认对话框。
  • 立即删除 — 立即将本地文件移入回收站。
  • 延迟删除 — 在配置的时间（小时）后安排删除（仅限桌面端）。
• 定期自动扫描全库：自动在后台查找并替换符合条件的图片（仅限桌面端）。
  • 扫描间隔：自动扫描的频率（默认：30分钟）。
  • 跳过最近修改的文件：跳过在此时间内修改过的文件（默认：10分钟）。
  • 自动扫描忽略的小图片：在自动扫描中忽略小于此阈值的文件。

许可证

MIT