第二版更改

README.md

@@ -1,6 +1,6 @@
 # ΣDOCS · Simba Robotics
 
-黑龙江大学 Simba 战队的文档站，基于 Astro 7 与 Starlight。首页复用 Simba 主站的黑红视觉、机器人实拍、Logo 和小组图标；文章页保留 Starlight 的侧栏、页内目录、搜索、浅色 / 深色主题与语言切换。
+黑龙江大学 Simba 战队的文档站，基于 Astro 7 与 Starlight。首页与文章统一使用 Starlight 默认文档框架，保留侧栏、页内目录、搜索、代码复制、深浅主题与语言切换。
 
 ## 本地运行
 
@@ -12,46 +12,47 @@ npm run astro -- dev logs
 npm run astro -- dev stop
 ```
 
-中文首页：`http://localhost:4321/zh-cn/`，英文首页：`/en/`，根路径跳转到中文首页。
+中文首页：`http://localhost:4321/zh-cn/`，英文首页：`/en/`。根路径跳转到中文首页。
 
-生产构建使用 `npm run build`，产物在 `dist/`。`npm run preview` 可验证生产版本与 Pagefind 搜索；开发模式中的搜索由 Starlight 显示开发提示。正式部署时，在 `astro.config.mjs` 设置实际 `site` 域名，以生成 sitemap。
+`npm run build` 生成 `dist/`，`npm run preview` 验证生产版本和 Pagefind 搜索。正式部署时，在 `astro.config.mjs` 设置实际 `site` 域名，以生成 sitemap。
 
-## 从哪里修改
+## 编写与维护
+
+文档支持 `.md` 与 `.mdx`：普通文章可以直接使用 Markdown；需要组件时使用 MDX，在 frontmatter 后导入 Starlight 或项目内的 Astro 组件。可按内容使用卡片、步骤、标签页等任意组件，使用其他前端框架的组件前需安装对应的 Astro 集成。提示信息也可直接使用 `:::note` / `:::tip` / `:::caution` / `:::danger` 语法。
 
 | 内容 | 文件 / 目录 |
 | --- | --- |
-| 首页布局与中英文文案 | `src/components/Home.astro` |
-| 首页卡片、描述和链接 | `src/data/home.ts` |
-| 首页样式 | `src/styles/home.css` |
-| 文档主题与品牌 | `src/styles/custom.css`、`src/components/SiteTitle.astro` |
-| 分类和顺序 | `astro.config.mjs`、页面 frontmatter 中的 `sidebar.order` |
+| 中文 / 英文首页 | `src/content/docs/zh-cn/index.mdx`、`src/content/docs/en/index.mdx` |
+| 分类和顺序 | `astro.config.mjs`、页面 frontmatter 的 `sidebar.order` |
+| 全局字体、红色强调与深灰背景 | `src/styles/custom.css` |
 | 入门与写作示例 | `src/content/docs/zh-cn/guides/` |
 | 技术方向 | `src/content/docs/zh-cn/{mest,elct,vsag,pram}/` |
 | 校内赛规则 | `src/content/docs/zh-cn/competition/` |
 | 原始规则附件 | `public/downloads/rmic-2026-original-draft.md` |
 
-新增 `.md` 或 `.mdx` 页面后，侧栏按目录自动生成。技术示例的页首有“示例内容”提示，替换为经过确认的内容后再调整该提示。原有视觉组导论保留，未改写。
+各分类按目录自动生成。技术示例在页首标注，替换为经过确认的内容后再调整提示。原有视觉组导论正文保留。英文未翻译文章使用 Starlight 默认语言回退。
 
-英文首页已提供，未翻译文章使用 Starlight 默认语言回退并显示提示。首页入口直达现有中文文章，避免空页面。
+## 公式与 Mermaid
+
+- 行内公式使用 `$…$`，独立公式使用 `$$…$$`（分行包裹）。`remark-math` 和 `rehype-katex` 在构建时渲染，KaTeX 的样式和字体随站点打包。
+- 以上公式写法和 Mermaid 均支持 `.md` 与 `.mdx`，不需要逐页导入组件。
+- 图表使用标准的 Mermaid 围栏代码块。`src/plugins/remark-mermaid.mjs` 保留源码，`src/scripts/mermaid.ts` 在有图表的页面按需加载 Mermaid 并渲染 SVG，随深浅主题切换重新绘制。宽图默认适应宽度，点击“放大查看”后可滚动阅读，无 JavaScript 或图表错误时仍可阅读源码。
+- 除数学公式外，正文、导航、代码块、表单和图表文字均为无衬线字体。KaTeX 保留数学字体。
+- `Head.astro` 仅增加图表渲染脚本，文档框架沿用 Starlight 默认实现。页眉 Logo 通过 Starlight 配置加载；搜索、导航、主题和语言切换保留原有行为。
+
+写法和预览见 `src/content/docs/zh-cn/guides/contributing.mdx`。
 
 ## 校内赛规则
 
-规则被整理为概览、赛前考核、开源审查、对抗赛、制作规范、裁判系统、待确认事项七章。使用 Starlight 提示栏、步骤、卡片、标签页、表格和自适应赛程示意。没有额外引入 Mermaid 客户端依赖；原始 Mermaid 源码保留在下载附件，网页以阶段示意与完整晋级关系表展示同一赛程。
+手册按概览、赛前考核、开源审查、对抗赛、制作规范、裁判系统、待确认事项拆为七章。比赛流程使用原始附件的 Mermaid 源码，不另写 Astro 流程组件；数学表达使用原有美元符号公式语法。
 
-`pending.md` 记录原稿缺失或有歧义的条款。正式发布前，应补齐报名入口、场地信息、同分规则、尺寸孔位图等，并同步各章节。所有页面当前标记为规则预览版；原始附件保持不变。
+`pending.md` 记录原稿缺失或有歧义的条款。正式发布前应补齐报名入口、场地信息、同分规则、尺寸孔位图等，并同步各章节。原始下载附件保持不变。
 
-## 主站素材
+## 主站与仓库
 
-素材于 2026-09-23 从 `https://simba-robotics.com` 复用并保存到 `public/simba/`，页面加载不依赖主站在线。素材属于战队原有资产，不因本次复用改变授权。
+- [Simba 主站](https://simba-robotics.com)
+- [文档仓库](https://git.simba-robotics.com/PRAM/simba_docs)
 
-| 本地文件 | 主站来源路径 | 用途 |
-| --- | --- | --- |
-| `logo.svg` | `/logo.svg` | 品牌图标、favicon |
-| `logo_with_char.webp` | `/logo_with_char.webp` | 页脚 Logo |
-| `header.webp` | `/header.webp` | 首页机器人背景 |
-| `mest.svg` | `/icons/mest.svg` | 机械架构入口 |
-| `elct.svg` | `/icons/elct.svg` | 电传测控入口 |
-| `vsag.svg` | `/icons/vsag.svg` | 视觉算法入口 |
-| `pram.svg` | `/icons/pram.svg` | 宣传筹划入口 |
+`public/simba/` 中的 Logo、图片与小组图标由主站复用。Logo 用于页眉与 favicon；此前用于展示首页的素材保留，供后续文章使用。来源为主站同名路径（小组图标来自 `/icons/`），下载日期 2026-09-23，授权不因复用而改变。
 
 参考：[Astro 文档](https://docs.astro.build)、[Starlight 文档](https://starlight.astro.build)。