FleurPDF

FleurPDF

Smart PDF Reading and Annotation Plugin for Obsidian

中文文档

---

✨ Features

Why Choose FleurPDF Over Other PDF Plugins?

1. Chinese-Friendly Design

   • Optimized text selection for Chinese characters
   • Proper handling of CJK text in PDFs
   • Smart text boundary detection

2. WYSIWYG Highlights with AI Annotations

   • What you see is what you get - highlights appear exactly where you select
   • AI can automatically generate insightful annotations for highlighted text
   • Visual feedback is immediate and accurate

3. AI-Powered Assistance

   • AI Explain: Get detailed explanations of selected text
   • AI Translation: Instant translation between Chinese and English
   • AI Annotations: Auto-generate thoughtful notes for your highlights
   • Supports any OpenAI-compatible API (DeepSeek, OpenAI, etc.)

4. One-Click Note Export

   • Export all annotations and highlights to a new Obsidian note
   • Preserves page numbers and organization
   • Perfect for creating reading summaries

5. Sticky Notes on PDF Pages (opt-in, v1.8.0)

   • Pin draggable, resizable, collapsible sticky notes anywhere on a PDF page
   • One click collects all notes into a single Markdown note; re-exporting overwrites the same note
   • Background color and font size are user-configurable
   • Fully local: content lives in a sidecar file under the plugin's data/ folder (hashed file name, no paths or note titles in it), and the exported note is an ordinary vault note

Complete Feature List

• 📝 Highlighting: Yellow, blue, green, and customizable colors
• 📏 Underlining: Solid, dashed, dotted, or wavy styles
• 💬 Comments: Add personal notes to any text selection
• 🤖 AI Features:
  • Explain complex passages
  • Translate text
  • Generate intelligent annotations
  • Interactive Q&A about selected content
• 📊 Sidebar: View and manage all annotations in one place
• 📤 Export: One-click export to Obsidian notes
• 🎨 Customizable: Adjust colors, styles, and AI settings

📦 Installation

Manual Installation

1. Download main.js, manifest.json, and styles.css from the latest release
2. Create a folder <vault>/.obsidian/plugins/fleur-pdf/
3. Place the three files into the folder
4. Reload Obsidian
5. Enable "FleurPDF" in Settings → Community plugins

Build from Source

git clone https://github.com/gibsonchan-5/fleur-pdf.git
cd fleur-pdf
npm install
npm run build

Then copy main.js, manifest.json, and styles.css to your vault's plugin folder.

🔧 Configuration

AI Setup

1. Open Obsidian Settings → FleurPDF
2. Choose your AI provider (DeepSeek, OpenAI, or Custom)
3. Enter your API Key (stored locally only)
4. Configure the Base URL if using a custom endpoint
5. Click "Test Connection" to verify

Security Note: Your API Key is stored locally only — by default in Obsidian's system keychain (SecretStorage), not in data.json, so it never syncs with your vault (you can opt into plain data.json storage in settings). Keys are sent solely to the AI endpoint you configure. Apart from your configured AI endpoint and the built-in dictionary sources (Youdao Dictionary / dictionaryapi.dev, which receive only the word being looked up), the plugin sends nothing to any server and has no telemetry.

Annotation Settings

• Default Highlight Color: Choose your preferred highlight color
• Default Underline Style: Select solid, dashed, dotted, or wavy
• Note Export Folder: Specify where exported notes should be saved
• Sidebar Position: Choose left or right sidebar

Cross-Device Sync (optional, off by default)

Text annotations (highlights / underlines / comments / AI results) and stylus ink can each be synced between your devices. When enabled, the plugin keeps a visible copy per annotated PDF inside your vault — FleurPDF/data/annotations/ for text annotations, FleurPDF/data/ink/ for ink — which travels with whatever sync you already use (Remotely Save, iCloud, …). Files are merged read-merge-write when a PDF opens, after each save, and when a copy change is detected; edits resolve last-writer-wins by modification time, and deletions are recorded as tombstones so a stale copy on another device cannot resurrect deleted annotations. Enable the toggles on every device. The copies only ever live in your own vault — the plugin sends nothing anywhere and has no telemetry.

Mobile Handwriting (Ink) Annotations

Stylus ink is rendered on the plugin's own overlay canvases and persisted in a sidecar file under FleurPDF/data/ — it is never baked into your PDF, and it is only ever written to your own vault.

• Ink display precision: rasterising and compositing the ink layer costs scale with the screen DPR, so on some tablets writing feels laggy even though the pen itself reports normally (the ink trails the stylus). Settings → Mobile handwriting → Ink display precision caps the ink layer at a lower resolution (Balanced ≈ half the pixels, Smooth ≈ 40%), which usually makes it responsive again. This changes on-screen resolution only — stroke data, coordinates, hit testing and exports are unaffected, and Native restores full sharpness at any time.
• Ruler (pen bar → ruler icon, Apple Notes style): tap to place an opaque, frosted-white ruler with centimetre graduations (default length 10 cm at the current zoom) — the body itself is a drawing surface (WYSIWYG: draw straight on the ruler and the line lands just outside the working edge), the small pill grip in the middle moves it, the round knob rotates, and either end changes its length (the other end stays anchored); use the level button that appears beside the ruler icon to snap it back to horizontal. Like Apple Notes, the ruler lies below the line you draw and its working edge is the top edge (switchable to the opposite side via the Ruler side setting): a stroke drawn across the ruler straightens along that working edge, and the ink is nudged fully to the ruler's outer side with a hairline gap, so the body never covers it; the body is opaque except for a hairline slit at the working edge, so a stroke passing the ruler shows as a thin line there. Works with pen and highlighter; strokes away from the ruler are unaffected. Toggle the icon again to hide it. The ruler is session-only (not a setting) and the resulting straight strokes are ordinary ink — undo, eraser, sync and export all behave as usual.
• Shapes (pen bar → shapes icon): drag to place a rectangle, ellipse or straight line (pick the kind in the shape flyout). Rectangles and ellipses can take a translucent highlighter-style fill from the palette (fluorescent yellow by default; "no fill" for outline only); the outline follows the shape tool's own color/width (both editable from the usual color and size buttons while the shape tool is active). Shapes are ordinary strokes: a tap won't create one (drag required), and after drawing you can tap a shape to select it (dashed box) and drag to move it. The eraser deletes a whole shape when it touches its outline, the lasso selects and moves them as a unit, and undo/sync work as usual.
• Stroke-break / lag diagnostics (command palette → 「手写断触诊断」, mobile only): a passive, command-gated recorder that samples pointer and touch timing plus frame gaps while you write, and saves them to FleurPDF/ink-debug.json and FleurPDF/ink-debug.md inside your vault. These are local files; the plugin uploads nothing and has no telemetry. What a capture contains: event timestamps, the on-screen position of each sampled pointer/touch (i.e. roughly where on the page you were writing), pressure/size fields, the CSS class of the touched element, and small counters (how many canvases/pages/strokes are live, current pen width and opacity, frame-gap durations). What it does not contain: PDF text, note or file contents, file names, vault paths, account details, or API keys. Both files are safe to delete at any time, and the recorder only runs between the two invocations of that command.

📖 Usage Guide

Basic Annotations

1. Select Text: Click and drag to select text in the PDF
2. Right-Click Menu: Choose from the following options:
   • Highlight: Add a colored background to the text
   • Underline: Add an underline with various styles
   • Comment: Add a personal annotation
   • Ask AI: Get AI explanation of the selected text
   • AI Translation: Translate the text instantly

AI Features

AI Explain

Select text → Right-click → "Ask AI" → Get detailed explanation with:

• Key concept definitions
• Background context
• Deep analysis

AI Translation

Select text → Right-click → "AI Translation" → Instant bidirectional translation (Chinese ↔ English)

AI Annotations

Highlight text → Click the 💡 icon in sidebar → AI generates intelligent annotations automatically

Managing Annotations

The sidebar shows all your annotations:

• 📌 View all highlights and comments
• ✏️ Edit annotations inline
• 🗑️ Delete unwanted items
• 💾 Export everything to a note

Exporting Notes

Click "Export Notes" in the sidebar to create a new Obsidian note with:

• All highlights with page numbers
• All comments and annotations
• Organized by page for easy reference

Screenshot & OCR (network behaviour declaration)

The ink toolbar includes a camera tool: drag a rectangle over the PDF to capture a high-resolution region (re-rendered via pdf.js, independent of screen zoom). From the result panel you can copy the image, copy recognized text, ask the AI, or save to vault.

• Text from digital PDFs is extracted from the PDF text layer — offline and exact.
• Local OCR (tesseract.js, Apache-2.0, see THIRD-PARTY-NOTICES.md) runs entirely on your machine and is strictly opt-in (off by default). Only after you enable it in Settings are the engine files (worker script + WASM kernel, ~9.4 MB, version-pinned from jsDelivr) downloaded once on first use and cached in the plugin folder — fully offline afterwards. The language data file (plain data) is likewise downloaded once from the configured source and cached.
• Vision model (optional) sends the screenshot to the endpoint you configure in Settings → Screenshot & OCR; nothing is sent without your explicit action.

🛠️ Development

Project Structure

fleur-pdf/
├── src/
│   ├── main.ts           # Plugin entry point
│   ├── patcher.ts        # PDF view interception
│   ├── sidebar.ts        # Annotation sidebar
│   ├── ai-chat-modal.ts  # AI dialog panel
│   ├── ai-service.ts     # AI API service
│   ├── settings.ts       # Settings panel
│   └── store.ts          # Data persistence
├── manifest.json
├── package.json
└── styles.css

Build Commands

npm run build      # Build for production
npm run dev        # Development mode with watch

🐛 Troubleshooting

"Text not found" Error

This can happen when:

• The PDF text layer is not fully loaded
• You're selecting across multiple pages

Solution: Wait a moment after selecting text, or try selecting again.

AI Not Responding

Check:

• API Key is correctly configured
• Base URL is accessible
• Internet connection is stable

Use the "Test Connection" button to verify your setup.

📝 License

MIT License

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

---

中文文档

✨ 功能特色

为什么选择 FleurPDF？

1. 中文友好

   • 针对中文字符优化的文本选择
   • 正确处理 PDF 中的中日韩文字
   • 智能文本边界检测

2. 所见即所得的高亮 + AI 批注

   • 高亮效果所见即所得，精确显示在选中的位置
   • AI 可以自动为高亮文本生成有见地的批注
   • 视觉反馈即时且准确

3. AI 智能助手

   • AI 解释：获取选中文本的详细解释
   • AI 翻译：中英文即时互译
   • AI 批注：为高亮内容自动生成智能批注
   • 支持任何 OpenAI 兼容 API（DeepSeek、OpenAI 等）

4. 一键导出笔记

   • 将所有批注和高亮导出为新的 Obsidian 笔记
   • 保留页码和结构组织
   • 非常适合创建阅读摘要

5. PDF 页面便签（可选开启，v1.8.0）

   • 便签可拖拽 pin 在页面任意位置，自由缩放、可折叠成小脚注
   • 一键将全部便签整理导出为一篇 Markdown 笔记，再次导出自动覆盖同一篇
   • 底色与字号均可在设置里自定义
   • 完全本地：便签内容存在插件 data/ 目录下的 sidecar 文件（文件名为哈希，不含路径信息）， 导出的笔记就是普通 vault 笔记，插件不上传任何内容

完整功能列表

• 📝 高亮标注：黄色、蓝色、绿色等多种可自定义颜色
• 📏 下划线：实线、虚线、点线、波浪线等多种样式
• 💬 批注：为任何选中文本添加个人注释
• 🤖 AI 功能：
  • 解释复杂段落
  • 翻译文本
  • 生成智能批注
  • 针对选中内容进行互动问答
• 📊 侧边栏：在一个地方查看和管理所有批注
• 📤 导出：一键导出为 Obsidian 笔记
• 🎨 可定制：调整颜色、样式和 AI 设置

📦 安装方法

手动安装

1. 从 latest release 下载 main.js、manifest.json、styles.css
2. 创建文件夹 <vault>/.obsidian/plugins/fleur-pdf/
3. 将三个文件放入该文件夹
4. 重新加载 Obsidian
5. 在设置 → 第三方插件中启用"FleurPDF"

从源码构建

git clone https://github.com/gibsonchan-5/fleur-pdf.git
cd fleur-pdf
npm install
npm run build

然后将 main.js、manifest.json 和 styles.css 复制到你的仓库的插件文件夹。

🔧 配置说明

AI 设置

1. 打开 Obsidian 设置 → FleurPDF
2. 选择 AI 提供商（DeepSeek、OpenAI 或自定义）
3. 输入 API Key（默认保存在系统钥匙串，可选改为随 vault 同步）
4. 如果使用自定义端点，配置 Base URL
5. 点击"测试连接"验证设置

安全说明：主 AI 与视觉模型两把 API Key 默认存入 Obsidian 系统钥匙串（SecretStorage），不写入 data.json，因此不会随 vault 同步上传；只有在设置里显式把「密钥保存位置」改为 data.json 时，密钥才会以明文随 vault 同步。除调用你所配置的 AI 端点与内置词典源（有道词典 / dictionaryapi.dev，仅发送所查询单词本身）外，插件不向任何服务器发送笔记内容，也没有任何遥测或上报。

批注设置

• 默认高亮颜色：选择您偏好的高亮颜色
• 默认下划线样式：选择实线、虚线、点线或波浪线
• 笔记导出文件夹：指定导出笔记的保存位置
• 侧边栏位置：选择左侧或右侧边栏

批注跨设备同步（可选，默认关）

文本批注（高亮 / 划线 / 批注 / AI 结果）与手写笔迹都可在多台设备间同步。开启后，插件会在 vault 内 为每本有批注的 PDF 保留一份可见副本——文本批注在 FleurPDF/data/annotations/，手写笔迹在 FleurPDF/data/ink/——随你现有的同步方式（Remotely Save、iCloud 等）跨设备流动。合并时机：打开 PDF、每次批注落盘、检测到副本变更；编辑冲突按修改时刻后写者胜，删除记录为持久化墓碑，其他设备上的 旧副本不会让已删批注「复活」。需要在每台设备上分别开启开关。 副本只存在于你自己的 vault 中， 插件不向任何服务器发送内容，也没有遥测。

移动端手写批注

手写笔迹画在插件自建的覆盖层 canvas 上，笔迹数据存在 vault 内的 FleurPDF/data/ sidecar 文件里， 不会写进你的 PDF 原件，也只写在你自己的 vault 中。

• 笔迹显示精度：笔迹层的栅格化与合成开销随屏幕 DPR 增长。平板上如果出现「笔的采样一切正常、 字却跟不上笔尖」的卡顿，可在设置 → 移动端手写批注里把这一项改为「均衡」（像素量约减半）或 「流畅」（约减六成），通常会立刻跟手。它只改显示分辨率：笔迹数据、坐标、命中测试、导出一律 不受影响，随时改回「原始」即可恢复最锐利的笔迹。
• 直尺（笔盒 → 直尺图标，Apple Notes 式）：点按在页面上放一把带厘米刻度的磨砂白直尺（尺身 不透明，底下的旧笔迹不会大片透出来；只有工作边留一条 6px 透明缝，经过尺沿的墨在缝里露出 一线，划没划线看得见），默认长 10 厘米（按当前缩放换算，尺面铺满 0–10 刻度）—— 尺身即书写面，所见即所得：直接在尺上画，墨沿工作边外侧落线；拖中央胶囊把手移动、 拖右端圆钮旋转、拖左右两端调长短（另一端锚定），其余尺面不感应拖拽、只管落墨， 直尺图标旁会出现「恢复水平」按钮一键扳平；设置里可用「直尺朝向」选择尺子在笔画 下方（默认）还是上方。书写逻辑与 Apple Notes 对齐：尺子躺在要画的线的对面，工作边朝向笔画——划线经过尺子就沿工作边被拉直， 且整条墨落在尺子外侧，只留一道小缝贴着尺沿，尺身不遮墨。钢笔 / 荧光笔都可用，离尺 较远的笔迹不受影响。再点一次图标即收起。直尺是会话内的（不进设置），画出的直线就是普通笔迹 —— 撤销、橡皮、同步、导出一律按普通笔迹处理。
• 形状（笔盒 → 形状图标）：拖拽画出矩形、圆形或直线（形状在弹层里三选一）。矩形和圆形 可从色板选半透明荧光笔式填充（默认荧光黄，也可选「无填充」只描边）；描边颜色与粗细用形状 工具自己的参数（形状模式激活时，笔盒的颜色 / 粗细按钮改的就是它）。形状就是普通笔迹： 点按不成形（必须拖拽）；画完后点一下形状即可选中（出现虚线框），再拖动可整体平移。 橡皮碰到轮廓整条删、套索整体圈选平移，撤销 / 同步照常。
• 断触 / 卡顿诊断（命令面板 → 「手写断触诊断」，仅移动端）：一个被命令开关的被动记录器， 在你书写期间采样指针/触摸时序与帧间隔，写入 vault 内的 FleurPDF/ink-debug.json 与 FleurPDF/ink-debug.md。这两个文件只落在本机，插件不上传任何内容，也没有遥测。 记录内容：事件时间戳、每次采样的屏幕位置（大致等于你在页面上书写的地方）、压感/接触面尺寸、 被按到的元素 class，以及若干计数（当前挂着几页覆盖层、多少笔迹、笔的粗细与透明度、掉帧毫秒数）。 记录内容不包括：PDF 文字、笔记正文、文件名、vault 路径、账号信息、API Key。 两个文件随时可以整篇删除，且记录器只在该命令运行期间工作。

📖 使用指南

基础批注

1. 选中文本：在 PDF 中点击并拖动选择文本
2. 右键菜单：从以下选项中选择：
   • 高亮：为文本添加彩色背景
   • 划线：添加各种样式的下划线
   • 批注：添加个人注释
   • 询问 AI：获取选中内容的 AI 解释
   • AI 翻译：即时翻译文本

AI 功能

AI 解释

选中文本 → 右键 → "询问 AI" → 获取详细解释，包括：

• 关键概念定义
• 背景信息
• 深度分析

AI 翻译

选中文本 → 右键 → "AI 翻译" → 即时双向翻译（中文 ↔ 英文）

AI 批注

高亮文本 → 点击侧边栏的 💡 图标 → AI 自动生成智能批注

管理批注

侧边栏显示您的所有批注：

• 📌 查看所有高亮和批注
• ✏️ 内联编辑批注
• 🗑️ 删除不需要的项目
• 💾 全部导出为笔记

导出笔记

点击侧边栏中的"导出笔记"创建新的 Obsidian 笔记，包含：

• 所有高亮及页码
• 所有批注和注释
• 按页码组织，便于查阅

🐛 故障排除

"未找到选中文本"错误

可能发生在：

• PDF 文本层未完全加载
• 跨页选择文本

解决方法：选中文本后稍等片刻，或重新选择。

AI 无响应

检查：

• API Key 配置正确
• Base URL 可访问
• 网络连接稳定

使用"测试连接"按钮验证您的设置。

📝 许可证

MIT 许可证

🤝 贡献

欢迎贡献！请随时提交 issue 或 pull request。