HZNU Math Guide

Appearance

书写格式与风格 ​

为了保证 HZNU Math Guide 的内容质量、可读性和可协作性，所有贡献者都应遵循本页规范。

基本原则 ​

  1. 以 Markdown 原文为中心，而不是以截图、排版效果图或外链文档为中心。
  2. 优先保证清晰、准确、可复查，其次才是表达风格。
  3. 一次提交只解决一类问题，避免把内容修订、格式清洗和结构调整混在同一个 Pull Request 里。
  4. 新增内容应默认面向协作者和后续维护者，而不只是当前作者本人。
  5. 能用文本表达的内容，不要改成图片；能用结构化列表表达的内容，不要写成大段堆叠文字。

Markdown 书写规范 ​

标题 ​

  1. 使用 ATX 标题，即 #、##、###，不要使用 Setext 标题。
  2. 每个页面只能有一个一级标题，也就是一个 # 标题。
  3. 标题要直接说明内容，不写「一些想法」「随便记记」这类模糊标题。
  4. 标题末尾不加句号、逗号、冒号等点号。
  5. 标题层级不要跳级。## 下直接接 #### 是不允许的。

段落 ​

  1. 一个段落只表达一个中心意思。
  2. 段落不要过长。能拆就拆，优先控制在 3 至 6 行内。
  3. 段落之间空一行。
  4. 段首不要缩进，不要手动插入多个空格来做视觉排版。
  5. 尽量使用短句、简单句和肯定句。

列表 ​

  1. 无序列表统一使用 -。
  2. 有序列表统一使用 1. 这种 Markdown 自动编号写法。
  3. 同一层级的列表项应保持句式一致。
  4. 列表项如果只是短语，末尾一般不加句号；如果是完整句子，整个列表应保持一致的句末标点风格。
  5. 不要为了「好看」连续嵌套过深；超过两层通常说明结构需要重写。

代码与数学公式 ​

  1. 行内代码使用反引号包裹，例如 Python、git status、docs/index.md。
  2. 多行代码必须使用 fenced code block，并尽量标注语言类型。
md
```python
print("Hello, world!")
```
  1. 数学公式统一使用 LaTeX 语法。
  2. 行内公式使用 $...$，独立公式使用 $$...$$。
  3. 公式前后要有解释，不能只丢公式不说明符号含义或结论用途。
  4. 能直接输入 LaTeX 的内容，不要上传公式截图替代。

表格、引用与分隔 ​

  1. 只有在确实需要对比信息时才使用表格，不要把普通段落硬写成表格。
  2. 引用内容使用 >。
  3. 引用第三方内容时，必须注明来源。
  4. 不要滥用分隔线。只有在章节切换明确需要时才使用 ---。

中文技术写作规范 ​

空格 ​

  1. 中文与英文之间保留一个半角空格。
  2. 中文与阿拉伯数字之间，可以加空格，也可以不加；但同一篇文档必须统一。
  3. 英文或数字与中文标点之间不加空格。
  4. 数字与未翻译的英文单位之间保留空格，例如 16 GB、2 min。

标点 ​

  1. 中文正文使用全角中文标点。
  2. 整句英文使用半角英文标点。
  3. 中文内容中的引号统一使用直角引号「」，不要使用弯引号 “”。如果外层已经使用「」，内层改用『』；需要更深层时继续交替使用。
  4. 上一条默认适用于中文正文、标题、说明文字和强调语。只有引用完整句子，或整句英文、英文术语、代码、配置项时，才保留原有英文引号。
  5. 中文并列内容优先使用 、，最后一项前优先使用「和」连接，使句子更自然。
  6. 不要使用 。。。、... 代替中文省略号 ⋯⋯。
  7. 不要连续使用多个感叹号或问号。

语气与措辞 ​

对于协作编写，不可避免出现文章的行文风格殊异的问题。但是必须要保证如下几点：

  1. 要保证语言和内容的可读性。
  2. 要保证有自己的理解和想法。
  3. 要保证书写的目的是为了让别人能够理解看懂，而不是来卖弄自己的知识。
  4. 要保证自己书写的内容具有专业性和严谨性。

专有名词 ​

  1. 专有名词遵循官方写法，例如 GitHub、Markdown、LaTeX、NumPy、PyTorch。
  2. 第一次出现缩写时，必要时给出中文全称或英文全称。
  3. 不要随意创造缩写，除非该缩写在全文都会重复使用且对读者有帮助。

面向 GitHub 的协作要求 ​

文件与目录 ​

  1. 在现有目录结构下新增文档，不要随意新建平行体系。
  2. 页面文件统一使用 .md。
  3. 文件名应准确反映主题，避免使用「笔记」「总结」「资料」这类泛化命名。
  4. 不要因为局部重构就批量改名或移动大量文件，除非有明确维护收益。
  5. 图片、截图等静态资源统一放在 docs/public/image/ 或其明确子目录下，不要散落在各章节目录。

页面功能开关 ​

页面可以通过 frontmatter 控制局部功能，避免把所有页面都做成同一种样子。

yaml
---
comment: false
showCopyLinks: true
showContributionActions: false
---
  • comment: false 关闭评论区，适合首页、公告页或不希望讨论的页面。
  • showCopyLinks: true 为当前页的外部链接显示复制按钮，适合资源导航型页面。
  • showContributionActions: false 隐藏页脚的「反馈问题 / 编辑此页 / 补充资源」入口，适合不希望出现协作入口的页面。

链接与资源 ​

  1. 仓库内部链接优先使用相对路径或站点内路径，保证本地预览和 GitHub 查看都可用。
  2. 外部链接应指向稳定来源，优先官方文档、论文原文、课程主页或作者主页。
  3. 引用外部图片、表格、结论和定义时，应给出来源。
  4. 失效链接、重定向链过长的链接、营销页链接，应尽量替换。

提交与 Pull Request ​

  1. 通过 GitHub 的分支协作或 Fork + Pull Request 流程提交修改。
  2. 一个 Pull Request 只做一件事，例如：
    • 修正文档内容
    • 统一格式
    • 补充参考资料
    • 调整目录结构
  3. 不要把大规模格式化与实质性内容修改混在同一个提交中，否则会显著增加 review 成本。
  4. Commit message 应直接描述改动，例如：
    • docs: fix typo in 概率论与数理统计
    • docs: add references for 微积分
    • docs: rewrite 书写格式与风格
  5. Pull Request 描述至少应说明三件事：
    • 改了什么
    • 为什么改
    • 是否影响现有链接、目录或页面结构

审阅友好 ​

  1. 改动前先阅读上下文，不要只改当前看到的一行。
  2. 修改术语、标题、链接或路径时，要检查全文是否还有相关引用。
  3. 批量替换前，先确认不会误伤代码块、公式、文件名或专有名词。
  4. 对于有争议的写法，优先在 PR 描述中说明判断依据，而不是让 reviewer 猜测意图。

自检清单 ​

提交前，至少检查以下内容：

  • 标题层级是否正确。
  • 是否只有一个一级标题。
  • 段落是否过长。
  • 中英文、数字和标点的风格是否统一。
  • 代码块和公式是否能正常阅读。
  • 图片是否放在正确目录，命名是否清晰。
  • 内部链接和外部链接是否有效。
  • 引用和转载内容是否标注来源。
  • 本次改动是否足够聚焦，是否适合单独审阅。