markdown 基本语法

判断一个文档是否适合用 Markdown，先看两个条件：内容是否以结构化文字为主，是否需要长期纯文本维护和版本对比。只要满足这两点，Markdown 通常比可视化排版更稳定；如果涉及严格分页、精确印刷或复杂批注，则应改用专用排版工具。

标题与段落

标题用 `#` 表示，数量对应级别：`#` 一级、`##` 二级、`###` 三级。一个文档通常只保留一个一级标题，正文分节从二级标题开始，层级不要跳跃，例如一级标题下不应直接出现三级标题。 段落之间必须空一行。不要用连续空格或 Tab 模拟缩进，这在 Markdown 中不产生预期缩进，反而可能被当作代码块处理。 适用场景：README、说明文档、博客正文、笔记。 注意事项：标题符号后要加一个空格，例如 `## 标题`，而不是 `##标题`。

强调与引用

• 粗体：`文本` 或 `文本`
• 斜体：`文本` 或 `_文本_`
• ~~删除线~~：`~~文本~~`，属于 GFM 扩展，CommonMark 不一定支持

引用用 `>`，可用于提示、摘录或风险说明。引用可以嵌套，例如： > 这是一条提示。 > > 这是嵌套引用。 使用建议：同一句内不要同时使用粗体和斜体过多，重点优先用粗体；删除线若需跨平台兼容，应确认目标平台支持 GFM，或改用 HTML `<del>`。

列表与任务列表

无序列表统一用 `-`，有序列表用 `1.`、`2.`。嵌套列表缩进 2 到 4 个空格，前后留空行。列表标记后要加一个空格。

• 无序项一
• 嵌套项
• 无序项二

1. 第一步
2. 第二步
3. 子步骤

任务列表是 GFM 扩展：

• [ ] 待办事项
• [x] 已完成事项

注意：并非所有平台都支持任务列表，如果文档需要跨平台阅读，任务列表可能显示为普通列表，此时应避免把关键信息只放在勾选状态里。简单清单可写紧凑列表；复杂内容建议每个列表项之间空行，以保持渲染稳定。

链接与图片

行内链接格式：`[文字](url "标题")`。标题参数可选，鼠标悬停时显示。链接文字应能独立说明目标，避免“点击这里”。同一链接多处使用时，可采用参考式，减少重复： [示例链接][1] [1]: https://example.com "示例" 图片格式：``。替代文字必须准确描述图片内容，图片加载失败时由替代文字说明信息。本地图片应先放到文档可访问的目录中，并使用相对路径，例如：  选择建议：简单配图用 Markdown 图片；需要指定宽高、对齐或更复杂布局时，可用 HTML，不强求纯 Markdown。

代码与代码块

行内代码用单个反引号包住，适用于命令、文件名、参数等，例如 `pip install markdown`。如果行内代码本身包含反引号，可用双反引号包围：`` ` `` 表示一个反引号字符。 代码块使用三个反引号围栏，并在开头标注语言： python def greet(name): return f"Hello, {name}" 代码块内的 Markdown 符号不需要转义，会按原样显示。语言标注有助于高亮，但不同渲染器支持的语言范围不同；如果语言标注失效，通常只影响高亮，不影响显示。适用于示例代码、配置文件、命令行输出等场景。

表格与转义

GFM 表格用竖线分隔，第二行为对齐控制行： | 列一 | 列二 | 列三 | | --- | :---: | ---: | | 左对齐 | 居中 | 右对齐 | 对齐行使用 `---`、`:---:`、`---:` 分别表示左对齐、居中、右对齐。单元格内若出现竖线，需写作 `\|`，否则会被当成列分隔符。列数必须前后一致，否则渲染会错乱。 需要显示 Markdown 符号本身时，用反斜杠转义，例如 `\*` 显示星号，`\#` 显示井号。简单数据适合表格；数据复杂、包含大量合并单元格或需要复杂样式时，建议改用 HTML 表格或独立数据文件。

小结

Markdown 的核心优势不是排版能力，而是结构清晰、可读性高、便于版本管理。实际使用中，优先保持标题层级不跳、列表缩进统一、链接和图片可访问。需要跨平台兼容时，优先使用 CommonMark 子集；在 GitHub、多数笔记软件和现代编辑器中，表格、删除线、任务列表等 GFM 扩展通常可以安全使用，但仍需检查目标环境是否支持。