gitbook-plugin-gitcode-issue-feedback

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

✨ 功能特性

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

📦 安装

系统要求

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

⚠️ 重要提示:

• 如果使用 Node.js 18+ 版本，可能会遇到兼容性问题
• 推荐使用 nvm 切换到 Node.js 16：nvm install 16 && nvm use 16
• 详见 Node.js 兼容性说明

安装方法

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

在您的 GitBook 项目的 package.json 中添加依赖：

{
  "dependencies": {
    "gitbook-plugin-gitcode-issue-feedback": "^1.4.4"
  }
}

然后运行：

npm install
gitbook install

方法二：使用 GitBook 安装

如果您已经在 book.json 中配置了插件，直接运行：

gitbook install

方法三：本地开发安装

如果您正在本地开发插件或需要修改插件代码：

# 在您的 GitBook 项目中
npm install --save file:../path/to/gitbook-plugin-gitcode-issue-feedback
gitbook install

🚀 快速开始

1. 安装插件

npm install gitbook-plugin-gitcode-issue-feedback
gitbook install

2. 配置插件

在您的 book.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

配置示例

私有仓库配置

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

自定义 URL 配置

{
    "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/"
        }
    }
}

3. 启动 GitBook

gitbook serve

访问 http://localhost:4000 查看效果。

📸 效果展示

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

1. 提取当前页面标题
2. 获取选中的文本内容（如果用户选中了文本）
3. 生成源文件链接和编辑链接
4. 跳转到 GitCode 新建问题页面，自动填充问题内容

按钮状态

• 默认状态: 显示配置的标签文字（如 "Bug Report"）
• 加载状态: 显示 "Loading..." 并显示加载动画
• 成功状态: 显示 "Issue Created!" 并变为绿色
• 错误状态: 显示错误信息并变为红色

🔧 详细配置

🛠️ 开发

本地开发

# 克隆仓库
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 dev

# 运行测试
npm test

项目结构

gitbook-plugin-gitcode-issue-feedback/
├── src/              # 源代码目录
│   ├── plugin.js     # 插件主文件
│   ├── BugReporter.js # Bug 报告类
│   └── styles.css    # 样式文件
├── assets/           # 构建输出目录
│   └── plugin.js     # 编译后的插件文件
├── test/             # 测试文件
├── example/          # 示例项目
└── index.js          # 插件入口文件

❓ 常见问题

Q: 点击按钮后显示错误怎么办？

A: 请打开浏览器开发者工具（F12），查看控制台（Console）中的错误信息。常见问题：

1. 配置错误: 检查 book.json 中的 repo 配置是否正确
2. 网络问题: 检查是否能访问 GitCode API
3. 浏览器阻止弹窗: 允许该网站的弹窗

更多调试信息请查看 调试指南。

Q: Node.js 23+ 版本报错怎么办？

A: 如果遇到 graceful-fs 相关错误，有两种解决方案：

1. 推荐: 使用 nvm 切换到 Node.js 16：

   nvm install 16
   nvm use 16

2. 临时方案: 修改 node_modules/npm/node_modules/graceful-fs/polyfills.js，注释掉第 62-64 行

详见 Node.js 兼容性说明。

Q: 插件没有显示按钮？

A: 检查以下几点：

1. 确认插件已正确安装：gitbook install
2. 检查 book.json 中是否添加了插件到 plugins 数组
3. 检查浏览器控制台是否有 JavaScript 错误
4. 确认插件配置中的 repo 字段已正确设置

Q: 如何自定义按钮样式？

A: 您可以在 GitBook 的 styles/website.css 文件中添加自定义样式：

.gitbook-plugin-gitcode-issue-feedback {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    border-radius: 25px;
    font-size: 14px;
    padding: 10px 20px;
}

Q: 支持私有仓库吗？

A: 是的，设置 private: true 即可：

{
    "pluginsConfig": {
        "gitcode-issue-feedback": {
            "repo": "your-org/private-repo",
            "private": true
        }
    }
}

📝 更新日志

查看 Releases 页面 了解版本更新详情。

最新版本

• v1.4.4:
  • 改进错误处理和调试信息
  • 修复 Node.js 23+ 兼容性问题
  • 增强容错机制，自动回退到简单模式
  • 添加详细的调试日志

🤝 贡献

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

报告问题

如果您发现了 bug 或有功能建议，请 创建一个 issue。

提交代码

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

📄 许可证

本项目基于 MIT 许可证 开源。

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