# gitee-book

**Repository Path**: leo58/gitee-book

## Basic Information

- **Project Name**: gitee-book
- **Description**: 一个基于浏览器的 Markdown 阅读器，支持从 Gitee 仓库下载和阅读 Markdown 文件，并提供阅读进度跟踪和跨设备同步功能。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-14
- **Last Updated**: 2025-11-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Markdown 阅读器

一个基于浏览器的 Markdown 阅读器，支持从 Gitee 仓库下载和阅读 Markdown 文件，并提供阅读进度跟踪和跨设备同步功能。

## ✨ 特性

- 📚 **多仓库支持**：支持从多个 Gitee 仓库下载和阅读 Markdown 文件
- 💾 **离线阅读**：使用 IndexedDB 本地存储，支持离线阅读
- 📊 **阅读进度**：自动跟踪阅读进度，支持进度可视化（圆环指示器）
- 🔄 **进度同步**：支持将阅读进度同步到 Gitee 仓库，实现跨设备同步
- 🎨 **代码高亮**：支持多种编程语言的语法高亮（JavaScript、TypeScript、Go、SQL、PHP、Bash 等）
- 📱 **响应式设计**：支持桌面端和移动端，自适应不同屏幕尺寸
- 🌓 **主题切换**：支持明暗主题切换
- 🔤 **字体调节**：支持字体大小动态调整
- 📑 **目录导航**：自动生成文档目录（大纲），支持快速跳转
- 🔍 **代码仓库**：支持查看代码仓库中的代码文件（非 Markdown 文件）

## 🚀 快速开始

### 使用方式

1. 直接在浏览器中打开 `index.html` 文件
2. 或者使用本地服务器运行（推荐）：

```bash
# 使用 Python 3
python3 -m http.server 8000

# 或使用 Node.js
npx serve .

# 或使用 PHP
php -S localhost:8000
```

3. 在浏览器中访问 `http://localhost:8000`

### 首次使用

1. 点击"新增书籍"按钮
2. 填写书籍信息：
   - **书籍名称**：显示在书库中的名称
   - **Gitee 仓库地址**：完整的 Gitee 仓库 URL（如：`https://gitee.com/username/repo-name`）
   - **Access Token**（可选）：如果不填写，将使用同步设置中配置的全局 Token
   - **内容类型**：选择"Markdown 书籍"或"代码仓库"
3. 点击"添加"后，系统会自动从 Gitee 下载内容

### 配置全局 Token（推荐）

为了避免每次添加书籍都要输入 Token，可以在同步设置中配置全局 Token：

1. 点击右上角的"同步设置"按钮
2. 在"全局 Access Token"中输入你的 Gitee Access Token
3. 保存后，添加书籍时可以不填写 Token，系统会自动使用全局 Token

## 📖 功能说明

### 阅读进度

- 阅读进度会自动保存到本地 IndexedDB
- 支持将进度同步到 Gitee 仓库
- 进度会在达到 50% 和 100% 时自动同步（同一文档的同步间隔至少为 1 分钟）
- 代码仓库不显示和上报阅读进度

### 同步设置

#### 启用 Gitee 同步
开启后，阅读进度会同步到 Gitee 仓库。

#### 自动同步
- **开启**：阅读进度会在达到 50% 和 100% 时自动同步到 Gitee，同一文档的同步间隔至少为 1 分钟
- **关闭**：需要手动点击书籍卡片上的"更新"按钮才会同步

#### 使用统一仓库存储阅读记录
- **开启**：所有书籍的阅读记录将存储在一个统一的仓库中
- **关闭**：每个书籍的阅读记录存储在其自己的仓库中

### 代码高亮

支持以下编程语言的语法高亮：
- JavaScript / TypeScript
- JSON
- CSS / SCSS / Less
- HTML / XML / SVG
- Bash / Shell
- PHP
- Go
- SQL (MySQL / PostgreSQL)

### 响应式设计

- **桌面端**：左侧文档树默认展开，右侧显示内容
- **移动端**：左侧文档树默认收起，点击菜单按钮展开

## 🛠️ 技术栈

- **前端框架**：纯原生 JavaScript（无框架依赖）
- **Markdown 渲染**：[markdown-it](https://github.com/markdown-it/markdown-it)
- **代码高亮**：[highlight.js](https://highlightjs.org/)
- **本地存储**：IndexedDB（用于存储书籍内容）
- **配置存储**：localStorage（用于存储应用设置）
- **API 集成**：Gitee API v5

## 📁 项目结构

```
read-markdown/
├── index.html              # 主页面
├── assets/
│   ├── main.js            # 主要业务逻辑
│   ├── styles.css         # 样式文件
│   └── vendor/            # 第三方库
│       ├── markdown-it.min.js
│       ├── highlight.min.js
│       ├── highlight.min.css
│       └── highlight-*.min.js  # 各语言的高亮支持
└── README.md              # 项目说明文档
```

## 🔧 配置说明

### Gitee Access Token

1. 登录 Gitee
2. 进入 **设置** → **安全设置** → **私人令牌**
3. 点击"生成新令牌"
4. 选择需要的权限（至少需要 `projects` 和 `user_info` 权限）
5. 复制生成的 Token 并保存

### 书籍配置

每个书籍可以配置以下选项：

- **书籍名称**：显示名称
- **Gitee 仓库地址**：仓库 URL
- **Access Token**（可选）：如果留空，使用全局 Token
- **内容分支**：读取内容时使用的分支（默认使用仓库默认分支）
- **进度分支**：存储阅读进度的分支（默认：`reading-progress`）
- **进度分支基准**：创建进度分支时的基准分支（默认使用仓库默认分支）

## 🔒 隐私与安全

- 所有数据存储在本地浏览器中（IndexedDB 和 localStorage）
- 阅读进度同步到 Gitee 仓库，需要你提供 Access Token
- Access Token 仅存储在本地浏览器中，不会上传到任何第三方服务器
- 代码完全开源，可自行部署和审查

## 📝 使用场景

- 📖 阅读技术文档和教程
- 📚 管理个人知识库
- 💻 查看代码仓库中的代码文件
- 📱 跨设备同步阅读进度
- 🌐 离线阅读已下载的内容

## 🐛 问题反馈

如果遇到问题或有功能建议，欢迎提交 Issue。

## 📄 许可证

本项目采用 MIT 许可证。

## 🙏 致谢

- [markdown-it](https://github.com/markdown-it/markdown-it) - Markdown 解析器
- [highlight.js](https://highlightjs.org/) - 代码语法高亮
- [Gitee](https://gitee.com/) - 代码托管平台

---

**注意**：本项目仅用于个人学习和使用，请遵守 Gitee 的使用条款和相关法律法规。