Markdown从入门到精通（三）：进阶语法——让文档更丰富

学会这些，你的文档就能图文并茂了。

---

一、链接

1.1 基本语法

[显示文字](链接地址)

示例：

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

渲染效果：

百度

GitHub

1.2 带标题的链接

鼠标悬停时显示提示文字：

[百度](https://www.baidu.com "点击访问百度")

1.3 引用式链接

适合多处引用同一链接：

我常用 [Google][1] 和 [百度][2] 搜索。

[1]: https://www.google.com
[2]: https://www.baidu.com

好处：正文简洁，链接集中管理。

1.4 直接显示URL

用尖括号包裹：

<https://www.example.com>
<email@example.com>

渲染效果：

www.example.com

1.5 常见问题

问题	原因	解决
链接无效	URL有空格	用 %20 替换空格
中文显示异常	编码问题	使用URL编码
链接内有括号	解析错误	使用 %28 %29 转义

---

二、图片

2.1 基本语法

![替代文字](图片地址)

示例：

![Markdown Logo](https://markdown-here.com/img/icon256.png)

2.2 带标题的图片

![Markdown Logo](https://markdown-here.com/img/icon256.png "Markdown图标")

2.3 图片链接

图片可以嵌套链接：

[![Markdown Logo](https://markdown-here.com/img/icon256.png)](https://markdown-here.com)

效果：点击图片跳转到指定链接。

2.4 图片尺寸控制

标准Markdown不支持尺寸控制，但很多平台支持HTML：

<img src="https://example.com/image.png" width="50%">

Typora等编辑器支持：

![图片](image.png =100x50)  # 宽100，高50
![图片](image.png =100x)    # 宽100，高自动

2.5 图片存储策略

策略	优点	缺点
本地存储	不依赖网络	分享不便
图床	跨平台使用	图床可能失效
CDN	稳定快速	需要成本

推荐图床：

• GitHub仓库（免费，国内可能慢）
• 阿里云OSS（稳定，需付费）
• 腾讯云COS（稳定，需付费）

---

三、表格

3.1 基本语法

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容1 | 内容2 | 内容3 |
| 内容4 | 内容5 | 内容6 |

渲染效果：

列1	列2	列3
内容1	内容2	内容3
内容4	内容5	内容6

3.2 对齐方式

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

渲染效果：

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

对齐语法：

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

3.3 表格内换行

使用 <br>：

| 项目 | 说明 |
|------|------|
| 项目A | 第一行<br>第二行 |

3.4 表格内强调

表格内可以使用其他Markdown语法：

| 语言 | 难度 |
|------|------|
| **Python** | 简单 |
| *Java* | 中等 |
| `C++` | 困难 |

3.5 表格的限制

限制	解决方案
不支持合并单元格	使用HTML表格
不支持复杂格式	使用HTML或专业工具
宽表格显示问题	简化内容或换行

---

四、代码块

4.1 行内代码

用反引号包裹：

使用 `print()` 函数输出内容。

渲染效果：

使用 print() 函数输出内容。

4.2 代码块

用三个反引号包裹：

```
这是一段代码
第二行代码
```

渲染效果：

这是一段代码
第二行代码

4.3 语法高亮

指定语言可以高亮显示：

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

渲染效果：

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

4.4 支持的语言

类别	语言
编程语言	java, python, javascript, go, rust, c, cpp
前端	html, css, vue, react
数据	json, yaml, xml, sql
配置	bash, shell, dockerfile, makefile
其他	markdown, mermaid, diff

4.5 显示行号

部分平台支持：

```java linenums="1"
public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}
```

4.6 代码块内显示反引号

如果代码块内有反引号，外层用更多反引号：

```
这里有三个反引号
```

---

五、综合示例

# 项目技术栈

本项目使用以下技术：

## 后端技术

| 技术 | 版本 | 说明 |
|------|------|------|
| Java | 21 | 主要开发语言 |
| Spring Boot | 4.0.4 | Web框架 |
| PostgreSQL | 16 | 数据库 |

## 核心代码示例

```java
@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello, World!";
    }
}

## 相关链接

- [Spring Boot官网](https://spring.io/projects/spring-boot)
- [PostgreSQL官网](https://www.postgresql.org/)

## 项目截图

![项目架构图](./images/architecture.png)

---

六、语法速查表

功能	语法
链接	[文字](URL)
图片	
表格	`	列1	列2	`
行内代码	`代码`
代码块	```语言

---

七、常见问题

7.1 图片不显示？

原因	解决
URL错误	检查链接是否正确
图片需登录	使用公开图床
跨域限制	使用允许外链的图床
格式不支持	转换为常见格式（png/jpg）

7.2 表格显示异常？

原因	解决
内容有换行	使用 <br>
列数不一致	检查每行列数

7.3 代码块不高亮？

原因	解决
未指定语言	添加语言标识
语言不支持	查看平台支持列表
拼写错误	检查语言名称

---

八、练习题

创建一个技术介绍文档，包含：

1. 标题和简介
2. 一个带对齐方式的表格
3. 一段带语法高亮的代码
4. 一个链接到官方网站
5. 一张图片

---

九、总结

要点	内容
链接	[文字](URL) 支持引用式
图片	 可嵌套链接
表格	|列| 格式，支持对齐
代码	行内用反引号，块用三反引号+语言

---