文档共建指南

使用 Markdown 编写

在对应分类目录中新增 .md 或 .mdx 文件即可。首页与普通文章使用相同的 Starlight 文档框架；纯文字内容可使用 Markdown，需要卡片、步骤、标签页或自定义组件时使用 MDX。两种格式都支持提示栏、数学公式与 Mermaid。

---
title: 我的第一份调试记录
description: 记录问题、环境、步骤和验证结果。
sidebar:
  order: 1
---

## 目标

写清楚这次要验证的行为。

## 操作步骤

1. 记录环境。
2. 执行操作。
3. 核对结果。

按内容选择组件

可以使用任意 Starlight 组件和项目内的 Astro 组件；需要 React、Vue 等框架组件时，先为项目配置对应的 Astro 集成。在 .mdx 文件的 frontmatter 后导入组件，再与 Markdown 正文一起使用。本页的标签页就是一个示例：

普通 Markdown
MDX 与组件

适合笔记、规则条款、表格和参考链接。保存为 .md 即可，不需要组件导入。

## 调试记录

1. 记录环境与接线。
2. 完成实验并保存结果。

:::tip[复现提示]
注明固件版本与关键参数。
:::

保存为 .mdx，即可将组件与 Markdown 混排。例如用 Steps 展示顺序操作：

import { Steps } from '@astrojs/starlight/components';

<Steps>

1. 记录环境与接线。
2. 完成实验并保存结果。

</Steps>

组件示例可参考首页卡片、入门步骤。完整用法见 Starlight 组件文档。

一篇文档回答什么

部分	要回答的问题
目标	读者要解决什么问题？
前提	适用的硬件、软件版本和基础知识是什么？
步骤	如何复现？关键参数为什么这样选？
验证	用什么现象或数据证明完成？
排错	常见失败有哪些？如何定位？
参考	来源、许可证和相关文档在哪里？

数学公式

行内公式使用 $…$ ，独立公式使用单独成行的 $$ 包裹。延续原始规则草稿的 LaTeX 写法：

初始尺寸小于 $350\times350\times350(mm)$。

$$
v = \frac{\Delta x}{\Delta t}
$$

显示效果：初始尺寸小于 $350\times350\times350(mm)$ 。

v = \frac{\Delta x}{\Delta t}

正文、导航、代码与图表标签统一使用无衬线字体栈，数学公式使用 KaTeX 自身的数学字体。

Mermaid 流程图

使用标记为 mermaid 的围栏代码块，直接维护图的源码。

```mermaid
flowchart LR
    A[记录问题] --> B[复现实验]
    B --> C[核对结果]
```

显示效果：

流程图在构建时生成静态 SVG，随 Starlight 深浅主题切换，无需浏览器重新渲染。宽图默认适应正文宽度，可点击“放大查看”后滚动阅读细节；没有 JavaScript 时仍能看到图表。图表语法错误会在构建时提示，请修正后再发布。比赛赛程直接使用原始附件中的 Mermaid 定义。

提示栏

保留 Starlight 的提示栏语法，不需要组件导入：

:::tip[复现提示]
注明固件版本与接线方式。
:::

字体与静态资源

本站不分发字体文件，也不让字体请求阻塞首屏：

正文使用思源黑体 Noto Sans SC，通过 Google Fonts 中国镜像 fonts.googleapis.cn 异步加载，并以 font-display=optional 声明。加载失败、被拦截或超时都不会留白，浏览器直接使用本地回退链（system-ui → PingFang SC / Microsoft YaHei → sans-serif）。
左上角标题（ΣDOCS）使用粗标题字体 Manrope 800，回退到 Archivo Black。标题含希腊字母 Σ，因此只选用带 greek 子集的字体族；字体族由 --sl-font-display 提供，样式在 custom.css 的 .site-title 中。
数学公式使用 KaTeX 的数学字体，按安装版本固定引用 cdnjs。每条公式样式优先使用对应的 KaTeX_Main / KaTeX_Math / KaTeX_Size* 字体，之后才是本地回退字体。CDN 不可达时仍会显示文字，但替代字体的字形度量不同，复杂公式和大括号可能错位；离线环境不能保证数学排版一致。
src/styles/fonts.generated.css 由 scripts/generate-fonts.mjs 在 npm run dev / npm run build 前自动生成，不要手工修改。脚本会校验生成结果中不含任何相对字体路径，因此打包产物不会包含字体文件。

修改字体策略时，请同时调整 scripts/generate-fonts.mjs 中的字体栈与 src/components/Head.astro 中的加载地址，并运行 npm run check:fonts 确认生成结果一致。public/ 与仓库中不得新增 .woff2 / .woff / .ttf 等字体资源。

站点标志与标题尺寸

顶栏是固定高度的，内部元素超高会被直接裁掉，因此标志尺寸受 --sl-nav-height - 2 * --sl-nav-pad-y 约束。custom.css 把该高度上调 0.25rem 并给出 --sl-logo-size（手机 2.25rem / 桌面 2.625rem）。如果需要更大的标志，必须同时上调 --sl-nav-height，否则会被裁切；该变量也会影响固定侧栏与正文的偏移。

发布前检查

核实内容。 区分正式规则、经验建议、示例与待确认项。
检查链接。 使用完整站内路径，如 /zh-cn/competition/。
构建预览。 执行 npm run build；开发预览使用 npm run dev -- --background。
人工复核。 检查手机排版、表格、数学公式、流程图与提示栏。

代码位于 Simba 文档仓库。各分类按目录自动生成，首页内容直接在 src/content/docs/zh-cn/index.mdx 中维护。