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 就够用了。剩下的,多写几篇文章自然就熟了。