[Old-cpu]

动机

社团公告目前只能在公告页以纯链接列表展示，首页访客完全看不到社团动态；公告页本身也只是 Markdown 链接堆叠，缺少视觉层次；同时公告条目靠手写 Markdown，新成员容易写错格式。本 PR 一次性解决这三件事。

改动内容

1. 首页公告卡片区

• 覆写 theme/index.tsx 的 HomeLayout，通过官方 afterFeatures 插槽挂载，仅中文站启用
• 展示最新 6 条公告：日期 + 来源徽章（微信推文 / Gitee / 外部链接 / 里程碑）+ 标题（两行截断）
• 有链接的卡片点击新标签页跳转原文；无链接的里程碑渲染为静态卡片（不可点击）
• 区块头部提供「＋ 创建公告」与「查看全部 →」两个入口
• 滚动进入视口时卡片依次浮入（70ms 交错动画），prefers-reduced-motion 下自动关闭
• 样式全部使用 Rspress 主题变量（--rp-c-*），浅色 / 深色主题自动适配

2. 公告页全量卡片墙（/announcement/）

• 新增 AnnouncementList 组件：展示 announcements.json 的全部条目，按年份分组（新 → 旧），组头显示年份与条数
• 每个年份分组滚动进入视口时，卡片依次 blur-fade 浮入（组内 60ms 交错，纯 CSS 实现，无额外依赖）
• 无链接的里程碑条目同样渲染为静态卡片，与首页卡片样式统一
• 公告页与创建页的 MDX 入口从 .md 升级为 .mdx，直接挂载组件

3. 「创建公告」表单页（/announcement/create）

• 表单字段：原文链接（带格式校验）、卡片标题、发布日期（默认今天、可修改）；粘贴链接后自动识别来源（微信 / Gitee / 其他）
• 右侧实时预览卡片效果与生成的 Markdown 片段
• 一键复制片段；「去 GitHub 提交」按钮按 Fork 状态自动分流：
  • 填写 GitHub 用户名并「检测我的 Fork」（调用免鉴权 GitHub API，60 次 / 小时 / IP）
  • 已 Fork → 直达本人 Fork 的编辑页
  • 未 Fork / 未检测 → 走上游编辑链接，由 GitHub 自动引导一键创建 Fork
• 包括仓库管理者在内，所有人统一走 Fork + PR，官方仓库历史保持干净
• 本地预览（localhost / 127.0.0.1）时提交链接自动指向 new_page 分支，避免 announcements.md 尚未合入 master 导致的 404；正式上线后自动指回 master

4. 数据自动同步管线

• 公告源文件由 docs/zh/announcement/index.md 迁移到仓库根目录 announcements.md：位置更醒目，编辑入口固定，贡献者一眼能找到
• 新增 scripts/gen-announcements.mjs：从 announcements.md 提取标题 / 日期 / 链接 / 来源，生成 docs/components/announcements.json（自动倒序，最新在前）
• 挂到 predev / prebuild 钩子：维护者只维护公告一个文件，首页卡片与公告页自动同步，无需手工改两处

支持的书写格式：

### [标题：2024.9.27](https://mp.weixin.qq.com/s/…)          <!-- 可跳转公告 -->
### [标题：2024.9.21 - 2024.9.22](https://…)                 <!-- 时间范围 -->
### 标题：2023.6.25                                          <!-- 无链接里程碑，生成静态卡片 -->

数据流

announcements.md ──(predev / prebuild: gen-announcements.mjs)──▶ docs/components/announcements.json
                                                                          │
                        ┌─────────────────────────────────────────────────┴──────────────────┐
                        ▼                                                                    ▼
              首页公告卡片区（最新 6 条）                                       公告页全量卡片墙（按年份分组）
                        ▲
                        │
        创建公告表单（实时预览 → 复制 Markdown 片段 → 自己的 Fork 编辑 → PR 回流到 announcements.md）

提交流程

1. 在 /announcement/create 填写原文链接与卡片标题，复制生成的 Markdown 片段
2. 填写 GitHub 用户名 →「检测我的 Fork」→ 直达本人 Fork（未 Fork 时由 GitHub 引导创建）的 announcements.md 编辑页
3. 把片段粘贴到文件末尾，点击 Commit changes
4. GitHub 自动跳转 PR 页，确认目标为 TSGU-OSC/website 的 master 后提交

本地验证

npm install
npm run dev   # predev 钩子会自动生成 docs/components/announcements.json

• 首页：确认 features 下方出现公告卡片区（切到英文站应不显示）
• /announcement/：确认年份分组与滚动入场动画
• /announcement/create：填写链接 / 标题，确认实时预览与片段生成

说明与已知限制

• 公告数据为纯前端静态数据，站点无后端，所有新增公告都要经 PR 回流
• Fork 检测使用免鉴权 GitHub API（60 次 / 小时 / IP），限流或断网时仅提示「检测失败」，不影响正常提交
• 请勿直接修改 docs/components/announcements.json：它由脚本生成，下次 predev / prebuild 会被覆盖，请改 announcements.md
• 首页卡片区仅中文站挂载（公告数据为中文），英文站如需要可后续补充
• 首页仅取最新 6 条，完整列表见公告页

变更规模

13 个文件，+1504 / -3，5 个 commit。

[CapableCCat]

首先感谢这次提交。重新审阅了当前版本后，我认为这次改动不只是简单地增加首页公告卡片，而是尝试建立一套相对完整的公告管理与展示流程，整体设计值得肯定。

尤其是以下几个方面：

1. 数据源设计合理。 以仓库根目录的 announcements.md 作为单一数据源，通过 scripts/gen-announcements.mjs 生成 announcements.json，再供首页和公告归档页使用，避免了多处维护重复数据的问题。
2. 工作流设计完整。 从公告表单生成 Markdown、复制内容、引导用户通过 GitHub 提交修改，到构建阶段生成数据，再到首页和公告归档页展示，已经考虑了从投稿到展示的主要环节。
3. 符合静态站点的技术特点。 采用 GitHub Fork + PR 的方式收集公告，而不是为了这一功能额外引入后端服务，能够控制维护成本，也便于追踪和审核修改记录。
4. 展示体验考虑较全面。 首页展示最新公告、归档页按年份整理，配合来源标识、里程碑卡片、主题适配以及减少动态效果的处理，整体思路比较完整。
5. 具备进一步扩展的基础。 这套机制不仅可以服务于社团管理者，也可以让普通成员乃至社团外的开源贡献者参与公告纠错、文案优化和其他细节改进。

建议修改或验证的问题

1. Fork 检测需要更准确

目前 CreateAnnouncement.tsx 中的 checkFork 主要通过 GitHub API 返回的 data.fork 判断仓库是否为 Fork。

建议进一步确认 Fork 的来源仓库是否确实为 TSGU-OSC/website，而不只是判断它是否为某个仓库的 Fork。同时，可以校验用户名格式，并确认目标分支和 announcements.md 文件确实存在。

这样可以避免用户填写了一个同名、但与本项目无关的仓库时，页面仍然给出错误的投稿引导。

2. 需要验证实际的 GitHub 投稿流程

目前页面会引导用户进入自己的 Fork 编辑 announcements.md，并提示提交修改后可以继续创建 PR。

这里建议进行实际测试：在 Fork 中点击 Commit changes，并不意味着所有情况下 GitHub 都一定会自动进入创建上游 PR 的流程。具体行为还可能受到分支状态和 GitHub 页面交互的影响。

建议至少验证以下场景：

• 从未 Fork 过仓库的普通访客；
• 已经 Fork 过仓库的用户；
• Fork 尚未同步上游更新，或者缺少目标文件的用户；
• 社团成员和外部贡献者分别进行投稿的情况。

如果不能保证提交后能够顺利创建 PR，建议在页面中明确提供下一步指引，例如引导用户进入 Compare & pull request，或者手动创建指向 TSGU-OSC/website 的 PR，避免用户完成编辑后不知道如何继续。

3. 公告生成脚本应避免依赖文件排列顺序

目前 scripts/gen-announcements.mjs 使用 items.reverse() 反转公告列表，这隐含了一个前提：源 Markdown 中的公告始终按照日期从旧到新排列。

当前数据符合这一约定，因此这不一定是现存的功能错误。但未来如果有人补录较早的公告，或者编辑时没有遵循既定顺序，首页的“最新公告”就可能出现排序错误。

建议优先根据解析出的日期进行排序，并对无法识别或不合法的日期给出明确提示。对于关键字段缺失、日期格式错误等情况，也可以考虑在构建阶段报错，避免问题静默进入正式网站。

4. 可以适当加强公告表单的输入校验

目前 URL 校验主要依赖简单的正则表达式，日期字段也缺少严格的日期语义校验。

建议使用标准 URL 解析方式验证链接，并明确限制为 http 或 https 协议；同时校验日期格式，针对无效输入提供清晰的错误提示。

这不需要把表单做得过于复杂，重点是减少普通贡献者因为输入格式不正确而反复修改 PR 的情况。

5. 合并前需要完成构建和页面验证

目前还需要进一步确认以下事项：

• 完整执行项目构建，确认 prebuild 自动生成公告 JSON 后，整个构建流程能够正常完成；
• 确认开发环境和生产构建都能正确生成并读取公告数据；
• 检查中文站与英文站的公告入口、页面内容和导航是否符合预期；
• 检查键盘导航、动画降级及减少动态效果的处理；
• 确认生产环境的路由和部署方式能够正确访问新增页面。

需要说明的是，以上属于待验证事项，并不代表这些功能目前一定存在缺陷。

总结

总体而言，我认可这次 PR 的主要设计方向，尤其是单一 Markdown 数据源、自动生成公告数据、首页与归档页联动，以及通过 GitHub PR 实现开源协作的思路。

我建议保留现有的整体架构，优先完善 Fork 来源校验、实际投稿流程引导和公告日期解析排序，再完成构建及页面验证。

这些问题处理完毕并完成必要验证后，我认为这套方案就具备了比较好的合并基础。感谢提交者为公告管理流程和用户体验所做的工作。

[CapableCCat]

感谢继续完善！

不过，我在最新版本中发现一处需要修复的问题：

文件：docs/components/CreateAnnouncement.tsx

当前代码中，submitUrl 的计算逻辑引用了 userForkSyncUrl：

const submitUrl =
  forkState === 'exists'
    ? userForkEditUrl
    : forkState === 'stale'
      ? userForkSyncUrl
      : editUrl;

但我检查了当前文件，发现并没有定义这个变量。

但是前面实际上已经对 userForkHomeUrl 定义了正确的链接：

const userForkHomeUrl = `https://github.com/${user}/website`;

这会导致一个具体问题：当用户的 Fork 缺少 announcements.md、检测状态变为 stale 时，组件渲染会因为引用未定义变量而报错。 这不是单纯的链接失效，而是可能导致整个创建公告页面无法正常显示。

建议直接将 userForkSyncUrl 改为 userForkHomeUrl，让用户进入自己的 Fork 仓库主页，再按页面提示点击 Sync fork。

另外，虽然当前 GitHub Actions 在 Node.js 18 和 20 下均构建成功，但这次问题仍然存在，说明现有构建流程没有捕获这个错误。后续可以考虑增加 TypeScript 类型检查。

辛苦再继续完善一下代码，再次感谢你的贡献！

[CapableCCat]

我对部分细节进行了一些小幅修复和调整，目前整体功能与实现都没有发现其他明显问题。

再次感谢你的贡献和付出！这次新增的公告展示与投稿功能让官网的内容维护更加完善，也很高兴看到项目在大家的共同参与下不断进步。