Markdown 语法入门：一篇文章学会常用写法

写技术博客、项目文档、接口说明时，Markdown 几乎是必备技能。
相比 Word 的复杂排版，Markdown 更轻量、更专注内容。

如果你刚开始写博客，或者经常写 README、知识库文档，那么这篇文章基本够用了。

本文会带你快速掌握 Markdown 常用语法 + 实战示例。

一、什么是 Markdown？

Markdown 是一种：

轻量级标记语言

它的特点：

语法简单
易读易写
支持 HTML
适合写技术文档
各大平台广泛支持

例如：

# 标题

这是正文内容

渲染后：

标题

这是正文内容。

常见使用场景：

技术博客
GitHub README
接口文档
知识库
项目说明文档

二、标题语法

使用 # 表示标题。

数量不同代表层级不同。

写法：

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

效果：

一级标题

二级标题

三级标题

建议：

一篇文章尽量不要超过三级标题。

这样阅读体验更好。

三、文本格式

1. 加粗

写法：

**加粗文字**

效果：

加粗文字

2. 斜体

写法：

*斜体文字*

效果：

斜体文字

3. 删除线

写法：

~~删除内容~~

效果：

~~删除内容~~

4. 高亮（部分编辑器支持）

写法：

==高亮==

效果：

高亮

四、引用

适合写说明、提示。

写法：

> 这是一段引用

效果：

这是一段引用

多层引用：

> 一级引用
>> 二级引用

效果：

一级引用
二级引用

五、列表

无序列表

写法：

- Java
- Python
- Go

效果：

Java
Python
Go

也可以：

* 内容
+ 内容

有序列表

写法：

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

效果：

第一项
第二项
第三项

嵌套列表

写法：

1. 后端
   - Java
   - Spring
2. 前端
   - Vue

效果：

后端
- Java
- Spring
前端
- Vue

六、代码块

技术博客最常用。

行内代码

写法：

使用 `docker ps` 查看容器

效果：

使用 docker ps 查看容器。

多行代码块

三个反引号：

```java
public class Test {
    public static void main(String[] args){
        System.out.println("Hello Markdown");
    }
}
```

效果：

public class Test {
    public static void main(String[] args){
        System.out.println("Hello Markdown");
    }
}

支持语言高亮：

java
python
javascript
bash
sql
json

例如：

docker ps
docker logs nginx

七、分割线

写法：

---

效果：

适合章节分隔。

八、链接

普通链接

写法：

[百度](https://www.baidu.com)

效果：

百度

自动识别链接

直接写：

https://www.github.com

效果：

https://www.github.com

九、图片

写法：

![图片描述](图片地址)

例如：

![logo](https://xxx.com/logo.png)

本地图片：

![截图](./images/demo.png)

十、表格

Markdown 也支持表格。

写法：

| 技术 | 用途 |
|---|---|
| Java | 后端开发 |
| Docker | 容器部署 |
| Nginx | 反向代理 |

效果：

技术	用途
Java	后端开发
Docker	容器部署
Nginx	反向代理

对齐方式：

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

效果：

左对齐	居中	右对齐
内容	内容	内容

十一、任务列表

适合 TODO。

写法：

- [x] 学习 Markdown
- [ ] 写博客
- [ ] 学 LangGraph

效果：

学习 Markdown
写博客
学 LangGraph

十二、目录

部分博客系统支持。

写法：

[TOC]

或者：

[[toc]]

具体看博客平台。

十三、转义字符

如果想显示 Markdown 符号本身：

加反斜杠 \

例如：

\# 不是标题

效果：

# 不是标题

十四、HTML 混写

Markdown 支持 HTML。

例如：

<div style="color:red">
红色字体
</div>

效果：

不过：

不同博客平台对 HTML 支持程度不同。

十五、Markdown 常见使用场景

1. 写博客

例如：

技术文章
学习记录
踩坑总结

2. GitHub README

项目说明：

项目介绍
安装方式
启动命令
接口文档

3. 接口文档

示例：

{
  "code": 200,
  "msg": "success"
}

4. 知识库文档

整理：

Linux 命令
Java 面试题
运维手册

十六、常见坑

1. 代码块不生效

注意：

必须是：

三个反引号

不要写成中文符号。

2. 表格不显示

注意：

表格前后空一行。

3. 图片不显示

检查：

路径是否正确
是否是公网地址
图片是否存在

十七、总结

Markdown 最大的优点：

把精力放在内容，而不是排版。

对于程序员来说：

学会 Markdown，基本等于掌握了技术文档写作基础。

建议：

直接开始写，不用死记硬背。

因为：

用多了，自然就记住了。

最后送一句：

写博客最难的不是 Markdown，而是坚持更新 😄

Markdown语法入门