gao/ljwx-docs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix: 更新 GitHub 仓库链接

Browse Source 
- 更新 VitePress 配置中的 socialLinks
- 更新中文首页的 GitHub 链接
- 更新英文首页的 GitHub 链接
- 修正 git clone 命令和 Issues 链接

正确的仓库地址：https://github.com/BrunoGao/ljwx-docs

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
bruno
2026-01-23 18:19:36 +08:00
co-authored by Claude Sonnet 4.5
parent a02a198afb
commit c8aabd4fcc
6 changed files with 418 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
GISCUS-CONFIG-STEPS.md
+101
View File
@@ -0,0 +1,101 @@
# Giscus 配置步骤（BrunoGao/ljwx-docs）
## ✅ 已完成
- [x] GitHub 仓库已创建：`BrunoGao/ljwx-docs`
- [x] 代码已推送到 GitHub
## 📋 接下来的步骤
### 第 1 步：启用 Discussions（2 分钟）
1. 访问您的 GitHub 仓库：
```
https://github.com/BrunoGao/ljwx-docs
```
2. 点击仓库顶部的 **Settings**（设置）标签
3. 在左侧菜单中，找到 **General**（常规）部分
4. 向下滚动到 **Features**（功能）区域
5. 勾选 ✅ **Discussions** 复选框
6. 点击页面底部的 **Save changes**（保存更改）
### 第 2 步：安装 Giscus App（1 分钟）
1. 访问 Giscus App 安装页面：
```
https://github.com/apps/giscus
```
2. 点击绿色的 **Install** 按钮
3. 选择安装位置：
- 选择 **Only select repositories**（仅选定的仓库）
- 在下拉菜单中选择 `BrunoGao/ljwx-docs`
4. 点击 **Install** 确认安装
### 第 3 步：获取 Giscus 配置（2 分钟）
1. 访问 Giscus 配置页面：
```
https://giscus.app/zh-CN
```
2. 在 **仓库** 输入框中填写：
```
BrunoGao/ljwx-docs
```
3. 页面会自动验证，您应该看到：
```
✅ 公开仓库
✅ 已安装 giscus app
✅ 已启用 Discussions
```
4. 在 **Discussion 分类** 部分：
- 选择 **Announcements** 或 **General**（推荐 General）
5. 向下滚动到 **启用 giscus** 部分
6. 复制生成的配置代码，找到这四个值：
```html
data-repo="BrunoGao/ljwx-docs"
data-repo-id="R_kgDO..." ← 复制这个值
data-category="General"
data-category-id="DIC_kwDO..." ← 复制这个值
```
### 第 4 步：更新配置文件
**请将您获取的配置值告诉我，格式如下：**
```
repo-id: R_kgDO...
category: General
category-id: DIC_kwDO...
```
我会帮您更新配置文件。
---
## 🎯 快速链接
- GitHub 仓库：https://github.com/BrunoGao/ljwx-docs
- Giscus App：https://github.com/apps/giscus
- Giscus 配置：https://giscus.app/zh-CN
## 💡 提示
- 如果看不到 Settings 标签，请确认您已登录 GitHub 且有仓库的管理权限
- Discussions 启用后，仓库顶部会出现 **Discussions** 标签
- Giscus App 安装后，可以在 Settings → Integrations 中查看
## ❓ 遇到问题？
如果遇到任何问题，请告诉我具体的错误信息或截图，我会帮您解决。
GISCUS-SETUP.md
+156
View File
@@ -0,0 +1,156 @@
# Giscus 评论系统配置指南
## 📋 前置要求
1. 需要一个 **公开的** GitHub 仓库
2. 仓库需要启用 **Discussions** 功能
3. 需要在仓库上安装 **Giscus App**
## 🚀 配置步骤
### 第 1 步：准备 GitHub 仓库
**选项 A：使用现有的 Git 仓库（如果在 GitHub 上）**
如果您的仓库 `http://192.168.1.83:33000/gao/ljwx-docs.git` 是私有 Gitea 服务器，您需要：
- 在 GitHub 上创建一个新的公开仓库用于评论
- 或者将现有仓库镜像到 GitHub
**选项 B：创建新的 GitHub 仓库**
1. 访问 https://github.com/new
2. 创建一个公开仓库（例如：`ljwx-docs` 或 `ljwx-docs-comments`）
3. 仓库可以为空，只用于存储评论
### 第 2 步：启用 Discussions
1. 进入您的 GitHub 仓库
2. 点击 **Settings**（设置）
3. 滚动到 **Features**（功能）部分
4. 勾选 ✅ **Discussions**
### 第 3 步：安装 Giscus App
1. 访问 https://github.com/apps/giscus
2. 点击 **Install**（安装）
3. 选择您要安装的仓库：
- **All repositories**（所有仓库）
- **Only select repositories**（仅选定的仓库）- 推荐，选择您的文档仓库
4. 点击 **Install**
### 第 4 步：获取 Giscus 配置
1. 访问 https://giscus.app/zh-CN
2. 在 **配置** 部分填写：
- **仓库**：输入您的 GitHub 仓库（格式：`用户名/仓库名`）
- 例如：`ljwx/ljwx-docs`
3. 页面会自动检查仓库是否满足条件：
```
✅ 公开仓库
✅ 已安装 giscus app
✅ 已启用 Discussions
```
4. **Discussion 分类**：选择 **General**（或创建新分类）
5. 向下滚动到 **启用 giscus** 部分
6. 复制生成的配置，您会看到类似这样的代码：
```html
<script src="https://giscus.app/client.js"
data-repo="您的用户名/仓库名"
data-repo-id="R_kgDOxxxxxxxxx"
data-category="General"
data-category-id="DIC_kwDOxxxxxxxxx"
...
</script>
```
### 第 5 步：更新配置文件
从上面的脚本中提取这四个值：
- `data-repo`：您的 GitHub 仓库
- `data-repo-id`：仓库 ID（以 R_kgDO 开头）
- `data-category`：Discussion 分类名称
- `data-category-id`：分类 ID（以 DIC_kwDO 开头）
编辑文件 `docs/.vitepress/theme/components/GiscusComment.vue`：
```typescript
// 第 31-34 行，替换为您的真实配置
const repo = computed(() => '您的GitHub用户名/仓库名')
const repoId = computed(() => 'R_kgDOxxxxxxxxx') // 从 giscus.app 获取
const category = computed(() => 'General')
const categoryId = computed(() => 'DIC_kwDOxxxxxxxxx') // 从 giscus.app 获取
```
### 第 6 步：测试评论系统
1. 保存配置文件
2. 重启开发服务器：
```bash
pnpm dev
```
3. 访问任意文档页面（不是首页）
4. 滚动到页面底部，应该能看到 Giscus 评论框
## 🔧 配置示例
```typescript
// 真实配置示例（您需要替换为自己的值）
const repo = computed(() => 'brunogao/ljwx-docs')
const repoId = computed(() => 'R_kgDOKZ3q5Q')
const category = computed(() => 'General')
const categoryId = computed(() => 'DIC_kwDOKZ3q5c4Cc8c0')
```
## 🎨 深色模式支持
配置完成后，Giscus 会自动跟随 VitePress 的深色模式切换。
## 📱 移动端优化
Giscus 已自动适配移动端，无需额外配置。
## 🚫 禁用评论
如果某个页面不想显示评论，在 Markdown 文件的 frontmatter 中添加：
```yaml
---
comment: false
---
```
## ❓ 常见问题
### Q1: 仓库必须是公开的吗？
是的，Giscus 只支持公开仓库。私有仓库无法使用。
### Q2: 我的主仓库是私有的 Gitea，怎么办？
您可以在 GitHub 创建一个单独的公开仓库，仅用于存储评论。文档仍然托管在您的 Gitea 服务器上。
### Q3: 评论数据存储在哪里？
评论存储在 GitHub Discussions 中，作为讨论主题。每个页面对应一个讨论。
### Q4: 可以迁移评论吗？
可以，评论存储在 GitHub Discussions 中，可以通过 GitHub API 导出和导入。
### Q5: 如何修改评论框样式？
编辑 `docs/.vitepress/theme/components/GiscusComment.vue` 的 `<style>` 部分。
## 🔗 相关链接
- [Giscus 官网](https://giscus.app/zh-CN)
- [Giscus GitHub](https://github.com/giscus/giscus)
- [GitHub Discussions 文档](https://docs.github.com/en/discussions)
## 💡 提示
如果您暂时不想配置评论系统，可以：
1. **完全移除评论组件**（在 Layout.vue 中）
2. **或保持现状**（配置错误时 Giscus 会显示友好的错误提示）
3. **或在所有页面禁用**（在 frontmatter 添加 `comment: false`）
---
配置完成后，您的文档网站将拥有一个现代化的评论系统！🎉
GISCUS-TEST-GUIDE.md
+154
View File
@@ -0,0 +1,154 @@
# ✅ Giscus 评论系统配置完成！
## 🎉 配置信息
- **GitHub 仓库**：BrunoGao/ljwx-docs
- **Repo ID**：R_kgDOQ_ockw
- **分类**：Announcements
- **Category ID**：DIC_kwDOQ_ock84C1Uqp
- **状态**：✅ 已配置并推送到仓库
## 🧪 测试评论系统
### 方法 1：本地测试
1. 访问本地开发服务器：
```
http://localhost:5555
```
2. 点击任意文档页面（例如：快速开始、指南等）
- **注意**：首页不显示评论，需要访问文档页面
3. 滚动到页面底部，您应该看到 Giscus 评论框
4. 如果看到评论框，说明配置成功！🎉
### 方法 2：远程测试
从局域网内其他设备访问：
```
http://192.168.1.83:5555
```
### 预期效果
**浅色模式：**
- 白色背景的评论框
- 蓝色主题色按钮
**深色模式：**
- 深色背景的评论框
- 自动切换主题
**多语言：**
- 中文页面显示中文界面
- 英文页面显示英文界面
## 📝 发表评论测试
1. 点击评论框中的 **Sign in with GitHub**
2. 授权 Giscus 访问您的 GitHub 账号
3. 输入测试评论，例如："测试评论系统 ✅"
4. 点击 **Comment** 发表
评论会自动保存到：
```
https://github.com/BrunoGao/ljwx-docs/discussions
```
## 🔍 验证评论存储
访问您的 GitHub Discussions：
```
https://github.com/BrunoGao/ljwx-docs/discussions
```
您应该能看到：
- **Announcements** 分类下有新的讨论
- 讨论标题对应文档页面的路径
- 评论内容显示在讨论中
## 🎨 评论框特性
✅ **自动主题切换**：跟随 VitePress 深色模式
✅ **多语言支持**：中英文自动切换
✅ **响应式设计**：完美适配移动端
✅ **Markdown 支持**：评论支持 Markdown 格式
✅ **表情反应**：支持点赞、点踩等反应
✅ **实时更新**：评论实时同步
## 🚫 禁用特定页面的评论
如果某个页面不想显示评论，在 Markdown 文件顶部添加：
```yaml
---
comment: false
---
```
## 📊 评论管理
所有评论都存储在 GitHub Discussions 中，您可以：
- 编辑评论
- 删除评论
- 锁定讨论
- 标记为已解决
- 导出评论数据
## 🔗 相关链接
- **GitHub 仓库**：https://github.com/BrunoGao/ljwx-docs
- **Discussions**：https://github.com/BrunoGao/ljwx-docs/discussions
- **Giscus 设置**：https://giscus.app/zh-CN
## ❓ 故障排查
### 问题 1：看不到评论框
**可能原因：**
- 访问的是首页（首页不显示评论）
- 浏览器缓存问题
**解决方法：**
1. 访问文档页面（不是首页）
2. 清除浏览器缓存并刷新
3. 检查浏览器控制台是否有错误
### 问题 2：评论框显示错误
**可能原因：**
- GitHub Discussions 未启用
- Giscus App 未安装
**解决方法：**
1. 访问 https://github.com/BrunoGao/ljwx-docs/settings
2. 确认 Discussions 已启用
3. 访问 https://github.com/apps/giscus 确认已安装
### 问题 3：无法登录评论
**可能原因：**
- 未登录 GitHub
- 浏览器阻止弹窗
**解决方法：**
1. 先登录 GitHub
2. 允许浏览器弹窗
3. 重新点击 "Sign in with GitHub"
## 🎯 下一步
评论系统已完全配置完成！您可以：
1. ✅ 测试评论功能
2. ✅ 邀请团队成员测试
3. ✅ 自定义评论框样式（编辑 GiscusComment.vue）
4. ✅ 配置评论通知（GitHub Settings → Notifications）
---
**配置完成时间**：2026-01-23
**配置文件**：docs/.vitepress/theme/components/GiscusComment.vue
**提交记录**：a02a198
docs/.vitepress/config.ts
+1 -1
View File
@@ -113,7 +113,7 @@ export default defineConfig({
// 社交链接
socialLinks: [
{ icon: 'github', link: 'https://github.com/ljwx' }
{ icon: 'github', link: 'https://github.com/BrunoGao/ljwx-docs' }
],
// 搜索配置 - 使用本地搜索
docs/en/index.md
+3 -3
View File
@@ -17,7 +17,7 @@ hero:
link: /en/knowledge-asset-automation-design
- theme: alt
text: GitHub
link: https://github.com/ljwx
link: https://github.com/BrunoGao/ljwx-docs
features:
- icon: 📚
@@ -121,7 +121,7 @@ Document metadata includes:
```bash
# Clone repository
git clone https://github.com/ljwx/ljwx-docs.git
git clone https://github.com/BrunoGao/ljwx-docs.git
cd ljwx-docs
# Install dependencies
@@ -160,5 +160,5 @@ npm run docs:serve
## Support and Feedback
- **Technical Support**: brunogao
- **Issue Reporting**: [GitHub Issues](https://github.com/ljwx/ljwx-docs/issues)
- **Issue Reporting**: [GitHub Issues](https://github.com/BrunoGao/ljwx-docs/issues)
- **Documentation Contribution**: Pull Requests are welcome
docs/index.md
+3 -3
View File
@@ -17,7 +17,7 @@ hero:
link: /knowledge-asset-automation-design
- theme: alt
text: GitHub
link: https://github.com/ljwx
link: https://github.com/BrunoGao/ljwx-docs
features:
- icon: 📚
@@ -121,7 +121,7 @@ graph LR
```bash
# 克隆仓库
git clone https://github.com/ljwx/ljwx-docs.git
git clone https://github.com/BrunoGao/ljwx-docs.git
cd ljwx-docs
# 安装依赖
@@ -160,5 +160,5 @@ npm run docs:serve
## 支持与反馈
- **技术支持**：brunogao
- **问题反馈**：[GitHub Issues](https://github.com/ljwx/ljwx-docs/issues)
- **问题反馈**：[GitHub Issues](https://github.com/BrunoGao/ljwx-docs/issues)
- **文档贡献**：欢迎提交 Pull Request