FleurAnnotation

An Obsidian plugin that brings intelligent reading and annotation features to Markdown files. Highlight text, add underlines, attach comments, and leverage AI to explain, translate, and annotate your content — all directly within Obsidian.

Features

• 📝 Highlight: Right-click to highlight selected text with customizable colors
• 📏 Underline: Multiple underline styles (solid, dashed, dotted, wavy)
• 💬 Annotations: Add personal comments to selected text
• 🤖 AI Assistance:
  • Smart Explanation: AI explains selected text content
  • Smart Translation: One-click translation
  • AI Annotations: Automatically generate valuable annotations
• 📋 Sidebar Management: View all annotations in one place with quick navigation
• 📤 Export: Export all annotations as a separate Markdown note
• 🌍 Multi-language Support: Chinese-friendly interface and interactions

Why FleurAnnotation?

Compared to PDF annotation plugins, FleurAnnotation focuses specifically on Markdown files:

1. Native Markdown Integration: Highlights and annotations display directly in Markdown files without view switching
2. AI-Powered Reading: Not just an annotation tool, but an intelligent reading assistant
3. One-Click Export: Easily organize annotations into separate note files
4. Lightweight: Minimal configuration, works out of the box

Installation

Via Community Plugins (Recommended)

1. Open Obsidian Settings → Community Plugins
2. Search for "FleurAnnotation"
3. Click Install, then Enable

Via BRAT

1. Install BRAT plugin in Obsidian
2. Add this repository: https://github.com/gibsonchan-5/fleur-annotation
3. Enable FleurAnnotation plugin

Manual Installation

1. Download the latest version from Releases
2. Extract to .obsidian/plugins/fleur-annotation/ in your vault
3. Enable FleurAnnotation plugin in Obsidian settings

Usage

Basic Operations

Highlight Text

• Select text in a Markdown file
• Right-click and choose "Highlight"
• Customize the highlight color in settings

Add Underline

• Select text and right-click
• Choose "Underline"
• Customize underline style and color

Add Annotation

• Select text and right-click
• Choose "Annotation"
• Enter your annotation content

AI Features

AI Explanation: Select text → Right-click → "AI Explanation"

AI Translation: Select text → Right-click → "AI Translation"

AI Annotation: Click the "AI Annotation" button in the sidebar annotation card

Dictionary Lookup

• Select a word or short phrase (≤ 4 words) → right-click → "查词 + 详解": with FleurDict installed the FleurDict lookup window opens (dictionary definitions, pronunciation, AI detail, vocabulary book); without it, a built-in popup queries Youdao and the Free Dictionary API directly.
• Select a sentence or paragraph → "AI Translation" as before.
• New words can go to the FleurDict wordbook (full sync pipeline) or to a local wordbook file kept inside the plugin's data folder.

Sidebar Management

• Click the FleurAnnotation icon in the left toolbar to open the sidebar
• View all annotations, click to jump to the original text
• Delete or edit annotations as needed
• Export all annotations via the "Export Notes" button

Configuration

In Obsidian Settings → FleurAnnotation:

• AI Configuration: Set AI provider (DeepSeek, OpenAI, Zhipu AI, Moonshot, Alibaba Qwen / DashScope, etc.), API Key, Base URL, and model. Switching provider auto-fills its Base URL and recommended model. API key is stored locally only.
• Annotation Settings: Customize default highlight color and underline style
• Export Settings: Set default export folder
• Sidebar: Choose sidebar position (left/right)

Privacy & Network Use

FleurAnnotation is offline by default. Highlights, underlines, comments, the sidebar and note export touch nothing but your own vault — annotation data is stored as plain JSON files inside your vault (.obsidian/plugins/fleur-annotation/data/, or a folder you choose for cross-device sync).

The plugin makes network requests only when you trigger them:

• AI requests you initiate. "AI Explanation", "AI Translation" and "AI Annotation" POST the text you have selected, plus the prompt, to the OpenAI-compatible chat/completions endpoint you configure under Settings → Base URL — for example api.deepseek.com, api.openai.com, open.bigmodel.cn, api.moonshot.cn or dashscope.aliyuncs.com (Alibaba Qwen). Nothing is sent unless you invoke an AI action, and only the selected passage goes out, never the whole document.
• Dictionary lookups you initiate. Selecting a word/phrase and choosing "查词 + 详解" queries public dictionary services: Youdao (dict.youdao.com, JSON API) and the Free Dictionary API (api.dictionaryapi.dev). Only the queried word goes out — never the surrounding text or context. If FleurDict is installed and enabled, lookups are handed to the FleurDict plugin instead, whose own network behavior is documented in its repository.
• Optional web search. When "Web search" is on and the endpoint supports it, the request asks the provider to retrieve public web pages server-side so it can answer time-sensitive questions: Alibaba DashScope (Qwen, and the third-party models hosted there such as DeepSeek) gets enable_search, Zhipu gets a web_search tool entry. Providers with no supported field — DeepSeek's own endpoint, OpenAI, Moonshot — receive nothing extra. Either way this adds a per-call search fee to that provider's bill.

There is no telemetry, no analytics, no usage tracking, no ads, no remote code or assets, and no self-update mechanism. The plugin never contacts the author's servers, and it does not read or write anything outside your vault.

Your API key stays on your device. By default it is kept in the system keychain through Obsidian's SecretStorage, which means it is not written to data.json and does not travel with your vault. If you switch the storage location to data.json, it is stored in clear text inside the vault and will sync with it — that tradeoff is your explicit choice, and the settings page warns you about it. The key is only ever transmitted as a Bearer token to the Base URL you configured.

Because that Base URL decides where the key goes, it is validated before every request: the address must parse, must not embed credentials, and must use HTTPS — plain HTTP is accepted only for loopback hosts (localhost, 127.0.0.1, ::1), so a local proxy such as Ollama or LM Studio keeps working while a cleartext downgrade to a remote host is refused. Any valid HTTPS host is still accepted, since pointing at your own gateway is the point of an OpenAI-compatible setting; the check is a transport-integrity guard, not a host allowlist.

Keys are therefore also bound to the host they were entered for: each host gets its own keychain entry, and the list of bound hosts is kept in data.json (host names are not secret — they are already in your Base URL). If a synced data.json arrives whose Base URL points at a host you never bound, the plugin will not hand an existing key to it; it clears the key and asks you to re-enter it once. Switching back to a previously bound host restores its key automatically. On first launch after upgrading, your existing single key is adopted into the entry for whichever host is configured at that moment, so no re-entry is needed unless you subsequently change host.

One local detail worth knowing: exported annotation notes carry a source: field in their frontmatter with the vault-relative path of the annotated note. That file is written into your own vault and is never uploaded anywhere. The optional local wordbook lives in FleurAnnotation/data/ inside your vault (or syncs through FleurDict if you enable that), and never leaves your device.

Development

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

npm test bundles every test/*.test.ts with esbuild (obsidian → test/obsidian-mock.ts) and runs it under Node + jsdom: marker-placement and unwrap rules, cross-device store merge, and the desktop zero-impact smoke checks.

Tech Stack

• TypeScript
• Obsidian API
• OpenAI-compatible AI Integration

License

MIT License

中文说明

FleurAnnotation 是一个 Obsidian 插件，为 Markdown 文件提供智能阅读和批注功能。

主要特性

• 📝 高亮标注：右键选中文本添加高亮，支持自定义颜色
• 📏 下划线标注：多种样式（直线、虚线、点线、波浪线）
• 💬 批注功能：为选中文本添加个人批注
• 🤖 AI 辅助：
  • 智能解释：AI 解释选中的文本内容
  • 智能翻译：一键翻译选中文本
  • AI 批注：自动生成有价值的批注
• 📖 词典查词：选中单词/短语（≤4 词）一键查词——装有 FleurDict 时走 FleurDict 查词窗（词典释义、发音、AI 详解、生词本），未装时用内置词典弹窗（有道 + Free Dictionary API）；选中句子则走 AI 翻译
• 📋 侧边栏管理：集中查看所有批注，支持快速跳转
• 📤 导出功能：一键导出所有批注为独立的 Markdown 笔记

安装方法

社区插件安装（推荐）

1. 打开 Obsidian 设置 → 社区插件
2. 搜索 "FleurAnnotation"
3. 点击安装并启用

手动安装

1. 从 Releases 下载最新版本
2. 解压到 vault 的 .obsidian/plugins/fleur-annotation/ 目录
3. 在 Obsidian 设置中启用 FleurAnnotation 插件

使用方法

基本操作

• 选中文本 → 右键 → 选择"高亮"/"划线"/"批注"
• 在设置中自定义颜色和样式

AI 功能

• AI 解释：选中文本 → 右键 → "AI 解释"
• AI 翻译：选中文本 → 右键 → "AI 翻译"
• AI 批注：点击侧边栏批注卡片的"AI 批注"按钮

词典查词

• 选中单词/短语 → 右键 → "查词 + 详解"（装有 FleurDict 时走 FleurDict 查词窗，未装时走内置词典弹窗）
• 选中句子/段落 → 右键 → "AI 翻译"
• 生词可加入 FleurDict 生词本（全管线同步）或本插件数据目录内的本地生词本

侧边栏管理

• 点击左侧工具栏的 FleurAnnotation 图标打开侧边栏
• 查看所有批注，点击跳转到原文
• 支持删除和编辑批注
• 通过"导出笔记"按钮导出所有批注

配置说明

在 Obsidian 设置 → FleurAnnotation 中：

• AI 配置：选择 AI 服务商（DeepSeek、OpenAI、智谱 AI、Moonshot、阿里千问/百炼 等）、API Key、Base URL 和模型。切换服务商会自动填入对应的 Base URL 与推荐模型。API Key 仅保存在本地。
• 标注设置：自定义默认高亮颜色和下划线样式
• 导出设置：设置默认导出文件夹
• 侧边栏：选择侧边栏位置（左侧/右侧）

隐私与网络使用说明

插件默认完全离线。高亮、划线、批注、侧边栏与导出笔记只读写你自己的 vault——批注数据以普通 JSON 文件形式保存在 vault 内（默认 .obsidian/plugins/fleur-annotation/data/，也可在设置里改到用于跨设备同步的目录）。

插件只在你手动触发时发出网络请求：

• 你主动发起的 AI 请求。「AI 解释」「AI 翻译」和侧边栏的「AI 批注」会把你选中的那段文字加上提示词，POST 到你在设置里填的 Base URL 对应的 OpenAI 兼容 chat/completions 接口，例如 api.deepseek.com、api.openai.com、open.bigmodel.cn、api.moonshot.cn、dashscope.aliyuncs.com（阿里千问）。不点 AI 就不会有任何外发，且只发送选中文本，不会上传整篇文档。
• **你主动发起的词典查词。**选中单词/短语后点「查词 + 详解」会请求公开词典服务：有道（dict.youdao.com JSON API）与 Free Dictionary API（api.dictionaryapi.dev）。外发的只有被查询的单词本身，不会带上前后文或任何笔记内容。如果安装并启用了 FleurDict，查词会转交给 FleurDict 插件完成，其自身的网络行为以其仓库文档为准。
• 可选的联网搜索。 开启「联网搜索」且当前端点支持时，请求会要求服务商在服务端检索公开网页以回答时政等时效性问题：阿里百炼（千问，以及挂在百炼上的第三方模型，如 DeepSeek）带 enable_search，智谱带 web_search 工具项。不支持该字段的端点（DeepSeek 官方、OpenAI、Moonshot）不会多发任何字段。无论走哪家，都会在你的对应账单里额外产生每次调用的搜索费用。

没有遥测、没有数据统计、没有广告、没有远程代码或资源加载、也没有自我更新机制。插件不会连接作者的任何服务器，读写范围不超出你的 vault。

API Key 始终留在你自己的设备上。默认通过 Obsidian 的 SecretStorage 存进系统钥匙串，因此不写入 data.json，也不会随 vault 同步；如果你把「密钥保存位置」改成 data.json，密钥将以明文存在 vault 内并随其同步——这是你主动选择的取舍，设置页也会给出提示。密钥只会作为 Bearer 令牌发往你填写的那个 Base URL。

由于 Base URL 决定了密钥的去向，插件在每次发请求前都会校验它：地址必须能解析、不得内嵌账号密码、且必须使用 HTTPS；明文 http 只对本机回环地址（localhost、127.0.0.1、::1）放行，这样 Ollama / LM Studio 这类本地代理照常可用，而把流量降级到远端明文地址会被拒绝。任何合法的 https 主机仍然放行——「能指向自建网关」正是 OpenAI 兼容设置的意义所在。所以这一层是传输完整性防护，不是主机白名单。

因此密钥还会与录入它的主机绑定：每个主机在钥匙串里各占一条，已绑定过哪些主机记在 data.json 里（主机名不是机密，它本来就在你的 Base URL 中）。如果同步过来的 data.json 指向一个你从未绑定过的主机，插件不会把已有密钥交给它——而是清空并要求你重新输入一次；切回曾经绑定的主机时，对应密钥会自动恢复。升级到本版后的首次启动，会把原有那把不分主机的密钥收养到「当时所配置的那个主机」名下，因此除非你之后更换主机，否则不需要重新输入。

另外一点本地细节：导出的批注笔记，其 frontmatter 里会有 source: 字段，记录被批注笔记在 vault 内的相对路径。这个文件只写进你自己的 vault，不会上传到任何地方。可选的本地生词本保存在 vault 内的 FleurAnnotation/data/ 目录（或在设置里交给 FleurDict 同步），同样不会离开你的设备。