# MiniMark **Repository Path**: minims/minimark ## Basic Information - **Project Name**: MiniMark - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2026-07-30 - **Last Updated**: 2026-09-29 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
MiniMark Logo # MiniMark **一款轻量、隐私优先的浏览器书签同步扩展** 将本地书签安全地备份到 GitHub Gist 或 Gitee，在多设备间自由同步。 [![Manifest Version](https://img.shields.io/badge/Manifest-V3-22c55e?logo=googlechrome&logoColor=white)](https://developer.chrome.com/docs/extensions/mv3/intro/) [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Platform](https://img.shields.io/badge/Platform-Chromium%20%7C%20Edge%20%7C%20Brave-22c55e)]() [![Language](https://img.shields.io/badge/Language-JavaScript-f7df1e?logo=javascript&logoColor=black)]() [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-22c55e.svg)]()
--- > 如果你觉得 MiniMark 有用，欢迎到 GitHub 点个 Star 支持一下！ ## 目录 - [项目简介](#项目简介) - [核心特性](#核心特性) - [界面预览](#界面预览) - [安装方式](#安装方式) - [快速开始](#快速开始) - [同步策略](#同步策略) - [隐私与安全](#隐私与安全) - [项目结构](#项目结构) - [技术实现](#技术实现) - [开发指南](#开发指南) - [常见问题](#常见问题) - [贡献指南](#贡献指南) - [开源协议](#开源协议) ## 项目简介 MiniMark 是一款基于 Manifest V3 的浏览器书签同步扩展。它把书签数据序列化为 JSON，托管到你自己的 GitHub Gist 或 Gitee 代码片段中，借助这两大平台的免费存储实现跨设备、跨浏览器的书签同步。 整个插件追求三件事：**简单**（零配置即可上手，填入 Token 即用）、**免费**（无需自建服务器，依托 Gist 存储）、**隐私优先**（所有个人 Token 仅保存在本地浏览器存储，书签数据加密存储于你私有的 Gist，不经过任何第三方服务器）。 ## 核心特性 | 特性 | 说明 | | --- | --- | | **双平台支持** | 同时对接 GitHub Gist 与 Gitee，可自由切换同步对象，互不干扰 | | **双向同步** | 支持本地上传至远端、远端下载至本地两个方向 | | **两种同步模式** | 覆盖模式以当前设备为准整体替换；合并模式按 URL 去重，保留两端新增 | | **智能自动同步** | 定时任务自动比较本地与远端数量，选择更优方向同步，避免覆盖更多数据 | | **状态对比分析** | 一键检查本地独有、远端独有、两端共有项，并检测书签的**顺序 / 位置变化**（如重新排序、移动文件夹），差异一目了然 | | **同步趋势** | 内置近 7 日同步次数柱状图，直观掌握同步频率 | | **历史记录** | 完整记录每次同步的平台、方向、结果，支持搜索、筛选与分页 | | **书签浏览页** | 独立页面（`nav.html`）以层级树形展示全部书签，可快速跳转，便于在弹窗外浏览与管理 | | **自动清理旧片段** | 启动时清理同名旧 Gist，仅保留最新一份，避免重复堆积 | | **实时未同步提醒** | 监听书签增删改，书签变动即刻在扩展图标显示角标红点 | | **零依赖** | 纯原生 JavaScript 实现，无任何前端框架，体积小巧 | ## 界面预览 MiniMark 采用 420×600 的卡片化弹窗设计，主色调为清新绿色（`#22c55e`），整体风格现代简洁。 - **状态总览卡**：圆形状态指示、同步进度条、自动同步开关与同步对象标签，一眼掌握当前同步状态 - **三栏统计**：本地书签数、远端书签数、差异项数（含顺序/位置变化项），差异卡可点击展开对比详情 - **快速操作**：醒目的"本地→远端"上传与"远端→本地"下载双按钮 - **书签浏览**：点击状态总览卡中的本地书签数，或主页的浏览入口，打开独立的树形书签浏览页 - **定时同步**：iOS 风格开关，可查看下次执行时间 - **健康报告**：近 7 天同步异常提示条 - **7 日趋势图**：柱状图展示本周每日同步次数，高亮峰值与今日 - **同步仓库**：GitHub / Gitee 双仓库卡片，显示分支与书签数，点击直达 Gist 页面 - **同步记录**：最近 8 条同步历史，可进入全量视图搜索筛选 ![bookmark.png](docs/bookmark.png) ## 安装方式 ### 方式一：开发者模式加载（推荐） 1. 下载或克隆本仓库到本地： ```bash git clone https://gitcode.com/mininote/MiniMark.git ``` 2. 打开 Chrome（或任何 Chromium 内核浏览器，如 Edge、Brave），进入扩展管理页： ``` chrome://extensions/ ``` 3. 打开右上角**开发者模式**开关。 4. 点击**加载已解压的扩展程序**，选择本项目的根目录（包含 `manifest.json` 的文件夹）。 5. 扩展图标出现在工具栏，点击即可使用。 ### 方式二：打包安装 若已发布到 Chrome 应用商店或 Edge Add-ons，可直接通过商店链接安装（发布后在此补充链接）。 ## 快速开始 ### 1. 获取平台 Token MiniMark 通过 Token 访问你的 Gist，请按需获取： - **GitHub**：访问 [Personal Access Tokens](https://github.com/settings/tokens)，生成一个勾选 `gist` 权限的 Classic Token。 - **Gitee**：访问 [私人令牌](https://gitee.com/profile/personal_access_tokens)，生成一个勾选 `gists` 权限的令牌。 ### 2. 配置连接 1. 点击扩展图标打开弹窗。 2. 点击右上角设置按钮进入设置页。 3. 在**账号连接**中粘贴对应平台的 Token，点击**验证**。验证成功后会显示你的用户名与头像。 ![bookmarksync.png](docs/bookmarksync.png) ### 3. 选择同步对象 在设置页的**同步对象**中选择 GitHub 或 Gitee 作为默认同步平台。 ### 4. 开始同步 回到主页，根据需求操作： - 点击**检查状态**：对比本地与远端差异，弹窗展示本地独有、远端独有以及**顺序/位置变化**，内容过多时弹窗内部独立滚动。 - 点击**本地 → 远端**：将本地书签上传备份。 - 点击**远端 → 本地**：将远端书签恢复到本地。 - 打开**定时同步**开关：按设定间隔自动同步。 ## 同步策略 MiniMark 提供两种同步模式，在设置页的**同步设置**中切换： ### 覆盖模式（默认） 以当前设备书签为准，整体替换远端（上传时）或本地（下载时）。适合单设备主导、追求强一致的场景。下载恢复时会先清空本地书签栏内容再写入远端数据。 ### 合并模式 按 URL 去重，保留两端各自新增的书签。上传时先将远端书签合并进本地（不删除本地已有项），再整体上传；下载时同样以合并方式写入本地。适合多设备并行使用的场景，最大限度避免书签丢失。 ### 智能自动同步 开启定时同步后，后台任务会自动比较本地与远端书签数量并智能选择方向： - 远端数量多于本地：从远端下载，避免覆盖更多数据。 - 本地数量不少于远端：上传到远端。 合并模式下则统一执行双向合并，无需比较数量。 ## 隐私与安全 MiniMark 的设计以隐私为前提： - **Token 仅存本地**：你的 GitHub / Gitee Token 保存在浏览器的 `chrome.storage.local` 中，不会上传到任何第三方服务器。 - **书签存储于私有 Gist**：同步时创建的 Gist 默认为私有（`public: false`），仅你本人可见。 - **直连平台 API**：所有数据请求直接发往 `api.github.com` 与 `gitee.com`，扩展本身不架设任何中转服务。 - **最小权限**：仅申请 `bookmarks`、`storage`、`alarms` 三个权限，以及两个平台的网络访问权限。 如需彻底清除数据，可在设置页**数据管理**中选择清空本地书签或全部重置。 ## 项目结构 ``` MiniMark/ ├── manifest.json # 扩展清单（Manifest V3） ├── background.js # Service Worker，后台同步逻辑核心 ├── popup.html # 弹窗界面结构 ├── popup.css # 弹窗样式 ├── popup.js # 弹窗交互逻辑 ├── nav.html # 书签浏览页（独立树形浏览界面） ├── nav.css # 书签浏览页样式 ├── nav.js # 书签浏览页交互逻辑 ├── _locales/ # 多语言资源（仅 manifest 的 name/description 使用） │ ├── en/messages.json │ └── zh_CN/messages.json └── icons/ # 图标资源 ├── icon16.png ├── icon48.png ├── icon128.png ├── logo.png ├── github.svg └── gitee.svg ``` ## 技术实现 MiniMark 基于 Chrome 扩展 Manifest V3 规范开发，采用纯原生 JavaScript，无任何构建步骤与运行时框架依赖。 - **Service Worker（`background.js`）**：承载全部同步核心逻辑，包括 Token 验证、Gist 增删改查、书签树序列化与恢复、智能同步决策、旧片段清理。通过 `chrome.alarms` 实现定时任务，监听 `chrome.bookmarks` 事件实时标记未同步状态并更新角标。 - **弹窗界面（`popup.*`）**：负责状态展示与用户交互，通过 `chrome.runtime.sendMessage` 与后台 Service Worker 通信。采用卡片化栅格布局，iOS 风格开关，内嵌 SVG 图标，无需任何外部图标库。 - **数据存储**：所有配置与同步状态通过 `chrome.storage.local` 持久化，包括 Token、Gist ID、同步历史（保留最近 50 条）、同步间隔等。 - **同步状态分析**：将本地与远端书签树扁平化，除比较 URL 集合（交集/差集）外，还为每个书签计算含层级顺序的签名 `orderKey`，能够检测书签被重新排序或移动到其他文件夹等结构性变化，生成可视化对比报告。 ## 开发指南 本项目无需安装任何依赖，克隆后即可直接加载调试。 1. 克隆仓库并按[安装方式](#安装方式)加载到浏览器。 2. 在 `chrome://extensions/` 页面点击扩展卡片上的**详情** → **检查视图**，可打开 Service Worker 的 DevTools 进行后台调试。 3. 点击扩展图标打开弹窗后右键**检查**，可调试弹窗界面。 4. 修改代码后，在扩展管理页点击刷新按钮即可重新加载。 调试技巧： - 后台日志输出在 Service Worker 的 Console 中。 - `chrome.storage.local` 的内容可在弹窗 DevTools 的 Application → Storage → Local Storage 中查看。 - 书签数据格式为 `{ version, timestamp, count, bookmarks }`，`bookmarks` 即 `chrome.bookmarks.getTree()` 的原始结构。 > **关于多语言**：目前仅 `manifest.json` 的 `name` / `description` 走 `_locales` 国际化占位符，弹窗与浏览页 UI 为硬编码中文。后续若要做完整中英文界面，需改造 `popup.*` / `nav.*`。 ## 常见问题 **Q：同步时报"Gitee 数据过大"怎么办？** Gitee 限制单个 Gist 文件最大 1MB。当书签数据超过此限制时会中断同步，建议改用 GitHub（无此限制）或精简书签数量。 **Q：Gitee 同步后书签标题里的 emoji 消失了？** Gitee 的数据库不支持 4 字节 UTF-8 字符（大部分 emoji），写入会报错。MiniMark 在上传 Gitee 前会自动剥离这类字符以保证同步成功，GitHub 则完整保留。 **Q：换了一台电脑，如何恢复书签？** 在新设备安装扩展并配置同一平台的 Token，进入主页点击**远端 → 本地**即可恢复。覆盖模式下会先清空本地再写入远端数据。 **Q：自动同步会覆盖我新加的书签吗？** 智能自动同步会比较两端数量，选择数据更多的一端为准，尽量避免丢失。若多设备并行使用，建议切换为**合并模式**，按 URL 去重保留两端新增。 **Q：Token 会泄露吗？** Token 仅存储在本地浏览器，所有请求直连 GitHub / Gitee 官方 API，扩展不经过任何第三方服务。Gist 默认创建为私有，仅你本人可见。 ## 贡献指南 欢迎通过 Issue 和 Pull Request 参与本项目。 1. Fork 本仓库。 2. 创建你的特性分支：`git checkout -b feature/your-feature`。 3. 提交更改：`git commit -m 'Add some feature'`。 4. 推送分支：`git push origin feature/your-feature`。 5. 提交 Pull Request 并描述你的改动。 提交前请确保： - 代码风格与现有保持一致（原生 JavaScript，无框架依赖）。 - 不引入新的运行时依赖。 - 涉及 UI 改动时保持 420×600 弹窗尺寸内的良好显示效果。 ## 开源协议 本项目采用 [MIT License](LICENSE) 开源协议。如需在项目中使用，请遵循协议要求保留版权声明。