跳转至

贡献指南

这是个人 wiki，主要由 @trilliverse 维护。但如果你发现错误、有补充材料或建议，欢迎贡献。

报告问题

发现错误（公式错、概念不准、链接失效、错别字均算）的最简单方式：

  1. 打开对应页面，点页面右上角 ✏️ 图标直接在 GitHub 上编辑并发 PR；或
  2. 在 GitHub Issues 描述问题。

本地开发

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# 一次性：装 uv（若未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 同步依赖（生成 .venv，按 uv.lock 还原版本）
uv sync

# 启动本地预览（默认 http://localhost:9876/scut-bdma-wiki/，文件变化自动刷新）
./run.sh
# 或自定义端口：./run.sh 9999
# 或：uv run mkdocs serve -a 0.0.0.0:9876

# 严格构建（任何 nav 引用了不存在的文件 / 链接失效都会失败）
uv run mkdocs build --strict

关于启动时的 MkDocs 2.0 横幅

mkdocs-material 9.6+ 会在启动时打印一段红色的 MkDocs 2.0 社区议题广告。run.sh 和 CI 都已通过 NO_MKDOCS_2_WARNING=true 关闭它。如果直接运行 uv run mkdocs build --strict 看到横幅，无视即可，或在当前 shell 执行 export NO_MKDOCS_2_WARNING=true。

本地默认不抓 GitHub 贡献者列表

git-committers 插件默认在本地 关闭（enabled: !ENV [ENABLE_GIT_COMMITTERS, false]），所以本地 ./run.sh 和 mkdocs build 不会调 GitHub API、不会触发 advisory warning。贡献者那一行只在线上站点显示，CI 中 ENABLE_GIT_COMMITTERS=true + secrets.GITHUB_TOKEN 已自动配好。

若你本地想看贡献者效果（需要 GitHub PAT，赋 public_repo scope 即可）：

1
2
3
export ENABLE_GIT_COMMITTERS=true
export MKDOCS_GIT_COMMITTERS_APIKEY=ghp_xxx...
uv run mkdocs build --strict   # 或 ./run.sh 看实时预览

写作约定

  • 每门课一个目录，目录名用小写 + 短横线（如 game-theory、data-mining）。
  • 每个章节一个 Markdown 文件，文件名 ch01.md、ch02.md…；章节内 H1 标题用 # 第 N 章 · 标题。
  • 公式：行内 $x$，展示式 $$ \sum_{i=1}^n x_i $$，使用 MathJax 3 默认语法。
  • 代码块指定语言，例如 ```python，以便高亮。
  • 引用与外链用相对路径，避免硬编码站点 URL。
  • 图片放在 docs/assets/<course>/ 下，引用时用相对路径。

加新课程

  1. 判断课程归属的学科板块：math/ / cs/ / opt/ / ds/ / bigdata/ / econ/。归属不清时按"边界判定原则"（见下）就近选一边，后续可迁。
  2. 在 docs/<板块>/<course-slug>/ 下创建 index.md（课程总览）和章节文件 ch01.md…chN.md。
  3. 在 mkdocs.yml 的 nav: 对应板块下追加该课程子树。
  4. 同步更新 docs/about/courses.md 的"当前上线进度"和对应 docs/<板块>/index.md 的状态列。
  5. 本地 uv run mkdocs build --strict 验证 nav 配置正确（注意需要设 MKDOCS_GIT_COMMITTERS_APIKEY 或不开 --strict）。
  6. 提交并 push，去 GitHub Actions 手动触发 Deploy Wiki workflow（本仓库目前是手动部署）。

边界判定原则（课程归哪个板块）

跨板块嫌疑较大时按"核心目标"判定：

课程核心目标 归
找最优解 / 决策 / 均衡 优化决策
从数据归纳模型 / 洞察 数据科学
基础设施 / 平台 / 治理 大数据
解释经济 / 商业现象 经管
数学本身（不应用） 数学
通用 CS 基本功 计算机科学