Markdown 写作技巧与最佳实践

写博客、学习笔记、README，Markdown 基本就是默认写作语言。这篇文章不只讲“Markdown 有哪些语法”，还会重点回答三件事：

• 标准 Markdown 里最常用的语法有哪些
• 写博客和笔记时，哪些写法最值得优先用
• 想让文章更好读，可以用哪些增强样式

先记一个总原则：Markdown 最重要的不是语法花样，而是让信息更容易被读者扫到、理解、复用。

标准 Markdown 高频语法

这一节讲的是通用 Markdown 能力。

标题：先把信息分层

标题最适合解决一个问题：让读者快速扫结构。

# 一级标题
## 二级标题
### 三级标题

推荐场景：

• 博客主章节
• 笔记的小节拆分
• FAQ、安装、总结这类固定模块

常见误用：

• 层级跳太快，比如 ## 后直接接 ####
• 只有标题，没有结构关系
• 一篇很短的文章拆出太多层级

更适合博客阅读的写法：

## 安装
## 使用方式
## 常见问题

不太推荐的写法：

## 安装
### 使用前准备
#### 本地环境检查
##### Node 版本确认

如果文章本身不长，层级太深反而会增加阅读负担。

强调：把重点标出来

强调语法最常见的有四种：

**加粗**
*斜体*
~~删除线~~
`行内代码`

推荐场景：

• **加粗**：标结论、关键词、注意点
• `行内代码`：标命令、变量名、文件名、接口路径
• ~~删除线~~：记录被废弃的方案或错误路径

常见误用：

• 一整段内容都加粗
• 命令、路径、接口名不用行内代码包起来
• 同一段里同时堆太多强调形式

博客和笔记里最有用的通常其实只有两种：

• 结论要点
• `技术对象`

列表：写步骤和并列项最顺手

无序列表适合写并列信息：

- 支持代码高亮
- 支持表格
- 支持任务列表

有序列表适合写步骤：

1. 安装依赖
2. 启动项目
3. 检查页面输出

推荐场景：

• 安装步骤
• 注意事项
• 功能列表
• 结论归纳

常见误用：

• 明明是步骤，却写成无序列表
• 明明是并列结论，却写成强制排序
• 列表项太长，导致一屏看不出重点

如果一条列表项已经超过两三行，通常可以考虑拆成“短标题 + 解释”。

链接和图片：增强可追溯性

[Markdown 官方指南](https://www.markdownguide.org/)
![首页效果图](../../../assets/blog/generated/markdown-tips.png)

推荐场景：

• 链接官方文档、仓库、PR、在线 Demo
• 图片展示页面效果、流程图、终端输出截图

常见误用：

• 链接文字写成“点这里”
• 图片没有说明意图
• 路径不对，构建后图片失效

更好的链接写法是：

• [Astro 内容集合文档](https://docs.astro.build/)

引用：把提醒和正文拉开

> 提示：先写结构，再补细节。

推荐场景：

• 一句话提醒
• 阶段性总结
• 原始描述或引用内容

常见误用：

• 用引用块承载整段正文
• 只是为了视觉变化，没有额外信息价值

引用块的价值不在“好看”，而在于告诉读者：这是一条应该被单独看到的信息。

代码块：技术文章最重要的语法

代码块几乎是开发者文章里最重要的阅读工具。

最基本的写法是：

```js
const greet = (name) => {
  console.log(`Hello, ${name}`);
};
```

推荐场景：

• 展示命令行操作
• 展示配置片段
• 展示代码逻辑
• 展示接口请求示例

常见误用：

• 不标语言
• 代码块太长，没有删减
• 代码前后没有解释

更适合博客阅读的顺序通常是：

1. 先说这段代码解决什么问题
2. 再给代码块
3. 最后补一句重点说明

表格：适合横向比较

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| title | string | 是 | 文章标题 |
| tags | string[] | 否 | 文章标签 |

推荐场景：

• API 参数说明
• 配置项对比
• 多方案横向比较

常见误用：

• 单元格里写大段解释
• 不同列的维度混乱
• 把顺序步骤硬塞进表格里

表格适合“对齐信息”，不适合“讲故事”。

任务列表：把状态直接写出来

- [x] 补充安装步骤
- [x] 增加代码示例
- [ ] 添加 FAQ

推荐场景：

• 发布前检查
• 学习清单
• 文章待补内容

常见误用：

• 没有状态的普通列表硬写成任务列表
• 清单太长，没有分组

分隔线：用来切换节奏

---

推荐场景：

• 正文和补充资料之间
• 教程主体和 FAQ 之间
• 主结论和参考链接之间

常见误用：

• 每个小节之间都放分隔线
• 本来靠标题就能解决，还额外用分隔线造成冗余

分隔线适合“切阶段”，不适合“装饰版面”。

技术博客和学习笔记最常用的写法推荐

真正提升阅读体验的，往往不是新语法，而是语法组合方式。

让读者快速扫结构

推荐组合：

• 标题 + 短段落
• 标题 + 列表
• 标题 + 结论句

例如：

## 为什么会报 401

先说结论：大多数情况下是因为请求没带 token。

- 未登录时直接请求接口
- token 过期但前端没刷新
- 请求头没有正确拼接

这种写法比一整段长说明更适合博客和笔记。

让技术内容更容易读

推荐组合：

• 行内代码 + 代码块
• 表格 + 简短解释
• 步骤列表 + 请求示例

例如：

执行 `npm run dev` 启动项目。

```bash
npm install
npm run dev

这里要点很简单：

- 行内代码适合点名具体对象
- 代码块适合展示完整动作
- 两者搭配比只贴大段代码更清晰

### 让重点更醒目

推荐组合：

- `引用块 + 一句话提醒`
- `任务列表 + 状态`
- `分隔线 + 新阶段`

例如：

```md
> 注意：本地图片能显示，不代表构建后路径一定正确。

这类轻提醒，在博客和笔记里都很高频。

组织一篇学习笔记

一个很稳的笔记结构通常是：

1. 问题是什么
2. 结论是什么
3. 解决步骤是什么
4. 还可以参考什么

对应 Markdown 可以这样写：

## 问题

接口为什么返回 401？

## 结论

大多数情况下是 token 缺失或过期。

## 处理步骤

1. 检查本地 token
2. 检查请求头
3. 检查接口状态码

## 参考资料

- [认证文档](https://example.com)

增强可读性的轻样式建议

这一节说的不是“新语法”，而是更适合博客和笔记的表达习惯。

emoji

适合的位置：

• 标题前做轻提示，比如“推荐”“注意”“踩坑”
• 总结区或清单区做状态标记
• 学习笔记里做分类感

例如：

• ## 推荐写法 ✅
• ## 注意事项 ⚠️
• - 笔记 📒
• - 举例子 🌰

不太推荐的用法：

• 每个标题都加 emoji
• 一段里连续塞多个 emoji
• 技术说明本身已经很复杂，还用 emoji 抢重点

更合适的思路是：emoji 是标签，不是结构。先把结构写清楚，再用 emoji 增加识别度。

统一提示词前缀

比起每次临时组织语言，更稳定的做法是统一一套提示词前缀：

• 提示
• 注意
• 推荐
• 踩坑记录
• 结论

例如：

> 注意：图片路径在本地可用，不代表发布后一定正确。

> 推荐：短段落配合列表，比大段说明更适合教程文。

统一前缀能让整篇文章的阅读节奏更稳。

用引用和分隔线控制节奏

很多人想增加“样式感”，第一反应是加很多颜色或花哨结构。其实 Markdown 里最有效的节奏工具，往往只是：

• blockquote
• hr
• 短段落
• 列表

普通写法：

这一部分讲安装，下一部分讲配置，最后再补常见问题。

更适合博客阅读的写法：

## 安装

先完成本地依赖安装。

---

## 配置

再检查环境变量和配置文件。

本站支持的增强样式写法

这一节讲的是当前博客项目额外支持的增强能力，不是标准 Markdown 本身。

提示块：article-callout

这个项目支持直接在 Markdown 里插少量 HTML，最实用的就是提示块。

写法：

<div class="article-callout">
  <p class="article-kicker">先记结论</p>
  <p>标题、列表、代码块，是技术文章里最值得优先掌握的三类写法。</p>
</div>

适合场景：

• 一句话总结
• 注意事项
• 阶段结论
• 文章开头的重点提醒

卡片网格：article-grid 和 article-card

如果你想并列展示几种能力、几类写法或几条建议，可以用卡片网格。

写法：

<div class="article-grid">
  <div class="article-card">
    <h3>标题</h3>
    <p>简短说明</p>
  </div>
  <div class="article-card">
    <h3>代码块</h3>
    <p>展示完整示例</p>
  </div>
</div>

回到主题，md常见误区与推荐搭配

常见误区

• 把 Markdown 当成语法秀场，什么都想加
• 用样式替代结构，结果文章还是不好读
• 代码块很长，但没有解释重点
• 表格、列表、引用块混用过度，阅读节奏被打散
• emoji 用得太多，反而削弱真正的重要信息

常用语法速查

可读性增强速查