一、Markdown 核心语法​​

Markdown 是一种轻量级标记语言，通过简单的符号实现文本格式化。以下是常用语法：

1. ​​标题​​

用 # 定义标题层级，建议标题前后空一行：

# 一级标题
## 二级标题
### 三级标题
#### 四级标题

2. ​​段落与换行​​

• ​​段落​​：段落间用空行分隔。
• ​​换行​​：在行尾添加两个空格或使用 <br> 强制换行。

3. ​​列表​​

• ​​无序列表​​：用 -、* 或 +：

- 项目1
- 项目2
  - 子项目（缩进2空格或1个Tab）

• 有序列表​​：用数字加 .：

1. 第一项
2. 第二项

4. ​​强调​​

• ​​粗体​​：**文本** 或 __文本__
• ​​斜体​​：*文本* 或 _文本_
• 删除线：~~文本~~

5. ​​代码​​

• ​​行内代码​​：用反引号 `code`
• ​​代码块​​：用三个反引号 ``` 包裹，并指定语言：

```python
print("Hello, Markdown!")
```

6. ​​链接与图片​​

• ​​链接​​：[显示文本](URL "可选标题")
  示例：[Google](https://www.google.com)
• ​​图片​​：![替代文本](图片URL "可选标题")
  示例：![Logo](logo.png "公司Logo")

7. ​​引用​​

用 > 表示引用：

> 这是引用内容  
> 多行时每行前加 `>`

8. ​​水平分割线​​

用三个或多个 ---、*** 或 ___（前后空一行）：

---

二、扩展语法（GFM/GitHub Flavored Markdown）​​

许多平台（如 GitHub、GitLab）支持扩展语法：

1. ​​表格​​

用 | 和 - 对齐列：

| 左对齐 | 居中对齐 | 右对齐 |
| :----- | :------: | -----: |
| 内容1  |  内容2   |   内容3 |
| 内容4  |  内容5   |   内容6 |

2. ​​任务列表​​

用 - [ ] 或 - [x] 表示未完成/已完成的任务：

- [x] 完成文档大纲
- [ ] 编写核心章节

3. ​​自动链接​​

直接写 URL 或邮箱地址会自动转为链接：
https://github.com → https://github.com

4. ​​脚注​​

用 [1](@ref) 标记脚注，底部用 [1](@ref): 注释内容 定义：

这是一段文字[1](@ref)。

[1](@ref): 这是脚注内容。

5. ​​流程图与公式（需平台支持）​​

• ​​流程图​​（如 Mermaid）：

```mermaid
graph LR
  A[开始] --> B{条件}
  B -->|是| C[执行操作]
  B -->|否| D[结束]
```

• ​数学公式​​（LaTeX）：

行内公式：$E=mc^2$  
块级公式：
$$
\sum_{i=1}^n i = \frac{n(n+1)}{2}
$$

三、编写规范与最佳实践​​

1. ​​保持一致性​​

• 使用统一的符号（如无序列表用 -，标题层级不超过4级）。
• 文件名建议使用小写字母和短横线（如 how-to-write-md.md）。

2. ​​增强可读性​​

• ​换行​​：每行不超过 80 字符（避免横向滚动）。
• ​​空格​​：中英文混排时，中文字符与英文字符间加空格（如 安装 Python 3.10）。
• ​​注释​​：用 HTML 注释隐藏说明（<!-- 这是注释 -->）。

3. ​​代码块规范​​

• 指定语言以支持语法高亮（如 ```python）。
• 复杂代码建议拆分到独立文件，通过链接引用。

4. ​​链接管理​​

• 长链接建议用引用式写法：

[GitHub][1]

[1]: https://github.com

5. ​​图片处理​​

• 优先使用相对路径（如 ![Alt](./images/logo.png)）。
• 大图片建议压缩或托管到图床（如 Imgur）。

6. ​​版本控制友好​​

• 避免使用平台专属扩展语法（如非通用的流程图）。
• 使用清晰的提交消息（如 "docs: 更新Markdown规范"）。

四、工具推荐​​

1. ​​编辑器​​

• ​​VS Code​​：支持实时预览、扩展语法高亮。
• ​​Typora​​：所见即所得模式，适合新手。
• ​​Obsidian​​：支持双向链接和知识图谱。

2. ​​校验工具​​

• ​​Markdownlint​​：检查语法规范（VS Code 插件）。
• ​​Prettier​​：自动格式化代码和文档。

3. ​​协作平台​​

• ​​GitHub/GitLab​​：支持 GFM 语法和 Issues 协作。
• ​​Notion​​：富文本编辑器，适合团队文档。

​五、示例文档结构​​

# 项目名称

![项目Logo](./images/logo.png)

## 简介
- 项目目标：用一句话描述核心功能。
- 适用场景：说明项目解决的问题。

## 快速开始
### 安装依赖
```bash
npm install