| name | cqu-openlib-docs |
| description | Rules for editing the CQU-openlib documentation site (public/doc/**/*.md) — resource entry formats for textbooks and exam papers, custom Markdown syntax (content tabs, admonitions, l- icons), the updated frontmatter field, and the three-file changelog sync. Use when adding or editing any page under public/doc, recording a textbook or exam paper, writing a changelog entry, or touching the Markdown parser under app/utils/remark or app/utils/preprocess. |
CQU-openlib 文档编写
重庆大学资源共享站点。Vite + React + TanStack Router SPA，文档源是 public/doc/**/*.md，包管理 pnpm，默认分支 main。
动手前先读对应的那一份
不确定读哪份就先读 entry-formats.md，站点九成的改动都是资源条目。
五条铁律
一、抄现有写法，不要发明写法。 这个仓库有 4000 多个文档页，几乎任何格式问题都已经有 300 个先例。动手前先 rg 一个同类页面看它怎么写的。你觉得「更合理」的写法一律不要用。
二、updated 只在读者看到的信息真的变了时才动。 格式统一、错别字、图标换名都不算。判定表在 updated-and-changelog.md，照表执行，不要自己推理。
三、写更新日志必须同步改三处文件。 只改当天日志文件、忘了 更新日志/index.md 和首页 index.md，站点上的日期就会对不上。清单在 updated-and-changelog.md。
四、图标必须先在代码里注册。 :l-xxx: 不是直通 lucide 的。没在 app/utils/parser/parserIcon.tsx 的 STATIC_ICONS 里注册过的图标，在页面上会渲染成灰色的字面文本 :l-xxx:。加新图标的完整步骤见 site-structure.md。
五、不要自动 commit / push。 用户要求提交时用普通 git，不要附加任何署名流程。
最常见的任务：收录一本教材
- 查课程号：在
public/doc/academic/专业培养方案/** 里 rg 课程名，那里每门课都标了 :l-book:课程号``。不要自己编，也不要凭课程名猜——书名和课程名一致不代表课程号一样。
- 查书目信息：书名、第一作者、出版方、版次、ISBN13。作者只写第一个。拿不准就搜 ISBN 核实，不要照抄 PDF 文件名（网上流传的文件名经常把主编写错）。
- 写条目：按 entry-formats.md 的模板写。目标页面如果是「暂无数据，欢迎贡献」占位页，整体替换成课程页骨架，不要在占位内容下面追加。
- 改
updated 为当天日期。
- 写更新日志三处。
- 兑现了待办条目：删掉
sundry/待办事项/textbook.md 里那条、该页 updated 也改当天，日志补一行 完成 … legacy#134。
只知道书目、拿不到文件时不要把页面留成空占位：按 entry-formats.md 的「已知教材但没拿到文件」写说明并引用待办序号，让读者看出「知道是哪本，只是没有」。
验证
pnpm test
pnpm typecheck
改文档不需要跑构建，但新增图标后必须跑 pnpm test：app/tests/parser/iconCoverage.test.ts 会扫描全库 :l-xxx:，漏注册直接失败并报出图标名和文件路径。
自查用得上的命令：
rg -n ':l-book-open:' public/doc/course | head
rg -n ':l-quote:' public/doc
rg -n ':l-printer:`[^`]+` ?$' public/doc
