moon-note-style

name	moon-note-style
description	按本仓库作者的个人风格编写、改写与校对中文技术笔记（Markdown）。当新建技术笔记、往已有笔记补充/重构内容、或对笔记做格式化与风格校对时使用；覆盖标题层级、中英文空格、彩色强调、Obsidian callout、代码块、表格、图片、wiki 链接等书写约定。

个人技术笔记书写风格（MooN Note Style）

按本人一贯的中文技术笔记风格产出内容。核心目标：新写、改写、校对的笔记，读起来跟仓库里已有笔记出自同一人之手。

何时使用

• 新建技术笔记：从零编写一篇符合风格的 .md
• 改写/补全已有笔记：往现有笔记追加章节或重构段落时，沿用同一风格
• 格式化/风格校对：检查并修正一篇笔记是否符合下列书写约定

核心约定（必须遵守）

1. 语言与排版

• 正文一律中文，技术术语保留英文，首次出现常用「中文（English）」或「English（中文）」括注，例如 控制反转（IoC）
• 中英文、中文与数字之间加一个半角空格：线程池是 JDK 1.5 后的新特性、Java 程序、第 3 个组成部分
• 标点用中文全角 。，：；（）「」；纯代码/命令/路径内部保持原样不加空格
• 换行一律靠空行实现：段落之间空一行分隔；禁用行尾两个空格的硬换行
• 行文遵循递进逻辑：概念 → 特点/好处 → 用法/示例 → 注意事项
• 列表项常用「术语：解释」句式，例如 - 对象：对象是类的一个实例，有状态和行为

2. 标题层级

• 正文从 ##（H2）起，逐级 ### / #### / ##### 深层嵌套，**不要用 #（H1）**当正文主标题（H1 仅极少数总览类文档使用）
• 标题为纯文字，不手动加编号（编号交给 Obsidian header-enhancer 处理）
• 标题命名简洁，可带英文括注：### JVM 类加载（Class Loading）

3. 强调与彩色标记（统一用 <span style>，按语义使用）

• 普通重点：**加粗**
• 补充/旁注说明：*斜体*（如 *注：只有实现该接口才能被调度*）
• 行内代码：类名、方法、关键字、配置项、路径、命令一律用反引号，如 ThreadPoolExecutor、shutdown()、spring.profiles.active
• 最高优先级警示 / 必知要点 / 易错点：<span style="color: red;">**红字**</span>
• 重要结论、关键定义、"注意/总结/值得注意"：<span style="color: purple;">**紫字**</span>
• 次一级需要留意的点：<span style="color: violet;">**粉字**</span>
• 下划线等其他样式同样用 <span style="text-decoration: ..."> 实现
• 颜色语义与下划线变体的完整清单见 reference.md。红色只用于最关键处，不要滥用彩色。

[!warning] 必须遵守：给文字加样式一律用 <span style="..."> <font>（如 <font color=red>）和 <u> 标签是早期笔记遗留的旧写法，已废弃，新写与改写笔记时严禁再使用。所有文字样式（颜色、下划线等）必须严格用 <span style="..."> 实现。改写老笔记遇到 <font> / <u> 时，顺手替换为等价的 <span style> 写法。

4. Obsidian Callout（新笔记统一用这套）

新写笔记的提示块统一使用 Obsidian callout 语法，不再用旧的 > Notes: / > Tips: / > 注：（改写老笔记时若整篇是旧风格，保持整篇一致即可）：

> [!note] 可选的中文标题
> 正文内容……

• 标题写不写自行判断：内容一两句、直给结论就不加标题（> [!tip] 一句话提示）；内容较长或需要点题时加简短中文标题（> [!info] 注意事项：）
• callout / 引用块内多行或多段，用一个只含 > 的空行分隔（不是行尾两空格）：

> [!info] 注意事项（中文乱码问题）：
>
> 在复制代码保存时，编码必须选择 `UTF-16 LE` 格式，否则右键菜单的中文会乱码。

• 常用类型：note 补充说明、tip 技巧/建议、info 提示/前提、warning 警告、quote 引述/出处、question 疑问、example 示例、success/failure/danger/bug。完整语义表见 reference.md
• callout 内可继续用彩色强调、行内代码、《笔记名》 引用

5. 代码块

• 必须标注语言：```java、```xml、```yaml、```sql、```bash、```markdown 等
• 代码注释用中文，风格贴近示例（如 // 使用反射创建对象）
• 展示接口/源码片段时，可保留原始英文 doc 注释再补中文说明
• 相邻多个方法/配置可拆成多个小代码块，每块后紧跟一句作用说明

6. 表格

• 大量用于关键字、API、配置项、对比项的速查
• 首列（名称/关键字列）常居中对齐 :---:，说明列左对齐
• 表格前用一句话点明用途，例如 以下是 Java 关键字汇总表

7. 图片

• 语法 ![](images/文件名.png)，引用与笔记同级的 images/ 目录
• 需要图注时写 ![生成war包](images/xxx.png)，否则 alt 留空
• 不要臆造图片路径；新增图片沿用现有命名习惯（数字 ID 或 时间戳_序号）

8. 跨笔记引用与链接

• 笔记间跳转用 Obsidian wiki 链接：[[文件名|显示别名]]、锚点用 [[文件名#章节|别名]]
• 正文提到其他笔记/章节用书名号：具体详见《ThreadPoolExecutor》章节、详见后面《属性加载优先级》章节
• 外部链接用标准 Markdown [文字](url)

笔记骨架模板

新建一篇笔记时，从这个骨架起步（不带 YAML frontmatter，直接从 ## 开始）：

## <主题> 简介

### 概念

<一句话定义 + 展开说明，中英文加空格>

### 特点 / 好处

- <要点：解释>
- <要点：解释>

## <主题> 核心用法

### <子主题>

<说明文字>

​```java
// 中文注释的示例代码
​```

> [!tip] <可选标题>
> <技巧或注意>

## 注意事项 / 常见问题

> [!warning] <标题>
> <易错点，关键处用 <span style="color: red;">**红字**</span> 标注>

工作流

新建笔记

1. 确认存放目录（按主题归类，如 Java/、并发编程/、分布式微服务/xxx/）与文件命名（主题-子主题.md，如 Java基础-集合.md）
2. 用上面的骨架搭结构，从 ## 起
3. 逐节填充，全程套用「核心约定」
4. 收尾用《校对清单》自查

改写 / 补全已有笔记

1. 先读该笔记现有片段，识别它用的是新风格（Obsidian callout）还是旧风格（> Notes:）
2. 追加内容时与整篇保持一致：旧风格笔记里就别混入 callout，除非要顺带统一整篇
3. 沿用该笔记已有的标题层级深度、术语、图片目录

格式化 / 风格校对

逐项对照《校对清单》，只改不符合项，不改动技术内容与作者原意；发现的问题按「必须改 / 建议改」分级反馈。

校对清单

- [ ] 正文从 ## 起，无多余 H1，标题无手动编号
- [ ] 中英文 / 中文数字之间有半角空格
- [ ] 中文标点为全角
- [ ] 换行用空行实现，无行尾两空格硬换行；callout/引用块内多段用只含 `>` 的空行分隔
- [ ] 类名/方法/关键字/路径/命令用了行内反引号
- [ ] 彩色强调按语义使用：红=最关键警示，紫=重要结论/注意，且未滥用
- [ ] 文字样式一律用 <span style="...">，无 <font> / <u> 等遗留标签
- [ ] 提示块用 Obsidian callout（新笔记），整篇风格一致
- [ ] 代码块都标了语言，注释为中文
- [ ] 表格用于速查，名称列居中
- [ ] 图片引用同级 images/ 目录，路径真实存在
- [ ] 跨笔记用 [[wiki 链接]]，正文引用章节用《书名号》

其他资源

• callout 类型语义表、颜色/下划线完整清单、标点与空格细则、命名与目录约定、完整示例：见 reference.md