markdown语法文档

Markdown 是否用得好，判断标准不是“语法记得多”，而是源文本在不渲染时仍能读懂、渲染后结构清晰、在不同平台不会频繁失效。对技术文档、README、笔记和博客草稿，它通常比富文本更易维护；但如果需要精细排版、复杂表格或强一致样式，应评估平台限制或配合模板。 ## 标题与段落 用 `#` 到 `######` 表示六级标题，`#` 后必须留一个空格。建议一篇文档只用一个一级标题，标题层级不要跳级，例如不要从二级直接到四级。段落之间空一行；多数渲染器会把单换行合并成同一段，若必须换行，可在行尾加两个空格或使用 `
`，但应少用。标题不要用加粗文字代替，除非目标平台不支持标题语法。写完后检查目录层级，确保章节顺序与阅读路径一致。 ## 行内标记：强调、链接与代码 斜体用 `*文字*`，粗体用 `**文字**`，粗斜体用 `***文字***`，删除线通常写作 `~~文字~~`，需确认平台支持。链接写作 `[显示文字](URL "可选标题")`；图片写作 ``，替代文本应说明图片内容，而不是写“图片”。行内代码用反引号包裹，适合命令、变量、文件名和短代码。若内容本身含反引号，可用双反引号包裹。链接地址含空格时，应做 URL 编码或用尖括号包住。 ## 列表、引用与分隔线 无序列表用 `-`、`*` 或 `+` 开头，有序列表用 `1.`、`2.` 开头，标记后要加空格。嵌套列表建议统一缩进两个或四个空格，同一文档内保持一致。任务列表写作 `- [ ] 待办` 或 `- [x] 已完成`，通常属于 GFM 扩展。引用用 `>` 开头，可嵌套为 `>>`。分隔线用 `---` 或 `***` 单独成行，前后留空行；紧跟文字可能被识别为 Setext 标题。列表项包含多段时，后续段落需缩进对齐。 ## 代码块与表格 围栏代码块由三个反引号或三个波浪线开始和结束，开始后可写语言名，如 `python`、`bash`、`json`，以启用语法高亮。代码块内不要额外缩进，除非缩进属于代码本身。表格用管道符：表头 `| 列 A | 列 B |`，分隔行 `| --- | :---: |`，冒号控制对齐。单元格内避免直接写竖线，必要时转义为 `\|`。复杂表格建议改用列表或 HTML。表格前要空行，否则部分渲染器不会解析。 ## 转义与跨平台兼容 反斜杠可转义特殊字符，例如 `\*`、`\_`、`\#`、`\[`、`\]`、`\>`、`\|`。CommonMark 是较通用的基础规范；GFM 额外支持表格、任务列表、删除线和自动链接。不同平台对 HTML、脚注、数学公式、目录和锚点的支持差异较大，不能假定全部可用。提交前重点检查：标题空格、块级元素空行、列表缩进、代码围栏闭合、链接路径大小写。若文档要发布到多个平台，优先使用核心语法。 ## 写作与维护要点 先写结论，再补细节；每个文件围绕一个主题，长文按二级标题拆分。团队应统一标题层级、列表符号、代码语言标记和链接方式。仓库文档尽量使用相对链接，便于迁移；图片集中放在 `assets` 等目录，并保留替代文本。定期检查死链、失效图片和渲染差异。版本控制中，Markdown 的纯文本差异清晰，适合评审和追溯。 小结：Markdown 的语法不多，真正影响可用性的是源文本可读、渲染稳定和跨平台一致。先掌握标题、段落、强调、链接、列表、引用、代码和表格这些核心规则，再根据平台扩展功能；每次提交前在目标环境预览一次，通常就能避免大多数格式问题。