3.6 KiB
ΣDOCS · Simba Robotics
黑龙江大学 Simba 战队的文档站，基于 Astro 7 与 Starlight。首页与文章统一使用 Starlight 默认文档框架，保留侧栏、页内目录、搜索、代码复制、深浅主题与语言切换。
本地运行
npm install
npm run dev -- --background
npm run astro -- dev status
npm run astro -- dev logs
npm run astro -- dev stop
中文首页：http://localhost:4321/zh-cn/，英文首页：/en/。根路径跳转到中文首页。
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/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 |
各分类按目录自动生成。技术示例在页首标注，替换为经过确认的内容后再调整提示。原有视觉组导论正文保留。英文未翻译文章使用 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。
校内赛规则
手册按概览、赛前考核、开源审查、对抗赛、制作规范、裁判系统、待确认事项拆为七章。比赛流程使用原始附件的 Mermaid 源码，不另写 Astro 流程组件；数学表达使用原有美元符号公式语法。
public/simba/ 中的 Logo、图片与小组图标由主站复用。Logo 用于页眉与 favicon；此前用于展示首页的素材保留，供后续文章使用。来源为主站同名路径（小组图标来自 /icons/），下载日期 2026-09-23，授权不因复用而改变。
参考：Astro 文档、Starlight 文档。