markdown语法菜鸟教程

Markdown 的核心不是“排版”，而是用少量符号给纯文本加结构。判断是否学会，标准只有一个：别人拿到你的 `.md` 文件，不依赖你的编辑器，也能看懂层级、链接和代码。先掌握标题、列表、链接、代码块四类语法，就能覆盖大多数笔记、README 和技术文档。 ## 先认准基准：CommonMark 与 GFM Markdown 有多个方言，新手最容易卡在“我这里能渲染，你那里不行”。比较稳妥的选择是：通用写作按 CommonMark，提交到 GitHub、Gitee 等平台时按 GFM（GitHub Flavored Markdown）检查。 - CommonMark 规定基础语法，兼容性较好。 - GFM 在基础语法上增加表格、任务列表、删除线、自动链接等。 - Typora、Obsidian、VS Code 等工具可能默认开启扩展语法，导出前应预览。 - 如果文档要给多人看，优先使用基础语法，少用平台专属写法。 判断标准：换一个编辑器或平台后，标题、列表、代码块是否仍能正常显示。若不能，说明你用了过多扩展语法。 ## 标题与段落：先搭骨架 标题用 `#` 表示，一级标题一个 `#`，二级两个 `##`，最多到六级。井号后必须加空格，例如 `## 安装步骤`。不要跳级使用，也不要在同一篇文章里堆多个一级标题。 段落之间要空一行。很多新手写： 第一行 第二行 渲染后可能仍是一段。想让它们成为两段，应写成： 第一行 第二行 如果只想换行不另起段落，可在行尾加两个空格或反斜杠，但不建议依赖这种写法。统一用空行分段，兼容性最好。 ## 强调、列表与引用：表达层次 强调语法中，`*斜体*` 或 `_斜体_` 表示斜体，`**粗体**` 表示粗体，`***粗斜体***` 表示粗斜体。中文里星号前后是否加空格不影响语义，但建议保持视觉清爽。 列表分无序和有序： - 无序列表用 `-`、`*` 或 `+`，符号后加空格。 - 有序列表用 `1.`、`2.`，数字后加空格。数字不必连续，但建议按顺序写。 - 嵌套列表缩进 2 或 4 个空格，同一文档内保持一致。 - 任务列表写作 `- [ ] 待办` 和 `- [x] 已完成`，通常需要 GFM 支持。 引用用 `>`，例如 `> 注意：这是提示`。可嵌套为 `>>`。列表和引用前后最好空一行，否则容易和段落粘连。 ## 链接、图片与分隔线：接入外部内容 链接格式是 `[显示文字](https://example.com)`，可加标题：`[显示文字](https://example.com "说明")`。图片格式是 ``。替代文字不要省，图片加载失败或读屏软件会用到它。 长文可用引用式链接： [Markdown 指南][guide] [guide]: https://example.com 分隔线单独一行写 `---` 或 `***`，前后空一行。若紧跟文字，可能被解析成标题或列表。本地图片建议用相对路径，例如 `./images/demo.png`，并把图片一起提交到仓库，避免外链失效。 ## 代码与表格：技术写作高频 行内代码用反引号包裹，例如 `` `npm install` ``。如果内容本身含反引号，可用双反引号包裹。代码块用三个反引号开始和结束，开头可标注语言： python print("hello") 表格用竖线分列，第二行用 `---` 分隔： | 语法 | 用途 | | --- | --- | | `#` | 标题 | | `-` | 无序列表 | 对齐可写成 `:---`、`:---:`、`---:`。表格单元格内换行通常需要 `
`，但应少用。特殊符号想原样显示，可在前面加反斜杠，如 `\*`、`\_`、`\#`、`\|`。 ## 常见坑与收尾建议 最常见的问题不是语法难，而是空格和空行：`#标题` 可能不生效，`-项目` 可能不是列表，段间不空行可能导致块级元素合并。提交前先预览，再用 markdownlint 等工具检查。 写作时优先保证结构清楚：标题层级合理，列表只列同类信息，链接可点击，代码可复制。不要混用太多方言，也不要为了排版塞入大量 HTML。真正影响阅读的，是内容组织和可维护性，而不是花哨效果。先写清楚，再调格式。