# new-tab-markdown

**Repository Path**: pharaoh_admin/new-tab-markdown

## Basic Information

- **Project Name**: new-tab-markdown
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Markdown New Tab

> 把你每天打开的"新标签页"变成一块可以随时记录的 Markdown 草稿本。
> 同时支持 Chrome 与 Edge（Manifest V3）。

![界面预览](screenshot.png)

用 Markdown 写笔记、记待办、贴链接、写清单——所有内容直接呈现在新标签页，启动浏览器即看见。

---

## ✨ 特性

- **多标签页管理**：左侧 Tab 列表，支持新增、切换、改名、拖拽排序。
- **实时 Markdown 预览**：编辑即所见，所见即所得（基于 [ByteMD](https://github.com/bytedance/bytemd)）。
- **干净的阅读视图**：展示页居中渲染，样式收敛在 `src/markdown.css`，无多余干扰。
- **本地持久化**：使用 `chrome.storage`（`unlimitedStorage` 配额），无大小限制。
- **云端同步**：支持 **GitHub Gist** 与 **Gitee Gist** 双向同步，多设备无缝接力。
- **冲突按 tab 合并**：同 `tabid` 比较各自 `time`（最后修改时间），取较新的一方；不同 `tabid` 的标签并入双方，不会互相覆盖。
- **零后端依赖**：同步全部走公开 API，无需自建服务器、可任意更换服务。

---

## 📦 安装

### 方式一：开发模式（推荐先体验）

1. 克隆仓库
   ```bash
   git clone https://github.com/<your-name>/new-tab-markdown.git
   ```
2. 打开浏览器扩展页
   - Chrome：访问 `chrome://extensions/`
   - Edge：访问 `edge://extensions/`
3. 开启右上角 **"开发者模式"**
4. 点击 **"加载已解压的扩展程序"**，选择仓库内的 `src/` 目录
5. 新开一个标签页，即可看到 Markdown New Tab

### 方式二：打包后加载

推荐用仓库根的打包脚本生成合规 zip（manifest 位于 zip 根、`lib/` 完整保留），解压后按方式一加载：

```bash
.\pack.ps1      # Windows
# 或
./pack.sh       # macOS / Linux
```

将生成的 `dist/markdown-new-tab-vX.Y.Z.zip` 解压后再按方式一加载；或用 `chrome://extensions/`（或 `edge://extensions/`）中的"打包扩展程序"生成 `.crx`。

---

## 🚀 打包与发布

项目零构建，直接用脚本把 `src/` 打包成符合商店规范的 zip：

```bash
.\pack.ps1      # Windows
./pack.sh       # macOS / Linux
```

- 产物为 `dist/markdown-new-tab-vX.Y.Z.zip`，版本号自动取自 `src/manifest.json`。
- zip 内第一层即 `manifest.json`（满足 Chrome/Edge 商店要求），`lib/` 完整保留。
- 完整上架步骤（Edge Add-ons / Chrome 导入、隐私政策模板、素材清单）见 [PUBLISH.md](PUBLISH.md)。

---

## 🚀 使用

| 操作 | 入口 |
|------|------|
| 创建新标签 | 点击左侧 Tab 列表底部的 `+` |
| 切换标签 | 点击左侧 Tab 名称 |
| 编辑内容 | 右上角铅笔图标 → 进入编辑页 |
| 调整顺序 | 拖拽左侧 Tab 即可 |
| 改名 | 编辑页顶部标题输入框 |
| 保存 | 编辑页右上角 ✓ 按钮（同步触发云端推送） |
| 同步设置 | 右上角齿轮 → 设置页 |

打开编辑页时，扩展会**自动比对 `lastSyncTime`**，按需拉取或推送，保证多设备数据一致。

> ⚠️ 切换 Tab 或关闭页面时若存在未保存修改，会自动弹窗提示。

---

## ⚙️ 同步配置

进入"设置"页，填写以下两项即可启用云端同步：

| 字段 | 说明 |
|------|------|
| **Provider** | `GitHub` 或 `Gitee` |
| **Token** | 拥有 `gist` 权限的个人访问令牌（Personal Access Token） |
| **Gist ID** | 已有 Gist 时填写；留空则首次同步自动创建 |

### 获取 Token

- **GitHub**：<https://github.com/settings/tokens> → 生成新 token，勾选 `gist` 范围即可。
- **Gitee**：<https://gitee.com/profile/personal_access_tokens> → 提交生成，勾选 `Gist` 权限。

### 同步策略

- **合并而非覆盖**：打开编辑页时拉取远程，与本地做**按 tab 合并**——同 `tabid` 取 `time` 较新的一方（相等时优先本地），不同 `tabid` 的标签并入双方。
- **回推收敛**：合并结果先写回本地存储，再上传远程，使多端数据最终一致。
- **适合多设备并行使用**：两端各自新增的标签都会保留，同一标签以最新修改为准。

---

## 🗂 数据结构

数据完全保存在 `chrome.storage.local` 中，由三类文件组成：

### `tabs.json` — 标签索引

```json
{
  "currentTabId": "20260804120533",
  "lastSyncTime": 1785818437116,
  "tabs": [
    {
      "tabid": "20260804120533",
      "title": "新标签",
      "time": 1691222333000
    }
  ]
}
```

> `tabid` 使用简化时间戳（如 `20260804120533`），既是唯一 ID 也是文件名。

### Markdown 源文件

`<timestamp>.md` —— 每个 Tab 对应一份 Markdown 原文。

### 渲染缓存

`<timestamp>.html` —— 渲染后的 HTML 片段，用于展示页极速读取，免去每次解析。

---

## 🧱 技术栈

| 模块 | 用途 |
|------|------|
| Manifest V3 | 浏览器扩展规范 |
| 原生 ES Modules | 无打包步骤，直接 `<script type="module">` |
| [ByteMD](https://github.com/bytedance/bytemd) | Markdown 编辑器 + 实时预览 |
| [Marked](https://github.com/markedjs/marked) | 备用 Markdown 渲染器 |
| [SortableJS](https://github.com/SortableJS/Sortable) | Tab 拖拽排序 |
| GitHub Gist API / Gitee Gist API | 云端同步 |

代码无任何前端框架与构建工具，clone 即可运行。

---

## 📁 项目结构

```
new-tab-markdown/
├── screenshot.png          # 界面截图
├── 开发说明.md              # 原始开发文档
├── README.md               # 你正在阅读
└── src/
    ├── manifest.json       # 扩展清单
    ├── index.html          # 展示页（新标签页）
    ├── edit.html           # 编辑页
    ├── settings.html       # 设置页
    ├── markdown.css        # Markdown 渲染样式
    ├── css/                # 通用 / 各页面样式
    ├── js/
    │   ├── index.js        # 展示页逻辑
    │   ├── edit.js         # 编辑页逻辑
    │   ├── settings.js     # 设置页逻辑
    │   ├── markdown.js     # Markdown 渲染封装
    │   ├── storage.js      # chrome.storage 读写
    │   ├── sync.js         # 同步引擎（GitHub / Gitee）
    │   └── utils.js        # 通用工具
    ├── lib/                # 第三方库（marked / bytemd / sortablejs）
    └── static/
        ├── icon/           # 16 / 48 / 128 像素图标
        ├── svg/            # 编辑、保存、设置等图标
        └── fonts/          # Fira Mono 字体（代码块）
```

---

## 🛠 开发

### 本地调试

按上方 **安装 → 方式一** 加载 `src/` 即可。修改任意文件后：

- HTML / CSS：刷新对应 Tab 即可看到效果
- JS（ES Module）：刷新 Tab；不需要重新加载扩展
- `manifest.json`：需要回到 `chrome://extensions/` 点击刷新按钮

### 调试同步

1. 在 `sync.js` 的 `_request` 处打断点
2. 编辑页右上角触发保存
3. 抓取 `https://api.github.com/gists/<id>` 或 `https://gitee.com/api/v5/gists/<id>` 验证

### 关于 Gitee 的坑

Gitee Gist API 在传输含 4 字节 UTF-8 字符（如 emoji `👋`）时会返回 500。`sync.js` 通过 **base64 编码中转** 绕过了此问题，这是 GitHub 与 Gitee 唯一行为差异。

---

## 📝 待办与想法

- [ ] 富文本片段（代码片段库）
- [ ] 全文搜索 / 标签分类
- [ ] 导出 PDF / 一键分享
- [ ] 主题切换（深色 / 浅色 / 自定义）

---

## 📄 许可

MIT License — 复制、修改、商用皆可，请保留原作者署名。

---

## 👤 作者

**pharaoh** — 有建议或想法欢迎提 Issue / PR。