优化 Mermaid 渲染

README.md

@@ -6,6 +6,7 @@
 
 ```sh
 npm install
+npm run setup:mermaid
 npm run dev -- --background
 npm run astro -- dev status
 npm run astro -- dev logs
@@ -14,8 +15,16 @@ npm run astro -- dev stop
 
 中文首页：`http://localhost:4321/zh-cn/`，英文首页：`/en/`。根路径跳转到中文首页。
 
+Mermaid 在构建时通过 Playwright Chromium 渲染，首次安装及 Playwright 升级后需执行 `npm run setup:mermaid`。Linux CI 使用 `npx playwright install --with-deps chromium`，并安装中文无衬线字体（如 Debian/Ubuntu 的 `fonts-noto-cjk`）。构建环境须安装开发依赖；发布时只需上传 `dist/`，无需 Chromium 或 Node.js 服务。
+
 `npm run build` 生成 `dist/`，`npm run preview` 验证生产版本和 Pagefind 搜索。正式部署时，在 `astro.config.mjs` 设置实际 `site` 域名，以生成 sitemap。
 
+构建会自动生成字体 CSS，并执行 `check:fonts` 和 `check:site`：检查字体引用、站内导航链接与锚点、页面直接引用的资源和公式错误，不检查外站可达性或 canonical/hreflang 等 SEO 元数据。`check:site` 中的站点域名应与 `astro.config.mjs` 保持一致。生成文件不提交；`scripts/` 中的脚本需要随项目一起提交。
+
+`check:site` 同时检查 Mermaid 深浅两套静态 SVG 和页面 ID 冲突。修改图表处理逻辑后，运行 `npm run check:mermaid`，验证多图、重复时序图的箭头引用和语法错误定位。
+
+当前仅精确过滤 Astro 7.3 生成的 `use astro:head-inject` 指令警告，其他构建警告保留。Mermaid 渲染器仅用于构建，不再进入浏览器端资源包。
+
 ## 编写与维护
 
 文档支持 `.md` 与 `.mdx`：普通文章可以直接使用 Markdown；需要组件时使用 MDX，在 frontmatter 后导入 Starlight 或项目内的 Astro 组件。可按内容使用卡片、步骤、标签页等任意组件，使用其他前端框架的组件前需安装对应的 Astro 集成。提示信息也可直接使用 `:::note` / `:::tip` / `:::caution` / `:::danger` 语法。
@@ -34,17 +43,20 @@ npm run astro -- dev stop
 
 ## 公式与 Mermaid
 
-- 行内公式使用 `$…$`，独立公式使用 `$$…$$`（分行包裹）。`remark-math` 和 `rehype-katex` 在构建时渲染，KaTeX 的样式和字体随站点打包。
+- 行内公式使用 `$…$`，独立公式使用 `$$…$$`（分行包裹）。`remark-math` 和 `rehype-katex` 在构建时渲染；字体脚本生成本地样式，字体文件按安装的 KaTeX 版本从 cdnjs 加载，不打包到站点。CDN 不可达时，本地回退字体不能保证复杂公式排版一致。
 - 以上公式写法和 Mermaid 均支持 `.md` 与 `.mdx`，不需要逐页导入组件。
-- 图表使用标准的 Mermaid 围栏代码块。`src/plugins/remark-mermaid.mjs` 保留源码，`src/scripts/mermaid.ts` 在有图表的页面按需加载 Mermaid 并渲染 SVG，随深浅主题切换重新绘制。宽图默认适应宽度，点击“放大查看”后可滚动阅读，无 JavaScript 或图表错误时仍可阅读源码。
+- 图表使用标准的 Mermaid 围栏代码块。`src/plugins/remark-mermaid.mjs` 在代码高亮前识别图表，`src/plugins/rehype-mermaid.mjs` 调用 `rehype-mermaid` 的 `inline-svg` 策略，在构建时生成深浅两套 SVG 并嵌入 HTML。CSS 跟随 Starlight 的 `data-theme` 切换，打印使用浅色版，无需重新渲染；没有 JavaScript 也能看到图表。`src/scripts/mermaid.ts` 仅提供放大和滚动查看功能。图表语法错误会导致构建失败，并报告源文件位置。
+- 图表沿用插件依赖的 Mermaid 版本（当前为 11.x），不再单独安装浏览器端 Mermaid 12。渲染使用本地无衬线字体，构建与阅读设备的字体差异仍可能影响字形；复杂中文图表应在 CI 构建后检查。内联 SVG 保留文本与矢量清晰度，但深浅两份会增加对应页面的 HTML 体积。
+- 主题配置作为插件选项传入，修改配色会自动使 Astro 内容缓存失效。若修改渲染插件逻辑或升级渲染依赖后仍看到旧图，运行 `npm run astro -- sync --force` 后重新构建。
+- MDX 集成保留静态优化，但将 `style` 排除，避免 SVG 内部样式被输出为无效的 `set:html` 属性。该集成需排在 Starlight 之后，以保留代码高亮的处理顺序。
 - 除数学公式外，正文、导航、代码块、表单和图表文字均为无衬线字体。KaTeX 保留数学字体。
-- `Head.astro` 仅增加图表渲染脚本，文档框架沿用 Starlight 默认实现。页眉 Logo 通过 Starlight 配置加载；搜索、导航、主题和语言切换保留原有行为。
+- `Head.astro` 增加图表放大脚本和可选的远程正文字体，文档框架沿用 Starlight 默认实现。页眉 Logo 通过 Starlight 配置随主题切换：浅色使用 `public/simba/logo-light.svg`（深灰主体），深色使用原版 `public/simba/logo.svg`（白色主体），两版保留红色标记；搜索、导航、主题和语言切换保留原有行为。
 
 写法和预览见 `src/content/docs/zh-cn/guides/contributing.mdx`。
 
 ## 校内赛规则
 
-手册按概览、赛前考核、开源审查、对抗赛、制作规范、裁判系统、待确认事项拆为七章。比赛流程使用原始附件的 Mermaid 源码，不另写 Astro 流程组件；数学表达使用原有美元符号公式语法。
+手册分为概览、赛前准备（含开源审查）、对抗赛、制作规范、裁判系统五章。比赛流程使用 Mermaid 源码；数学表达使用美元符号公式语法。
 
 - [Simba 主站](https://simba-robotics.com)
 - [文档仓库](https://git.simba-robotics.com/PRAM/simba_docs)