---
title: 关于本笔记库
aliases:
  - 写作规范
  - 使用说明
tags:
  - 元/说明
created: 2026-10-11
updated: 2026-10-11
level: 入门
prerequisites: []
sources: []
---

# 关于本笔记库

> [!abstract] 这是什么
> 一套面向**计算机科学全方向**的系统性中文学习笔记，覆盖计算机基础、编程语言、前端、后端、工具与工程化五个方向，共 60 余篇笔记。全部为 Markdown，专为 [Obsidian](https://obsidian.md) 设计。

## 怎么打开

1. 安装 Obsidian（免费）。
2. 选择「打开文件夹作为仓库（Open folder as vault）」，选中本笔记库的根目录 `CS-Notes`。
3. 从 [[00-索引]] 开始读，或直接看 [[学习路线图]] 决定顺序。

> [!tip] 建议开启的设置
> - 设置 → 核心插件 → 开启 **关系图谱（Graph view）**，可以看到双链织成的知识网络
> - 设置 → 外观 → 开启 **阅读视图** 以获得最佳的 Callout 与公式渲染效果
> - 公式使用 LaTeX 语法，Obsidian 内置 MathJax 渲染，无需额外插件

## 目录结构

```
CS-Notes/
├── 00-索引.md              ← 总导航，从这里进入
├── 关于本笔记库.md          ← 本文件：使用说明 + 写作规范
├── 学习路线图.md            ← 按阶段的学习顺序建议
├── 常见问题FAQ.md           ← 跨方向的通用问题
├── 01-计算机基础/           ← 组成原理、操作系统、网络、数据结构、算法、数据库
├── 02-编程语言/             ← Python、C#、JavaScript 及语言对比
├── 03-前端/                 ← HTML/CSS/TS/框架/构建工具/浏览器原理
├── 04-后端/                 ← API 设计、三大后端框架、数据库、认证、部署
├── 05-工具与工程化/         ← Git、命令行、包管理、测试、协作、CI/CD
└── 99-模板/                 ← 笔记模板
```

## 写作规范（维护本笔记库时请遵守）

这一节是本库的**风格契约**。新增笔记时保持一致，笔记之间才能互相引用而不混乱。

### 1. 文件命名

- 文件名即笔记标题，**不使用空格**，用 `-` 连接，例如 `数据结构-树与堆.md`
- 避免 `[ ] # ^ | /` 等字符，它们在 Obsidian 双链中需要转义
- 分节笔记用统一前缀编号：`Python-01-环境与基础语法.md`
- 编号一旦发布不再改动，插入新笔记时用 `-补充` 后缀而不是重排编号（重排会让所有双链失效）

### 2. YAML frontmatter

每篇笔记开头必须有 frontmatter，**键齐全**：

```yaml
---
title: 笔记标题          # 与文件名保持一致
aliases:                 # 别名，方便用不同关键词检索
  - 英文名
tags:                    # 用 / 形成嵌套标签
  - 计算机基础/操作系统
  - 类型/教程
created: 2026-10-11
updated: 2026-10-11
level: 入门              # 入门 | 进阶 | 高级
prerequisites:           # 前置笔记的双链，没有就留空数组
  - "[[操作系统]]"
sources:                 # 关键来源 URL，至少一个
  - https://example.com
---
```

标签分两个维度：

- **类型**（每篇必有一个）：`类型/教程`（教学笔记）、`类型/速查`（速查表）、`类型/例题`（题目集）
- **方向/主题领域**（技术笔记必有）：按**主题领域**划分，**不按难度划分**——难度由 `level` 字段承担。当前使用的标签值：

| 方向 | 标签值 |
|---|---|
| 计算机基础 | `计算机基础/组成原理`、`计算机基础/操作系统`、`计算机基础/计算机网络`、`计算机基础/数据结构`、`计算机基础/算法`、`计算机基础/数据库` |
| 编程语言 | `编程语言/Python`、`编程语言/CSharp`、`编程语言/JavaScript`、`编程语言/综合` |
| 前端 | `前端/HTML`、`前端/CSS`、`前端/浏览器`、`前端/TypeScript`、`前端/Vue`、`前端/React`、`前端/工程化` |
| 后端 | `后端/API`、`后端/框架`、`后端/数据库`、`后端/安全`、`后端/运维` |
| 工具与工程化 | `工具/工程化` |
| 库自身文件 | `元/导航`、`元/说明`、`元/速查`、`元/模板` |

> [!important] 为什么标签按主题而不按难度分
> 难度已经由 `level` 字段表达（入门 / 进阶 / 高级）。如果标签也去表达难度，同一方向下就会出现「基础」与具体技术并列的情况，
> 结果是按标签浏览时**既不能按主题聚齐，也不能按难度排序**。新增笔记请从上表挑一个已有主题标签；
> 确实需要新主题时，请同时把新标签补进这张表，保持一致。

### 3. Callout 提示框

用 Obsidian 原生语法，按语义选择类型，不要滥用：

```markdown
> [!note] 补充说明
> 一般性的补充信息。

> [!tip] 实践建议
> 工程上的经验。

> [!important] 重点
> 必须记住的核心结论。

> [!warning] 易错点
> 新手常见错误。

> [!example] 示例
> 完整的可运行例子。

> [!question] 自测
> 用来检验理解的问题。

> [!danger] 危险操作
> 可能造成数据丢失或安全事故的操作。
```

### 4. 双链与关联

- 引用其他笔记一律用 `[[笔记名]]`，需要改显示文字时用 `[[笔记名|显示文字]]`
- **只链接真实存在的笔记**，不要凭想象造链接——死链会让关系图谱出现孤立节点
- 每篇笔记结尾必须有 `## 相关笔记` 小节，至少链接 2 篇
- 本库的笔记清单见 [[00-索引]]，链接前先确认目标文件名

### 5. 数学公式

涉及算法与数学的内容必须用 LaTeX，**不要用纯文本描述公式**：

- 行内：`$O(n \log n)$` → $O(n \log n)$
- 块级：

$$
T(n) = 2T\left(\frac{n}{2}\right) + O(n) = O(n \log n)
$$

复杂度的渐进符号统一写成 $O$、$\Theta$、$\Omega$，不要写成 O()、Theta()。

### 6. 内容深度标准

每篇笔记要讲清四件事：**是什么、为什么、怎么用、注意什么**。

> [!warning] 不合格的笔记
> 只罗列术语和目录、没有解释动机、没有可运行代码、没有具体例子。

> [!tip] 合格的笔记
> 读者读完能自己写出代码、能解释设计取舍、能说出至少三个易错点。

每个核心知识点至少配一个代码示例或一道练习题。代码必须逻辑正确、能直接运行，注释解释「为什么」而不是复述「做了什么」。

### 7. 准确性

- 概念以官方文档和权威教材为准，**关键结论注明来源**
- 版本敏感的内容（框架版本号、API 变更）标注「以官方最新文档为准」并给出官方链接
- 不确定的内容宁可写明「有争议」或省略，也不要编造

## 维护约定

- 修改笔记后更新 frontmatter 里的 `updated` 字段
- 新增笔记后回到 [[00-索引]] 补上链接，否则会变成孤立笔记
- 重命名文件后，用 Obsidian 的重命名功能（会自动更新所有双链），不要直接在文件管理器里改名
