Markdown 可以理解成一种轻量级标记语言。名字里就带着意思：Mark（标记）+ down（简化版）。
最早是 2004 年 John Gruber创建了Markdown，后来在 GitHub、Reddit、Stack Overflow、Swift等写作工具里大规模普及。程序员尤其爱用它，因为写起来比 HTML、Word 都快，还能放进 Git 管理。
它的目标就是：
使用非常简单、直观的符号（比如 #、*、>）来写文档，而不用记复杂的 HTML 或 Word 样式按钮。然后，Markdown 会被“渲染”成漂亮的格式化文本（网页文章、PDF、README 等）。
在学习前，可以在MarkdownLivePreview页面中预览Markdown语言。
Markdown语法
1、标题
# 一级标题
## 二级标题
### 三级标题在使用Markdown时，要在符号和内容之间添加一个空格：
# 一级标题 // 正确写法，添加空格
#一级标题 // 错误写法，没有空格
替代语法-一级标题：
基本用法
===============替代语法-二级标题：
详细信息
---------------2、段落
在海洋中.
在深水里.
段落之间使用空行分隔一行或多行。
除非段落在列表中，否则不要使用空格或制表符缩进段落：
清风浮绿水. // 正确写法
红掌拨清波. // 错误写法，使用了制表符3、换行符
在一行末尾添加两个空格或多个空格，然后按回车创建换行符。
这是一棵树.
那也是一棵树.
在Markdown应用程序中，编辑器很难看到尾随空格，如果Markdown应用支持HTML，可以使用<br>HTML标签。
在CommonMark或其他轻量级标记语言中可以在行尾输入反斜杠：
大江大海.\
涌浪洪波.但并非所有Markdown应用都支持此功能，从兼容性角度来看，并不是一个好的选择。如果反斜杠 \ 的下一行没有内容，反斜杠可能会被作为转义字符显示出来。因此，推荐使用两个空格或者<br>HTML标签。
4、粗体
在单词或短语前后添加两个星号或下划线，表示强调。
这是 **粗体**.
这也是 __粗体__.
加粗的**粗体**字体
因为Markdown应用在处理单词中间的下划线时存在分歧，为了兼容，建议使用两个星号加粗单词表示强调。
Eat**a**dumpling // 单词中间推荐使用星号加粗
Eat__a__dumpling // 不推荐在单词中间使用__下划线5、斜体
在单词或短语前后添加一个星号或下划线，表示斜体文字。
他走路总是 *歪歪扭扭* 的.
她走路也是 _歪歪扭扭_ 的.
歪*歪*扭*扭*
因为Markdown应用在处理单词中间的下划线时存在分歧，为了兼容，建议使用一个星号斜体化单词表示强调。
A*winding*road // 在单词中，推荐使用星号实现斜体
A_winding_road // 在单词中，不推荐使用下划线实现斜体6、粗体和斜体
同时使用粗体和斜体强调文本，需要在单词或短语前后添加三个星号或下划线：
加重的 ***文本***.
加重的 ___文本___.
加重的 __*文本*__.
加重的 **_文本_**.
so***very***Good.
因为Markdown应用在处理单词中间的下划线时存在分歧，为了兼容，建议使用三个个星号斜体化单词表示强调。
so***very***Good.// 推荐写法，使用是三个星号
so___very___Good. // 不推荐写法，使用三个下划线7、块引用
1、块引用
创建块引用，在段落前面添加 >
> 床前明月光，疑是地上霜.渲染的输出如下所示：
2、多个段落的块引用
块引用还可以包含多个段落，在段落前面添加 >
> 床前明月光, 疑是地上霜.
>
> 举头望明月, 低头思故乡.渲染的输出如下所示：
3、嵌套的块引用
块引用可以嵌套，在要嵌套的段落前面添加 >>
> 孩子们唱到
>
>> 枫叶落呀落, 秋风何时归渲染的输出如下所示：
4、包含其他元素的块引用
块元素还可以包含其他Markdown格式的元素：
> ### 天气预报
>
> + 明天, 晴转多云
> + 后天, 阴
> + 大后天, **暴雨**渲染的输出如下所示：
为了兼容性，在块引用前后放置空格：
// 正确写法，前后放置空行
今天出去吃饭
> 吃了包子
回去睡觉
// 错误写法，块引用前后没有空行
考试前读书.
> 临阵磨枪，不快也光
努力挣分数8、列表
1、有序列表
添加数字或句点的行项目：
1. 太阳
2. 月亮
3. 星星
4. 陨石
数字可以不按照数字顺序排序，但列表应从数字1开始。
写法1:
1. 花
1. 草
1. 树
1. 木
写法2:
1. 鸟
3. 语
7. 花
2. 香
嵌套写法：
1. 日记
2. 2025年9月2日
3. 天气晴
1. 无事
2. 玩手机
4. 完成
CommonMark和其他一些轻量级标记语言运行使用括号 ) 作为分隔符，例如 1) First item，但并不是所有Markdown都支持这一功能，为了兼容性，应该使用小数点。
// 推荐的写法，使用小数点分隔
1. 第一天
2. 第二天
// 不推荐的写法，使用 ) 括号分隔
1) 第一天
2) 第二天2、无序列表
创建无序列表，可以在行前添加破折号（-）、星号（*）或加号（+），缩进一个或多个可以创建嵌套列表。
写法1：
- 第一名
- 第二名
- 第三名
- 第四名
写法2：
* 一颗星
* 二颗星
* 三颗星
* 四颗星
写法3：
+ 一加
+ 二加
+ 三加
+ 四加
嵌套写法：
- 凌晨
- 早上
- 中午
- 吃饭
- 午休
- 睡觉
在无序列表中，显示数字+小数点+空格开始的句子，应该使用反斜杠（\）来转义句点。
- 100\. 白日梦如果不使用反斜杠，Markdown会把它（1968.）当成有序列表，渲染出来的内容被重新编号。
在无序列表中，不要混用不同的分隔符，选择一种并坚持使用：
// 推荐写法，只使用一种分隔符
- 坚持
- 坚持
- 坚持
- 还是坚持
// 不推荐写法，混合多种分隔符
+ 加
- 减
* 乘列表中也可以添加Markdown的其他元素，无序列表和有序列表至今也可以互相嵌套。
9、代码块
通常缩进四个空格或一个制表符。如果是列表形式，则缩进八个空格或两个制表符。
ls ~/Downloads/
单词或者短语的代码，可以建议使用单个反引号（`）包裹：
推荐使用 `ScrollView`
多行代码：
在GitHub Flavored Markdown (GFM) 等扩展中，引入围栏法（用三个引号或者三个波浪号）。
// 三个单引号
```
VStack {
Text("方君宇")
}
```
// 三个波浪号
~~~
VStack {
Text("方方方")
}
~~~
三个反引号是现代主流写法，表示多行代码块。
10、链接
链接文本格式：
[链接文本](URL)在方括号中填写链接文本，在小括号中填写URL：
[方君宇](https://www.fangjunyu.com)添加链接标题格式：
[链接文本](URL "链接标题")和链接格式不同之处，在于URL后面空格并使用双引号包裹链接标题：
[方君宇](https://www.fangjunyu.com "方君宇的网站")
URL兼容性
在Markdown应用中，如何处理URL中间的空格存在分歧。为了兼容性，使用 %20 替换URL中的空格：
[fangjunyu](https://www.fangjunyu.com/Hello%20Word) // 正确写法，使用 %20 替代空格
[fangjunyu](https://www.fangjunyu.com/Hello Word) // 错误写法，保留空格，存在兼容性问题如果Markdown应用程序支持HTML，也可以使用aHTML标签：
<a href="https://www.fangjunyu.com/Hello Word">fangjunyu</a>处理做括号和右括号时，也存在同类问题，使用 %28 替代左括号，使用 %29 替代右括号。
[fangjunyu](https://www.fangjunyu.com/计算机历史%28ASCII%29) // 正确写法，使用 %20 替代空格
[fangjunyu](https://www.fangjunyu.com/计算机历史（ASCII）) // 错误写法，保留空格，存在兼容性问题如果支持HTML，也可以使用aHTML标签：
<a href="https://www.fangjunyu.com/计算机历史（ASCII）">fangjunyu</a>引用式链接
Markdown的引用式链接（reference-style link），核心思想是把链接和正文内容分离，让 Markdown 文档更干净、更易读。可以拆解成两部分：
1、正文里的链接文本
使用两个方括号表示：
[个人网站][1]
[个人网站] [1] ← 空格可选[hobbit-hole] → 这是用户看到的文字。
[1] → 这是链接的标签，用来指向文档中定义的 URL。
标签大小写不敏感，可以是字母、数字、空格或标点。
2、定义链接
文档中任意地方定义标签对应的 URL（可选 title）：
[1]: https://fangjunyu.com/
[1]: https://fangjunyu.com/ '方君宇网站'
[1]: https://fangjunyu.com/ "方君宇网站"
[1]: https://fangjunyu.com/ (方君宇网站)
[1]: <https://fangjunyu.com/> '方君宇网站'
[1]: <https://fangjunyu.com/> "方君宇网站"
[1]: <https://fangjunyu.com/> '方君宇网站'[1]: → 标签。
URL → 链接地址。
“方君宇网站” → 可选标题（鼠标悬停显示）。
URL 可以加尖括号 <…>，标题可以用 ” “、’ ‘ 或 ( )。
3、组合示例
正文里写：
这是方君宇的[个人网站][1]文本末尾定义链接：
[1]: <https://fangjunyu.com/> '方君宇网站'渲染后的效果和普通内联链接一样：
<a href="https://www.fangjunyu.com/" title="方君宇网站">hobbit-hole</a>这种写法的优点在于，文本更简洁，不会被长URL干扰阅读，可以多次引用同一个链接，便于维护、批量修改链接。
11、图片
Markdown图片格式写法：
使用叹号、方括号和小括号组成，方括号填写图片描述，小括号填写图片链接。
title悬停提示：
在图片地址后面添加双引号表示标题提示：
链接图像：
[](URL)将图像的Markdown放在链接括号中：
[](https://www.fangjunyu.com)
12、URL和电子邮件地址
在尖括号中输入URL或电子邮件地址：
<URL>
<Mail>例如:
<https://www.fangjunyu.com>
<fangjunyu.com@gmail.com>
格式化链接：
我是 **[方君宇](https://www.fangjunyu.com)**.
还叫 *[FangJunyu](https://www.fangjunyu.com)*. 
13、转义字符
显示格式化Markdown文档中的文本字符时，在字符前添加反斜杠（\）。
\* 这是一个星星使用反斜杠，防止文本字符被格式化，否则显示无序列表。
还可以转移以下字符：
1、\ 反斜杠
2、` 反引号
3、* 星号
4、_ 下划线
5、{ } 花括号
6、[ ] 方括号
7、< > 尖括号
8、（）括号
9、# 井号
10、+ 加号
11、- 减号（连字符）
12、. 点
13、! 感叹号
14、| 管道
14、水平线
创建水平线，可以使用三个或多个星号（***）、破折号（—）或下划线（___）。
***---_________________为了兼容性，推荐在在水平线前后放置空格。
// 推荐写法，水平线前后放置空格
门前大桥下,
---
油锅一群鸭.
// 不推荐写法，水平线前后没有空格
快来快来数一数,
---
二四六七八.15、表格
在扩展Markdown中，可以使用竖线分隔创建表格：
| Left columns | Right columns |
| ------------- |:-------------:|
| Name | FangJunYu |
| Web | fangjunyu.com |
| Home | Rizhao |标准的最早版 Markdown（John Gruber 2004）没有表格，后来 GitHub Flavored Markdown（GFM）加了，逐渐开始普及，现在几乎所有编辑器/渲染器都支持了。
16、HTML
许多Markdown应用程序允许使用HTML标签：
<p>这是一片<b>海</b></p>但是出于安全考虑，并非所有Markdown应用程序都支持HTML，需要参考使用的Markdown应用程序文档。
注意：不要在HTML标签中使用Markdown语句：
<p>这是一片**海**</p>它不起作用。
总结
Markdown广泛用于播客和即时通讯，也用于在线论坛、写作软件、文档页面和自述文件等其他领域。
相关文章
1、Markdown Wikipedia：https://en.wikipedia.org/wiki/Markdown
2、Markdown Guide：https://www.markdownguide.org/
3、Markdown live preview：https://markdownlivepreview.com/
扩展知识
CommonMark
2012年，Jeff Atwood和John MacFarlane在内的一群人发起了Atwood所称的标准化工作。
2014年9月，Gruber反对该项目中使用“Markdown”，并将其更名为CommonMark。
由于主要问题仍未解决，1.0版规范至今仍未发布。
尽管如此，以下网站和项目采用了CommonMark：GitHub、Reddit、Stack Exchange。
Markdown Extra
Markdown还有一个变体Markdown Extra，用于PHP、Python、Ruby等语言，增加了常规Markdown不具备的功能：HTML块内的Markdown标记、表格、缩写、脚注等功能。
目前有超过十几种编程语言提供Markdown的实现，主流博客平台也有Markdown插件。
在Swift 5.6开始，官方支持在注释文档中直接写Markdown。
/// 计算两数之和
///
/// - Parameters:
/// - a: 第一个数字
/// - b: 第二个数字
/// - Returns: `a + b` 的结果
///
/// 示例:
/// ```swift
/// add(2, 3) // 5
/// ```
func add(_ a: Int, _ b: Int) -> Int {
a + b
}
