Markdown 完整语法指南
Markdown 是一种用纯文本就能排版文档的写法:不依赖鼠标点按钮,只要会打字,就能写出带标题、列表、代码块、表格的漂亮文章。这个博客的所有文章都是用 Markdown 写的,学会它,你就能自由地在这里写作。
写在前面:本博客的约定
每篇文章是 content/posts/ 下的一个 .md 文件,开头有一个“信息头”(front matter),告诉博客这篇文章的标题、日期和标签:
---
title: 文章标题
date: 2026-08-15
tags: [教程, Markdown]
description: 一句话介绍这篇文章。
---
本博客开了“单换行即换行”的选项:普通文本直接回车就会显示为换行;但段落之间还是建议空一行,阅读更清晰。
一、基础语法
1. 标题
在文字前面加 #,一个 # 是一级标题,两个是二级,最多到六级:
# 一级标题(一般给文章大标题用)
## 二级标题(正文里最常用的小节标题)
### 三级标题
#### 四级标题
标题和正文之间最好空一行。
2. 段落与换行
段落之间用空行隔开。想强制换行,直接回车即可(本博客设置);如果要在别的编辑器里换行,可以在行尾加两个空格:
这是第一段。
这是第二段,和第一段之间空了一行。
3. 强调:加粗、斜体、删除线
**加粗**:文字两边各加两个星号
*斜体*:文字两边各加一个星号
***加粗又斜体***:两边各加三个星号
~~删除线~~:两边各加两个波浪号
`行内代码`:用一对反引号包起来
效果:加粗、斜体、加粗又斜体、删除线、行内代码。
4. 列表
无序列表用 -、* 或 +,有序列表用数字加点:
- 无序项一
- 无序项二
1. 有序项一
2. 有序项二
嵌套列表:在下一行前面缩进两个空格(或一个 Tab):
- 第一层
- 第二层
- 第三层
任务清单:- [ ] 表示未完成,- [x] 表示已完成:
- [x] 学会标题
- [x] 学会列表
- [ ] 学会表格
任务清单效果:
- 学会标题
- 学会列表
- 学会表格
5. 链接
[链接文字](https://example.com)
[带提示的链接](https://example.com "鼠标悬停时显示的文字")
<https://example.com>(直接写网址会自动变成链接)
给链接起个名字、后面统一引用(适合长文章里多处引用同一个链接):
可以去[我的 GitHub][github]逛逛。
[github]: https://github.com/mlidog
效果:打开我的 GitHub 和自动链接 https://example.com。
6. 图片


图片说明 在图片加载失败时会显示,所以别留空。想控制图片大小,可以用 HTML 的 <img> 标签:
<img src="图片地址" alt="说明" width="400">
效果(用博客的头像演示):
7. 引用
段落开头加 >,引用可以嵌套:
> 这是引用。
>
> > 这是嵌套在里面的引用。
效果:
这是引用。
这是嵌套的引用。
8. 分割线
单独一行写三个或更多 -、*、_:
---
效果(下面这条线就是分割线):
注意:分割线那一行上面要空一行,否则会被当成标题。
9. 代码
一句话里提到代码用行内代码;整段代码用三个反引号包起来,开头还可以注明语言,让代码高亮:
```js
console.log("你好,世界");
```
支持的语言包括 js、python、html、css、json、bash 等,写上语言名就有对应高亮。如果代码里本身有反引号,把外层围栏加长一个就行,比如内层三个、外层四个。
10. 表格
用竖线分隔列,第二行用 --- 分隔表头:
| 语法 | 作用 | 难度 |
| ---- | ---- | ---- |
| `#` | 标题 | 简单 |
| `**` | 加粗 | 简单 |
| 表格 | 排列表格 | 中等 |
列的对齐方式可以通过冒号控制:
| 左对齐 | 居中 | 右对齐 |
| :----- | :--: | -----: |
| 内容 | 内容 | 内容 |
效果:
| 语法 | 作用 | 难度 |
|---|---|---|
# |
标题 | 简单 |
** |
加粗 | 简单 |
| 表格 | 排列表格 | 中等 |
11. 转义
想显示星号、井号这些特殊符号本身,在前面加反斜杠:
\# 这不是标题,只是井号
\*不是斜体\*
常用转义:\*、\#、\-、\_,反引号本身用两个反引号包住:\`。
二、进阶技巧
组合使用
列表、引用、代码块可以互相嵌套。引用里放代码块:
> 一段引用:
>
> ```js
> console.log("引用里的代码");
> ```
列表里放代码块时,代码块要比列表项多缩进一层:
- 第一步
```js
console.log("缩进后的代码");
```
Emoji
直接粘贴 emoji 就行,比如 🌙 ☀️ 🎉。本站不支持 :smile: 这种代码写法,也不支持脚注。
用 HTML 兜底
Markdown 允许嵌入 HTML。想让某一行居中、插入视频、改颜色,都可以用 HTML 实现:
<center>这一行居中</center>
不过日常写作尽量少用,保持纯 Markdown 更清爽。
三、一篇完整的示例文章
把上面的语法串起来,一篇标准文章的源码长这样:
---
title: 我的第一篇完整文章
date: 2026-08-15
tags: [生活, 随笔]
description: 用示例展示一篇完整文章的写法。
---
## 今天做了什么
今天学会了 **Markdown**,感觉离*自由写作*又近了一步。
## 三件小事
1. 写了第一篇完整文章;
2. 给博客加了一个新栏目;
3. 学会了[引用链接][参考]。
## 今日代码
```python
print("hello, world")
```
## 今日收获
| 项目 | 完成 |
| ---- | ---- |
| 阅读 | ✅ |
| 写作 | ✅ |
> 写作的意义,是把想法变成看得见的东西。
[参考]: https://example.com
对照一下就能看到:标题、段落、列表、链接、代码块、表格、引用,一篇文章该有的都有了。
四、常见坑
- 标题没生效:
#和文字之间要有空格,#标题是不行的; - 分割线变成标题:
---上方没有空行时会变成二级标题,记得空一行; - 列表里的代码块乱掉:代码块要比列表项多缩进一层;
- 表格没显示:表格的每一行竖线数量要一致,表头下面必须有
---那一行; - 图片不显示:检查图片地址对不对、说明文字别留空;
- 粘贴过来格式乱了:很多编辑器会把空格自动转换,建议在纯文本模式下粘贴。
掌握这些,Markdown 就够用了。剩下的,多写几篇文章自然就熟了。
评论
昵称不填时会自动分配「访客-xxxx」,可以随时改成自己喜欢的名字,浏览器会自动记住;邮箱和网址选填。想删除评论?点击评论区右上角的「小齿轮」,登录管理员密码后即可在线删除。