A GitBook plugin for AtomGit issue feedback with smart content extraction and precise positioning. Compatible with GitBook 3.x and Node.js 14-17.
一个为 GitBook 提供 AtomGit 问题反馈功能的插件。让读者可以轻松地从文档页面直接创建问题报告，提升文档维护效率。
- 🐛 一键问题报告 - 在文档页面添加浮动按钮，读者可快速创建问题报告
- 📝 智能内容提取 - 自动提取选中的文本和当前页面信息
- 🔗 自动生成链接 - 自动生成源文件链接和编辑链接
- ⚙️ 灵活配置 - 支持私有仓库、自定义标签等多种配置选项
- 🎯 精确定位 - 支持精确定位到具体行号，便于问题修复
- 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 中添加依赖：
``json`
{
"dependencies": {
"gitbook-plugin-AtomGit-issue-feedback": "^1.4.5"
}
}
然后运行：
`bash`
npm install
gitbook install
方法二：使用 GitBook 安装
如果您已经在 book.json 中配置了插件，直接运行：
`bash`
gitbook install
方法三：本地开发安装
如果您正在本地开发插件或需要修改插件代码：
`bash`在您的 GitBook 项目中
npm install --save file:../path/to/gitbook-plugin-AtomGit-issue-feedback
gitbook install
`bash`
npm install gitbook-plugin-AtomGit-issue-feedback
gitbook install
在您的 book.json 文件中添加插件配置：
`json`
{
"gitbook": ">=3.0.0",
"title": "您的文档标题",
"plugins": [
"gitcode-issue-feedback"
],
"pluginsConfig": {
"gitcode-issue-feedback": {
"repo": "owner/repository-name"
}
}
}
#### 必需参数
- repo (string): AtomGit 仓库路径，格式为 owner/name
#### 可选参数
- label (string): 按钮标签文字，默认为 "Bug Report"
- (boolean): 是否为私有仓库，默认为 false
- (string): 自定义新建问题的 URLmarkdownBaseURL
- (string): 资源文件的基础 URLgitcodeAPIBaseURL
- (string): AtomGit 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://atomgit.com/your-org/your-repo/issues/new",
"markdownBaseURL": "https://atomgit.com/your-org/your-repo/blob/master/",
"gitcodeAPIBaseURL": "https://api.atomgit.com/repos/your-org/your-repo/contents/"
}
}
}
`bash`
gitbook serve
访问 http://localhost:4000 查看效果。
插件会在文档页面右下角添加一个浮动的「Bug Report」按钮。当用户点击按钮时，会自动：
1. 提取当前页面标题
2. 获取选中的文本内容（如果用户选中了文本）
3. 生成源文件链接和编辑链接
4. 跳转到 AtomGit 新建问题页面，自动填充问题内容
- 默认状态: 显示配置的标签文字（如 "Bug Report"）
- 加载状态: 显示 "Loading..." 并显示加载动画
- 成功状态: 显示 "Issue Created!" 并变为绿色
- 错误状态: 显示错误信息并变为红色
`bash克隆仓库
git clone https://atomgit.com/nutpi/gitbook-plugin-AtomGit-issue-feedback.git
cd gitbook-plugin-AtomGit-issue-feedback
$3
gitbook-plugin-gitcode-issue-feedback/
├── src/ # 源代码目录
│ ├── plugin.js # 插件主文件
│ ├── BugReporter.js # Bug 报告类
│ └── styles.css # 样式文件
├── assets/ # 构建输出目录
│ └── plugin.js # 编译后的插件文件
├── test/ # 测试文件
├── example/ # 示例项目
└── index.js # 插件入口文件
❓ 常见问题
$3
A: 请打开浏览器开发者工具（F12），查看控制台（Console）中的错误信息。常见问题：
1. 配置错误: 检查
中的 repo 配置是否正确
2. 网络问题: 检查是否能访问 AtomGit API
3. 浏览器阻止弹窗: 允许该网站的弹窗更多调试信息请查看 调试指南。
$3
A: 如果遇到
graceful-fs 相关错误，有两种解决方案：1. 推荐: 使用 nvm 切换到 Node.js 16：
`bash
nvm install 16
nvm use 16
`2. 临时方案: 修改
，注释掉第 62-64 行详见 Node.js 兼容性说明。
$3
A: 检查以下几点：
1. 确认插件已正确安装：
gitbook install
2. 检查 中是否添加了插件到 plugins 数组
3. 检查浏览器控制台是否有 JavaScript 错误
4. 确认插件配置中的 repo 字段已正确设置$3
A: 您可以在 GitBook 的
styles/website.css 文件中添加自定义样式：`css
.gitbook-plugin-AtomGit-issue-feedback {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
border-radius: 25px;
font-size: 14px;
padding: 10px 20px;
}
`$3
A: 是的，设置
即可：`json
{
"pluginsConfig": {
"gitcode-issue-feedback": {
"repo": "your-org/private-repo",
"private": true
}
}
}
`📝 更新日志
查看 Releases 页面 了解版本更新详情。
$3
- v1.4.4:
- 改进错误处理和调试信息
- 修复 Node.js 23+ 兼容性问题
- 增强容错机制，自动回退到简单模式
- 添加详细的调试日志
🤝 贡献
我们欢迎各种形式的贡献！
$3
如果您发现了 bug 或有功能建议，请 创建一个 issue。
$3
1. Fork 本仓库
2. 创建您的功能分支：
3. 提交您的更改：
4. 推送到分支：本项目基于 MIT 许可证 开源。
---
⭐ 如果这个项目对您有帮助，请给我们一个 Star！