Markdown 写作指南：让文章结构清晰可读

TL;DR

Markdown 是写博客核心工具。掌握标题层级、代码块、表格和脚注，写技术文章不再费力。本文覆盖所有常用语法，并附实战技巧。

为什么先学 Markdown

写博客最难不是技术，是把话说清楚。Markdown 的设计哲学与此高度一致：让作者专注于内容，而不是排版。

学习 Markdown 的收益是长久。GitHub README、技术文档、Notion、飞书笔记—这些地方都用 Markdown。学会一处，处处能用。

基础语法

标题

用 # 的数量表示层级，最多六层：

# 一级标题（文章标题）
## 二级标题（大章节）
### 三级标题（小节）
#### 四级标题
##### 五级标题
###### 六级标题

博客文章通常用二到三级标题。标题要具体，“安装 Node.js” 比 “步骤一” 更有用。

段落与换行

Markdown 中，两个段落之间空一行即可。不要用 <br> 标签或空格堆砌。

第一段文字。

第二段文字。

第三段文字。

行末两个空格 + 换行，可以产生段内换行（但大多数场景不需要）。

列表

无序列表用 - 或 *（两者在渲染后没有区别，统一风格即可）：

- 第一项
- 第二项
  - 子项（前面加两个空格）
  - 子项
- 第三项

有序列表用数字加点：

1. 第一步
2. 第二步
3. 第三步

列表前后留空行，列表项之间不需要空行。

代码

行内代码用反引号 `code`，适合包裹命令、变量名、文件名。

代码块用三个反引号，开头注明语言：

```javascript
const greeting = 'Hello, world!';
console.log(greeting);
```

常用语言标识：javascript、typescript、python、bash、css、html、json、yaml、markdown。

链接与图片

[链接文字](https://example.com)
![图片描述](https://example.com/image.png)

图片的 ! 不能漏。图片描述要有实际内容，不要留空或写”图片”。

引用

> 这是一段引用。
> 可以多行，会渲染为一个整体。

引用常用于：

• 别人说过话
• 文档中重要说明
• 代码注释引用

表格

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| A   | B   | C   |
| D   | E   | F   |

表格对齐在第二行 --- 中控制：

| 左对齐 | 居中 | 右对齐 |
|:------|:----:|------:|
| text  | text | text  |

进阶语法

脚注

这句话有一个脚注[^1]。

[^1]: 这是脚注内容，会显示在文章底部。

脚注适合放参考资料和补充说明，不打断正文阅读。

水平线

三个 - 或 * 产生水平分隔线：

---

不建议在文章中间使用水平线—用标题代替分层，更符合屏幕阅读器语义。

任务列表

- [x] 安装 Node.js
- [x] 创建 Astro 项目
- [ ] 配置域名

GitHub 和多数博客平台支持，但要注意兼容性。

目录

Astro博客会在正文开头自动生成目录（TOC）。你要做是让标题结构合理，不要跳级、不要在标题里加无意义符号。

写作技巧

标题即摘要

好的标题让读者扫一眼就知道这段在讲什么：

# 不好：关于 Node.js 的一些介绍
# 好：安装 Node.js 并验证版本

代码块前面加说明

不要只丢代码不加解释：

安装 Astro 命令行工具：

```bash
npm install -g astro

而不是：

npm install -g astro

（猜这是干什么的）

表格代替长列表

超过5项的列表，考虑用表格呈现，阅读体验更好。

代码块的文件名注释

在代码块第一行注明文件名：

```javascript title="utils/format.js"
export function formatDate(date) {
  return new Intl.DateTimeFormat('zh-CN').format(date);
}
```

常见错误

错误	问题	修正
标题跳级（# 直接跳到 ###）	目录结构混乱	按顺序使用标题层级
列表项里直接写多段文字	渲染结果不整齐	每段单独一行，缩进保持
图片 ! 漏写	只显示链接文本	检查 Markdown 预览
代码块没有语言标识	无语法高亮	添加 ```javascript 等
中文和英文之间没有空格	排版不整齐	”安装 Node.js” vs “安装 Node.js”

在 Astro 中使用 Markdown

Astro 的 Markdown 文件支持 frontmatter（文件顶部的元数据）：

---
title: '文章标题'
description: '文章描述'
pubDate: 2026-05-22
tags: ['标签1', '标签2']
---

正文从这里开始。

frontmatter 的字段由博客主题定义。云图札记支持 title、description、pubDate、category、tags、series、seriesOrder。

博客扩展语法

博客在标准 Markdown 基础上额外支持四种扩展语法，详见 博客写作语法指南：

文本高亮 ==重点文字== → 渲染为 重点文字（黄色背景），适合标记核心概念和关键结论。

Emoji 快捷 :emoji_name: → 渲染为 🚀 / 💡 / ⚠️ 等，比直接输入 Emoji 更具可读性。

Callout 容器 :::tip / :::warning / :::bug 等 → 醒目的提示框，适合技巧提示、警告、注意事项、问题思考。

脚注 [^1] 语法 → 自动渲染为带编号的脚注，适合放参考资料和补充说明。

延伸阅读

• Markdown 官方语法说明
• Astro Markdown/MDX 文档
• 从零搭建 Astro 博客并部署到 Cloudflare Pages
• 博客写作语法指南 — 所有扩展语法的完整演示与对照表