🗺️ 贡献者指南 · 笔记规范
本文档面向希望向本项目贡献笔记的贡献者。 请遵循以下规范，确保知识库的一致性和可维护性。
目录结构规范
Notes/
├── index.md ← 知识库首页（唯一保留的 index 文件）
├── 知识图谱构建方法论.md ← 本文档
│
├── <学科英文名>/ ← 如 Algorithms、CSAPP
│ ├── <学科英文名>.md ← 学科根节点 Hub（入口）
│ ├── 01-<章节名>/ ← 数字前缀 + 中文名
│ │ ├── <章节中文名>.md ← 章节导航 Hub
│ │ ├── <X.Y> <知识点>.md ← 原子笔记，带编号
│ │ └── ...
│ ├── 02-<章节名>/
│ │ └── ...
│ ├── images/ ← 图片资源（可选）
│ └── notes/ ← 原始长篇笔记（不上传至网站）
│
├── Others/ ← 其他辅助文档
└── README.md
关键说明：仓库中不存在 index.md（除根目录外）。所有导航由 Hub 文件（<名称>.md）承担，在 Quartz 网站和 Obsidian 本地使用同一套文件。
文件命名规则
| 要素 | 规则 | 示例 |
|---|---|---|
| 学科根目录 | 英文名 | Algorithms/、CSAPP/ |
| 章节目录 | <2位数字>-<中文名> | 01-算法分析 |
| 学科根节点 | <学科名>.md | Algorithms.md、CSAPP.md |
| 章节导航 | <章节中文名>.md | 算法分析.md、计算机系统漫游.md |
| 原子笔记 | <X.Y> <名称>.md | 1.1 复杂度分析.md |
| 原始笔记 | 放在学科 notes/ 目录 | CSAPP/notes/1.md |
⚠️ 原子笔记必须包含
X.Y数字前缀，否则无法在 Explorer 中正确排序。
原子笔记内容要求
每篇原子笔记应遵循以下格式：
---
created: <YYYY-MM-DD>
tags: [<章节标签>, <学科标签>, <知识标签>]
---
# <知识点名>
用一两句话概述该知识点的核心内容。
## <子标题>
- 要点 1
- 要点 2
## 相关概念
- 可选的跨章节/跨学科链接（使用 markdown 链接，不要用 wiki-link）要点：
- 一个笔记只讲一个概念，粒度要均匀，避免大而全
- 公式使用 LaTeX 语法（
$$或$），Quartz 会自动渲染 - 代码块标注语言类型
- 图片放在章节目录下的
images/或学科公共images/ - 原子笔记不要有出链（入链由章节 Hub 提供），仅可通过 markdown 链接进行跨章节引用
章节导航 Hub 文件
每个章节目录中需要一个 Hub 文件：
位置：<章节目录>/<章节中文名>.md
---
created: <YYYY-MM-DD>
tags: [<学科标签>, moc, <章节标签>]
---
# 第<N>章 <章节中文名>
> 一句话概述本章内容
## 本章知识点
- [[<学科>/<目录>/<X.Y> <知识点>|<X.Y> <知识点>]]
- [[<学科>/<目录>/<X.Y> <知识点>|<X.Y> <知识点>]]
- ...
---
[[../<学科>|← 返回 <学科> 总览]]规范要点：
- 知识点列表必须按 X.Y 编号升序排列
- 不要添加
[[../<学科>|<章节名>]]自引用作为第一个知识点（直接从知识点列表开始） - 返回链接指向学科 Hub（
[[../<学科英文名>]]），而非../index - Hub 中列出的知识点链接使用完整显式路径，包含学科前缀
学科根节点 Hub 文件
位置：<学科根目录>/<学科名>.md
文件命名：学科 Hub 文件名不加数字前缀，与学科目录名一致（如 CSAPP.md、Algorithms.md）。
---
created: <YYYY-MM-DD>
tags: [<学科标签>, map-of-content, root]
---
# <学科名>
> 一句话描述该学科
---
## 章节导航
### [[<学科>/<章节目录>/<章节Hub>|第<N>章 <章节名>]]
<章节核心主题概述>
---
[[../index|← 返回 📚 笔记主页]]规范要点：
- H1 标题直接用学科英文名（如
# CSAPP），不加「知识图谱」后缀 - 章节链接使用
###标题链接 + 描述行格式，不再使用表格 - 链接必须包含学科前缀，如
[[CSAPP/01-计算机系统漫游/计算机系统漫游]] - 返回链接指向根
index.md（[[../index|← 返回 📚 笔记主页]]）
链接规范（重要）
本仓库使用 Hub-only 文件体系，不依赖 index.md：
| 位置 | 链接目标 | 示例 |
|---|---|---|
| 根 index.md → 学科 | 学科 Hub | [[CSAPP/CSAPP|CSAPP]] |
| 学科 Hub → 章节 | 章节 Hub | [[Algorithms/01-算法分析/算法分析|第1章 算法分析]] |
| 学科 Hub → 根 | 根 index.md | [[../index|← 返回 📚 笔记主页]] |
| 章节 Hub → 原子笔记 | 原子笔记文件 | [[CSAPP/01-计算机系统漫游/1.1 抽象层次结构|1.1 抽象层次结构]] |
| 章节 Hub → 学科 | 学科 Hub | [[../CSAPP|← 返回 CSAPP 总览]] |
标签体系
| 标签类型 | 格式 | 示例 |
|---|---|---|
| 学科标签 | 小写英文 | csapp、algorithms |
| 章节标签 | <学科>-ch<编号> | csapp-ch1、algo-ch3 |
| 知识标签 | 中文 | 复杂度、浮点数 |
| 页面类型 | map-of-content / moc / root | 根节点用 root |
统一格式检查清单
学科根节点 Hub（<学科名>.md）
# <学科英文名> ← 英文名，无「知识图谱」后缀
### [[<学科>/<章节目录>/<章节Hub>|第N章 <章节名>]] ← 含学科前缀
<描述>
[[../index|← 返回 📚 笔记主页]] ← 底部回链- H1 标题为学科英文名（
# CSAPP），无中文「知识图谱」 - 章节链接使用
###标题链接格式，含学科前缀 - 底部有
[[../index|← 返回 📚 笔记主页]]回链 - 无表格格式
章节 Hub（<章节中文名>.md）
# 第N章 <章节中文名>
## 本章知识点
- [[<学科>/<章节目录>/<X.Y> <知识点>|<X.Y> <知识点>]]
---
[[../<学科>|← 返回 <学科英文名> 总览]] ← 底部回链- 文件名不含数字前缀（如
计算机系统漫游.md，非01-计算机系统漫游.md） - 没有
[[../<学科>|<章节名>]]自引用行作为第一个知识点 - 知识点列表按 X.Y 升序排列
- 每条链接包含完整学科前缀（
CSAPP/、Algorithms/） - 每条链接包含
|X.Y name显示名（如|1.1 抽象层次结构） - 底部有
[[../<学科>|← 返回 <学科> 总览]]回链 - 回链不是用自引用行代替的
原子笔记（<X.Y> <名称>.md）
- 文件名包含
X.Y数字前缀 - 有 Front Matter（
created、tags） - 没有出链 wiki-link（入链由章节 Hub 提供）
- 上下知识点导航用 wiki-link，带学科前缀和
|X.Y显示名
链接格式总则
[[CSAPP/CSAPP|CSAPP]] ✅ 学科 Hub 显示名
[[CSAPP/01-计算机系统漫游/计算机系统漫游|第1章 计算机系统漫游]] ✅ 学科 Hub→章节 Hub
[[CSAPP/01-计算机系统漫游/1.1 抽象层次结构|1.1 抽象层次结构]] ✅ 章节 Hub→原子笔记
[[../CSAPP|← 返回 CSAPP 总览]] ✅ 回链
[[../index|← 返回 📚 笔记主页]] ✅ 学科 Hub→主页
[[CSAPP/01-计算机系统漫游/1.1 抽象层次结构]] ❌ 缺少 | 显示名
[[../CSAPP|计算机系统漫游]] ❌ 章节 Hub 中不允许自引用
[[01-计算机系统漫游/1.1 抽象层次结构]] ❌ 缺少学科前缀提交 PR 流程
- Fork 本仓库
- 按照上述规范创建或修改笔记
- 对照检查清单逐项验证
- 提交 Pull Request，说明改动内容
注意事项
- 不要上传 PDF 文件（已全局
.gitignore） - 不要在原子笔记中使用出链 wiki-link（会破坏图谱结构），跨章节引用请用 markdown 链接。同一章节内的上下知识点导航可用 wiki-link，须带学科前缀和
|X.Y显示名 notes/目录的原始笔记仅供 Git 备份，不会出现在 Quartz 网站中- 除根
index.md外，不要创建其他index.md文件（CI 会自动删除） - 章节导航中知识点列表必须按 X.Y 编号升序排列
- 所有 wiki-link 使用完整显式路径，包含学科前缀和
|X.Y显示名，不要使用裸链接或模糊匹配