链接的基本语法
Markdown 中的链接由两部分组成：链接文字（用方括号 [] 包裹）和目标 URL（用圆括号 () 包裹）。这种语法在视觉上很直观：先是说明链接说的是什么，然后才是链接地址。
内联链接（Inline Links）
源码
# 基本内联链接 [古法编程](https://gufacode.com) # 带 title 的链接（鼠标悬停显示提示） [GitHub](https://github.com "GitHub 首页") # 链接文字可以包含格式 [**官方文档**](https://docs.example.com) [`npm install`](https://npmjs.com)
内联链接的 URL 规则
URL 部分有以下规则：
URL 中的特殊字符
URL 中如果包含空格，需要用
%20 替换空格，或者用尖括号 < > 包裹 URL。例如：[链接](path/to/my%20file.md) 或 [链接](<path/to/my file.md>)。URL 中的右括号
如果 URL 本身包含右括号
)，需要转义为 \)，或用尖括号包裹。例如：[Wikipedia](https://en.wikipedia.org/wiki/Markdown\)。title 属性
title 用单引号、双引号或圆括号包裹均可：
"双引号"、'单引号'、(圆括号)。鼠标悬停时浏览器显示此文字，有助于提升可访问性，但在移动端无法显示（移动端没有悬停状态）。相对路径链接
链接目标可以是绝对 URL（含 http://）或相对路径。相对路径适合文档内部之间的链接：
# 同目录文件 [安装指南](./install.md) [安装指南](install.md) # 等价写法 # 上级目录 [返回首页](../README.md) [父目录的指南](../guide/setup.md) # 根路径（以 / 开头，相对于站点根目录） [首页](/index.md) # 在 MkDocs、Docusaurus 等框架中有效 # 链接到同文件的锚点 [跳转到安装章节](#安装) [跳转到英文锚点](#installation) # 链接到其他文件的锚点 [另一篇文档的某章节](guide.md#configuration)
INFO（锚点规则）标题会自动生成锚点 ID，规则是：标题文字全小写，空格替换为
-，去掉特殊字符。例如 ## Getting Started 的锚点是 #getting-started；## 安装依赖 的锚点在 GitHub 中是 #安装依赖（中文保持原样，空格替换为 -，标点去掉）。
引用链接（Reference Links）
当同一链接在文档中多次出现，或链接 URL 很长影响可读性时，引用链接是更好的选择：
# 第一种：链接文字和引用标识符不同 请访问[古法编程][gufacode]获取更多教程， [古法编程][gufacode] 提供免费的编程课程。 # 第二种：链接文字直接作为引用标识符（折叠引用） 请访问 [古法编程][] 获取更多教程。 # 在文档任意位置（通常在底部）定义引用 [gufacode]: https://gufacode.com "古法编程官网" [古法编程]: https://gufacode.com
引用链接定义的语法格式
引用定义的格式：[标识符]: URL "title（可选）"
# URL 后面的 title 可用三种形式括起 [ref]: https://example.com "双引号 title" [ref]: https://example.com 'single-quote title' [ref]: https://example.com (parentheses title) # URL 可以用尖括号包裹（允许含空格） [ref]: <https://example.com/path with spaces> # 引用标识符不区分大小写 [Google]: https://google.com [google]: https://google.com # 与上面等价
TIP（引用链接的维护优势）对于在文档中多次出现的链接，引用链接有一个重要优势：当链接变化时，只需修改底部的定义一次，而不需要在全文搜索替换。这在 API 文档变更 URL、版本更新等场景非常有价值。
自动链接（Autolinks）
Markdown 提供两种方式让 URL 自动成为可点击链接：
尖括号自动链接（CommonMark 标准）
# URL 自动链接 <https://gufacode.com> <https://github.com/user/repo> # 邮箱自动链接 <user@example.com>
user@example.com（邮箱自动链接）
裸 URL 自动链接（GFM 扩展）
GFM 支持识别裸 URL（不需要尖括号）：
https://gufacode.com 会自动变成可点击链接 www.example.com 也会（GFM 会补全 https://） user@example.com 邮箱也会自动识别
WARNING裸 URL 自动链接是 GFM 扩展，在 CommonMark 标准解析器中不会自动识别，URL 会显示为普通文字。如果文档需要跨平台兼容，用明确的链接语法（
[文字](URL) 或 <URL>）更可靠。
图片（Images）
图片语法和链接语法非常相似，区别只是在最前面加一个感叹号 !：
# 基本图片语法  # 带 title 的图片  # 网络图片  # 引用风格图片 ![替代文字][logo] [logo]: ./images/logo.png "Logo"
alt 文字的重要性
图片语法中的"替代文字"（alt text）不只是备用文字，它有多个重要作用：
可访问性（Accessibility）
屏幕阅读器（Screen Reader）会朗读 alt 文字，视障用户通过它理解图片内容。这是所有图片都应提供有意义 alt 文字的最重要原因。
图片加载失败时的备用内容
当图片 URL 失效或网络错误时，浏览器会显示 alt 文字，让用户知道这里应该有什么内容。
SEO（搜索引擎优化）
搜索引擎无法"看图"，通过 alt 文字理解图片内容，有助于图片出现在相关搜索结果中。
# ❌ 不好的 alt 文字 ![image]() # 空 alt：屏幕阅读器会说"图片"，毫无意义 ![图片1]() # 没有描述性 ![点击查看大图]() # 描述操作而非内容 # ✅ 好的 alt 文字 ![Python 代码执行流程图，展示 AST 解析到字节码编译的步骤]() ![古法编程网站首页截图，展示48门编程课程的卡片布局]() # 装饰性图片（纯装饰，无信息价值）  # 空 alt 是正确的！表示"屏幕阅读器跳过此图"
图片尺寸控制
标准 Markdown 语法不支持设置图片尺寸，需要使用 HTML：
# 按像素设置宽度 <img src="image.png" alt="说明" width="300"> # 按百分比设置宽度 <img src="image.png" alt="说明" width="50%"> # 同时设置宽高（注意保持比例，否则图片会变形） <img src="image.png" alt="说明" width="300" height="200"> # 设置样式（GitHub 不支持 style 属性） <img src="image.png" alt="说明" style="max-width:100%;border-radius:8px;">
INFO（平台差异）GitHub 会过滤
style 属性，但保留 width 和 height 属性。如果目标平台是 GitHub，用 width="300" 而不是 style="width:300px"。在 MkDocs 或 Docusaurus 等框架中，style 属性通常被保留。
图片居中对齐
在 GitHub 中，用 <div align="center"> 或 <p align="center"> 包裹图片来居中：
<div align="center">  **项目名称** · [文档](docs/) · [反馈](issues/) </div>
可点击的图片（图片链接）
将图片嵌套在链接语法内，可以创建可点击的图片：
# 图片链接语法：链接包裹图片 [](目标URL) # 实际例子：可点击的 CI 状态徽章 [](https://github.com/user/repo/actions) # 点击图片跳转到大图 [](full-size.jpg)
徽章（Badges）
GitHub README 中的彩色小徽章本质上是"可点击的图片链接"——用 shields.io 或其他服务生成的微型 SVG 图片。
shields.io 徽章语法
# 基本格式：标签-内容-颜色 https://img.shields.io/badge/标签-内容-颜色 # 示例    
常用徽章类型
| 徽章类型 | 来源 | 示例用途 |
|---|---|---|
| GitHub Actions 状态 | GitHub 自动生成 | 显示 CI 是否通过 |
| 版本号 | shields.io / npm / PyPI | 显示最新发布版本 |
| 许可证 | shields.io | 显示开源许可证类型 |
| 下载量 | shields.io + npm/PyPI | 显示安装量统计 |
| 代码覆盖率 | Codecov / Coveralls | 显示测试覆盖率 |
| Codacy / SonarCloud | 代码质量平台 | 显示代码质量等级 |
| Discord 服务器 | shields.io | 显示在线社区成员数 |
GitHub Actions CI 徽章
# 格式（GitHub 自动生成）  # 实际例子 [](https://github.com/myuser/myrepo/actions/workflows/tests.yml)
链接最佳实践
1. 使用有描述性的链接文字
# ❌ 不好：链接文字无意义 更多信息请[点击这里](https://example.com/docs)。 详情见[此处](https://example.com/api)。 # ✅ 好：链接文字描述目标内容 请查阅[完整 API 文档](https://example.com/docs)。 详见 [REST API 端点参考](https://example.com/api)。
2. 区分内部链接和外部链接
- 内部链接（同仓库内）：使用相对路径，随仓库移动不会失效
- 外部链接（其他网站）：使用绝对 URL，并定期检查有效性
3. 检查链接有效性
# 使用 markdown-link-check 工具 npm install -g markdown-link-check markdown-link-check README.md # GitHub Actions 中自动检查链接 name: Check Links on: push: branches: [main] schedule: - cron: '0 6 * * 1' # 每周一 6:00 检查 jobs: link-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Link Checker uses: gaurav-nelson/github-action-markdown-link-check@v1 with: use-quiet-mode: 'yes'
4. 使用引用链接提高可维护性
# 文档中多次引用同一资源 查看 [官方文档][docs] 了解安装方法。 遇到问题可以在 [讨论区][discuss] 提问。 也可以阅读 [官方文档][docs] 中的 FAQ 章节。 # 文档底部统一管理所有引用 [docs]: https://docs.example.com "官方文档" [discuss]: https://github.com/user/repo/discussions "讨论区"
常见错误与误区
WARNING（常见错误 1）方括号内的链接文字和圆括号内的 URL 之间不能有空格：
[文字] (URL) 是错误的，会解析为字面量 [文字] 后跟 (URL)。正确写法：[文字](URL)（紧贴，无空格）。
WARNING（常见错误 2）图片语法
![]() 和链接语法 []() 的区别只是开头的 !。初学者常忘记加 ! 导致图片变成链接，或多加 ! 导致链接变成图片。
WARNING（常见错误 3）在 Markdown 中链接 Email 地址时，如果不用
<> 包裹或明确写 mailto: 协议，不同解析器的行为不一致。推荐明确写法：[联系我们](mailto:contact@example.com)。
小结
本章要点
- 内联链接：
[文字](URL)，可加"title"；方括号和圆括号之间不能有空格 - 引用链接：
[文字][标识符]+ 底部定义，适合多次引用同一 URL - 自动链接：
<URL>（CommonMark）或裸 URL（GFM 扩展） - 图片：
，alt 文字对可访问性和 SEO 很重要；控制尺寸需用 HTML<img> - 图片链接：
[](linkURL)，图片嵌套在链接语法内 - 徽章：shields.io 等服务生成 SVG 图片徽章，常用于 README
- 链接文字应有描述性；定期检查链接有效性；多次引用同一 URL 用引用链接管理