Markdown 从入门到精通：语法、规范与写作技巧

Markdown 的目标不是“排版软件”，而是用尽量少的标记，让内容在不同平台上都保持可读、可迁移、可协作。

这篇文章按“从入门到精通”的顺序讲清三件事：

语法：你要会写、写得对。
规范：你要写得像“文档”，而不是“聊天记录”。
技巧与工具：你要写得快、写得稳、好维护。

1) 认识 Markdown：它解决什么问题

Markdown 适合：

写博客、写技术笔记、写项目文档、写 README
与 Git 配合做版本管理（可 diff、可 review、可回滚）
跨平台迁移（本地、GitHub、语雀/飞书/Notion、博客系统）

Markdown 不擅长：

复杂的专业排版（例如学术期刊级的版式控制）
“所见即所得”的精细布局（需要 HTML/CSS 或专门排版工具）

2) 入门语法（必会）

2.1 标题

1
2
3

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

建议：

一篇文章尽量只有一个 #（文章标题通常由平台生成，正文从 ## 开始更稳）
标题层级不要跳（## 后面直接用 #### 会让目录结构变乱）

2.2 段落与换行

Markdown 里“换行”和“换段”不同：

换段：空一行
强制换行：行尾加两个空格（很多平台支持）

1
2
3

第一段。

第二段（中间空了一行）。

2.3 强调：加粗、斜体、删除线

1
2
3

**加粗**
*斜体*
~~删除线~~

建议：统一用 **加粗**，不要混用 __加粗__。

2.4 列表：无序、有序、任务清单

无序列表：

1
2
3

- 一条
- 另一条
  - 子项

有序列表：

1 2	`1. 第一步 2. 第二步`

任务清单（不少平台支持）：

1 2	`- [x] 已完成 - [ ] 未完成`

2.5 引用（blockquote）

1 2	`> 这是一段引用。 > 可以多行。`

常见用途：

引用定义/原文
写“结论/注意事项”

2.6 链接

行内链接：

1	`[Hexo 官网](https://hexo.io/)`

引用式链接（适合长文档，便于维护）：

[Hexo 官网][hexo]
[Markdown 指南][md]

[hexo]: https://hexo.io/
[md]: https://www.markdownguide.org/

2.7 图片

基础写法：

1	`![替代文本](https://example.com/image.png)`

建议：

替代文本 不要空，至少写“截图/流程图/示意图”，利于可访问性与搜索
图片建议本地托管或走稳定 CDN，避免外链挂掉导致“破图”

在 Hexo 中常见的“本地图片”路径（示例）：

1	`![首页截图](/img/posts/home.png)`

2.8 代码：行内代码与代码块

行内代码：

1	用 `git status` 查看状态。

代码块（强烈建议标注语言，利于高亮与阅读）：

1 2	```bash git status


如果你的代码块里还要写三引号，可以用四引号包住外层（部分平台支持），或改用缩进式代码块。

---

### 2.9 分隔线

```md
---

常见用途：章节分割、TL;DR 与正文分割。

3) 进阶语法（常用扩展）

不同平台的 Markdown “扩展能力”不完全一致。下面这些在多数场景都可用，但建议发布前在目标平台预览一次。

3.1 表格（最容易写错）

最小可用表格：

| 列1 | 列2 |
|---|---|
| a | b |
| c | d |

对齐：

1
2
3

| 左对齐 | 居中 | 右对齐 |
|:---|:---:|---:|
| a | b | c |

最常见的错误：

表头有 N 列，但分隔行不是 N 个 ---，会导致“看起来像表、实际不是表”
单元格里有 | 没转义，导致列错位（可用 \|）

3.2 脚注（部分平台支持）

1
2
3

这里有一个脚注[^1]。

[^1]: 脚注内容。

如果目标平台不支持脚注，你可以用“引用式链接 + 参考资料”替代。

3.3 折叠（HTML 写法，兼容性高）

<details>
  <summary>点击展开</summary>
  <p>折叠内容。</p>
</details>

3.4 目录（TOC）

许多博客主题会自动生成目录，不一定需要你手写。但在纯 Markdown 场景里，常见几种做法：

让平台自动生成（最省事）
用插件/编辑器生成 TOC
手写“导航段落”（例如：入门/进阶/技巧/附录）

4) 写作规范：让 Markdown 变成“可维护文档”

4.1 统一风格（最小规范）

建议你固定一套风格，长期收益很高：

标题：中文标题尽量短，避免堆叠“：：：”
列表：统一用 - 作为无序列表符号
中英文混排：英文/数字两侧留空格（例如：使用 Git 管理）
代码与命令：用行内代码包起来

4.2 结构模板（可直接复用）

## TL;DR
- 结论 1
- 结论 2

## 背景
为什么写这篇？

## 方案/步骤
分点说明，每步给可执行例子。

## 常见坑
列出错误现象 → 原因 → 修复。

## 参考资料
- 链接 1

4.3 链接与引用：优先“可追溯”

技术文章建议做到：

结论给出来源（论文/文档/官方链接）
引用用原文链接，避免“二手引用”失真
关键版本信息写清楚（例如某工具在某版本后变更行为）

5) Hexo 写作加成：Front-matter 与常用字段

在 Hexo 里，一篇文章通常会在开头写 YAML Front-matter：

---
title: 标题
date: 2026-06-01 10:00:00
categories:
  - 技术
tags:
  - Markdown
comments: true
---

常见字段（是否生效取决于主题/插件）：

title：标题
date：发布时间
updated：更新时间
categories / tags：分类与标签
comments：是否开启评论
permalink / slug：自定义 URL（需要时再用）

6) 进阶技巧：写得快、写得稳

6.1 先写结构，再填内容

写长文时，先把标题骨架搭好：

TL;DR
背景
方案/对比
实战步骤
常见坑
参考资料

这样你不会写着写着“跑题”，也便于后续补充。

6.2 少用“花哨语法”，多用“稳定语法”

为了迁移与长期可维护，建议优先使用：

标题、列表、引用、表格、代码块、链接、图片

谨慎使用：

依赖特定平台的提醒块/提示块语法
过度复杂的 HTML（后期很难维护）

6.3 文档可读性清单（发布前自检）

标题层级正确，目录结构清晰
表格列数一致，渲染正常
链接没有 404
图片有替代文本
代码块语言正确，命令可复制执行

7) 常见问题（FAQ）

Q1：为什么我写的表格没有变成表格？

最常见原因：分隔行 |---|---| 的列数和表头列数不一致；或表格中出现了未转义的 |。

Q2：为什么代码块没高亮？

通常是没标注语言：

1 2	```js console.log('hi')


---

## 8) 速查表（收藏版）

```txt
标题：      # ## ###
加粗：      **text**
斜体：      *text*
删除线：    ~~text~~
引用：      > text
无序列表：  - item
有序列表：  1. item
链接：      [name](url)
图片：      ![alt](url)
代码：      `code`
代码块：    ```lang
表格：      |a|b| + |---|---|
分隔线：    ---

技术

#Markdown #写作 #文档

Markdown 从入门到精通：语法、规范与写作技巧

https://www.pcboy.com.cn/2026/06/01/Markdown-从入门到精通/

作者

chituer

发布于

2026年6月1日

许可协议

MySQL 8 新特性盘点：从功能升级到常用 SQL 示例上一篇

大模型概念大全：全景图、时间线与部署路线（含术语索引）下一篇