gitbook-plugin-gitcode-issue-feedback/README.md

A GitBook plugin for GitCode issue feedback with smart content extraction and precise positioning. Compatible with GitBook 3.x and Node.js 14-17.

# gitbook-plugin-gitcode-issue-feedback

[![npm version](https://badge.fury.io/js/gitbook-plugin-gitcode-issue-feedback.svg)](https://www.npmjs.com/package/gitbook-plugin-gitcode-issue-feedback)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

一个为 GitBook 提供 GitCode 问题反馈功能的插件。让读者可以轻松地从文档页面直接创建问题报告，提升文档维护效率。

## ✨ 功能特性

- 🐛 **一键问题报告** - 在文档页面添加浮动按钮，读者可快速创建问题报告
- 📝 **智能内容提取** - 自动提取选中的文本和当前页面信息
- 🔗 **自动生成链接** - 自动生成源文件链接和编辑链接
- ⚙️ **灵活配置** - 支持私有仓库、自定义标签等多种配置选项
- 🎯 **精确定位** - 支持精确定位到具体行号，便于问题修复

## 📦 安装

### 系统要求

- **Node.js**: 14.x - 17.x (推荐 16.x)
- **GitBook**: 3.x
- **操作系统**: macOS, Linux, Windows

### 安装方法

**方法一：使用 GitBook 安装（推荐）**

```bash
gitbook install
```

**方法二：本地安装（适用于 Node.js 18+）**

如果遇到 Node.js 兼容性问题，请使用本地安装：

```bash
# 创建插件目录
mkdir -p node_modules/gitbook-plugin-gitcode-issue-feedback

# 复制插件文件
cp plugin-files/* node_modules/gitbook-plugin-gitcode-issue-feedback/
```

> **注意**: 如果使用 Node.js 18+ 版本，建议使用本地安装方法。详见 [Node.js 兼容性说明](NODEJS_COMPATIBILITY.md)。

## 🚀 使用方法

### 基本配置

在您的 `book.json` 文件中添加插件配置：

```json
{
    "gitbook": ">=3.0.0",
    "title": "您的文档标题",
    "plugins": [
        "gitcode-issue-feedback"
    ],
    "pluginsConfig": {
        "gitcode-issue-feedback": {
            "repo": "owner/repository-name"
        }
    }
}
```

### 配置选项

#### 必需参数

- **`repo`** (string): GitCode 仓库路径，格式为 `owner/name`

#### 可选参数

- **`label`** (string): 按钮标签文字，默认为 `"Bug Report"`
- **`private`** (boolean): 是否为私有仓库，默认为 `false`
- **`newIssueURL`** (string): 自定义新建问题的 URL
- **`markdownBaseURL`** (string): 资源文件的基础 URL
- **`gitcodeAPIBaseURL`** (string): GitCode API 的基础 URL

### 配置示例

#### 私有仓库配置

```json
{
    "gitbook": ">=3.0.0",
    "title": "私有文档",
    "plugins": [
        "gitcode-issue-feedback"
    ],
    "pluginsConfig": {
        "gitcode-issue-feedback": {
            "repo": "your-org/private-repo",
            "private": true,
            "label": "报告问题"
        }
    }
}
```

#### 自定义 URL 配置

```json
{
    "gitbook": ">=3.0.0",
    "title": "自定义配置文档",
    "plugins": [
        "gitcode-issue-feedback"
    ],
    "pluginsConfig": {
        "gitcode-issue-feedback": {
            "repo": "your-org/your-repo",
            "label": "反馈问题",
            "newIssueURL": "https://gitcode.com/your-org/your-repo/issues/new",
            "markdownBaseURL": "https://gitcode.com/your-org/your-repo/blob/master/",
            "gitcodeAPIBaseURL": "https://api.gitcode.com/repos/your-org/your-repo/contents/"
        }
    }
}
```

## 📸 效果展示

插件会在文档页面右下角添加一个浮动的「Bug Report」按钮。当用户点击按钮时，会自动：

1. 提取当前页面标题
2. 获取选中的文本内容
3. 生成源文件链接和编辑链接
4. 跳转到 GitCode 新建问题页面

## 🛠️ 开发

### 本地开发

```bash
# 克隆仓库
git clone https://gitcode.com/nutpi/gitbook-plugin-gitcode-issue-feedback.git
cd gitbook-plugin-gitcode-issue-feedback

# 安装依赖
npm install

# 构建项目
npm run build

# 监听文件变化
npm run watch
```

### 运行测试

```bash
npm test
```

## 📝 更新日志

查看 [Releases 页面](https://gitcode.com/nutpi/gitbook-plugin-gitcode-issue-feedback/releases) 了解版本更新详情。

## 🤝 贡献

我们欢迎各种形式的贡献！

### 报告问题

如果您发现了 bug 或有功能建议，请 [创建一个 issue](https://gitcode.com/nutpi/gitbook-plugin-gitcode-issue-feedback/issues)。

### 提交代码

1. Fork 本仓库
2. 创建您的功能分支：`git checkout -b feature/amazing-feature`
3. 提交您的更改：`git commit -m 'Add some amazing feature'`
4. 推送到分支：`git push origin feature/amazing-feature`
5. 提交 Pull Request

## 👨‍💻 作者

- [GitCode/nutpi](https://gitcode.com/nutpi)

## 📄 许可证

本项目基于 [MIT 许可证](LICENSE) 开源。

---

⭐ 如果这个项目对您有帮助，请给我们一个 Star！