什么是 Markdown？

Markdown 是一种轻量级的标记语言，用简单的符号来格式化文本。它易学易用，广泛应用于博客、文档、README 文件等场景。

基础语法回顾

标题

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

强调

*斜体* 或 _斜体_
**粗体** 或 __粗体__
***粗斜体*** 或 ___粗斜体___
~~删除线~~

列表

无序列表：

- 项目 1
- 项目 2
  - 子项目 2.1
  - 子项目 2.2
- 项目 3

有序列表：

1. 第一项
2. 第二项
3. 第三项

链接和图片

[链接文本](https://example.com)
[链接文本](https://example.com "链接标题")
![图片描述](image.jpg)
![图片描述](image.jpg "图片标题")

高级技巧

1. 代码块

行内代码：

使用 `code` 表示行内代码

代码块：

```python
def hello_world():
    print("Hello, World!")
```

支持的语言高亮包括：python、javascript、java、c++、bash 等。

2. 表格

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 数据1 | 数据2 | 数据3 |
| 数据4 | 数据5 | 数据6 |

对齐方式：

| 左对齐 | 居中 | 右对齐 |
|:------|:----:|-------:|
| 左 | 中 | 右 |

3. 引用

> 这是一个引用
> 可以有多行
> 
> > 嵌套引用

4. 分割线

---
***
___

5. 列表中的代码块

1. 第一步
   ```python
   code here
   ```

2. 第二步
   ```javascript
   code here
   ```

6. 脚注

这是一个脚注[^1]

[^1]: 脚注内容

最佳实践

1. 结构清晰

  • 使用合适的标题层级（不要跳级）
  • 每个部分用标题分隔
  • 逻辑递进，循序渐进
# 主标题
## 第一部分
### 小节 1
### 小节 2
## 第二部分
### 小节 3

2. 代码示例完整

提供可运行的代码示例，包括导入和完整的上下文：

❌ 不好的做法：
```python
result = function(data)
```

✅ 好的做法：
```python
from module import function

data = [1, 2, 3]
result = function(data)
print(result)
```

3. 使用列表组织信息

❌ 不好的做法：
这个功能有三个优点：速度快、易于使用、功能强大。

✅ 好的做法：
这个功能有三个优点：
- 速度快
- 易于使用
- 功能强大

4. 链接使用规范

❌ 不好的做法：
更多信息请点击[这里](https://example.com)

✅ 好的做法：
更多信息请查看[官方文档](https://example.com)

5. 图片优化

❌ 不好的做法：
![](image.jpg)

✅ 好的做法：
![网站首页截图](images/homepage.jpg "首页展示")

6. 使用引用强调重点

> **注意：** 这是一个重要提示
> 
> 具体内容说明

7. 代码块语言标注

❌ 不好的做法：
```
code here
```

✅ 好的做法：
```python
code here
```

常见错误

1. 标题层级混乱

❌ 错误：
# 标题
### 小标题（跳过了二级）

✅ 正确：
# 标题
## 小标题

2. 列表缩进不一致

❌ 错误：
- 项目1
  - 子项目1
 - 子项目2（缩进不一致）

✅ 正确：
- 项目1
  - 子项目1
  - 子项目2

3. 代码块前后没有空行

❌ 错误：
这是说明
```python
code
```
继续说明

✅ 正确：
这是说明

```python
code
```

继续说明

工具推荐

编辑器

  • VS Code - 强大的代码编辑器，Markdown 支持完善
  • Typora - 所见即所得的 Markdown 编辑器
  • Obsidian - 知识库管理工具，Markdown 支持优秀
  • Notion - 在线笔记工具，支持 Markdown

预览工具

  • Markdown Preview Enhanced - VS Code 扩展
  • Grip - 命令行工具，实时预览
  • Pandoc - 文档转换工具

总结

Markdown 的强大之处在于它的简洁性和灵活性。通过掌握基础语法和最佳实践，你可以写出清晰、专业的文档。

记住这些要点：

  • 保持结构清晰
  • 代码示例完整
  • 链接描述准确
  • 图片有说明
  • 一致的格式风格

相关资源：