markdown使用技巧

Markdown 写作的核心原则是：先保证结构清晰，再考虑视觉样式。真正影响效率的不是记住多少语法，而是能否在输入阶段就避免混乱嵌套和多余标记。以下按写作顺序给出可执行技巧。 ## 一、标题和段落：固定层级，不跳级 适用场景：长文档、笔记、README、技术说明。 - 一级标题一个文档通常只出现一次；正文分节从 `##` 开始，逐级使用 `###`、`####`。 - 不要因为觉得字号太大就跳过二级直接用三级，这会导致部分平台生成目录或折叠结构时层级错乱。 - 同一层级标题保持并列关系：如果 `## 安装` 下有 `### Windows`，就不应在同一层再出现 `## 配置` 下直接跳到 `####`。 段落之间用空行分隔。需要换行但不开始新段落时，可以在行尾加两个空格或使用 `
`，但普通写作尽量少用强制换行，交给渲染器处理。 可执行步骤： 1. 先写出全部二级标题，确认文档骨架。 2. 再为每个标题补 1～3 个短段落。 3. 发布前检查：标题是否跳级，同级标题是否表达同一层级。 注意事项：标题中尽量不堆叠行内代码、链接和强调；标题要能单独成立，扫描时即可知道下段内容。 ## 二、列表：优先无序，只有顺序重要才用有序 适用场景：步骤、要点、待办。 - 无序列表统一用 `-`，不要混用 `*` 和 `+`，避免源码看起来杂乱。 - 有序列表只用于顺序不可变的内容，例如“1. 打开设置；2. 输入名称”。如果只是罗列功能点，用无序列表即可。 - 嵌套列表缩进 2 到 4 个空格，并且前后留空行，避免部分解析器把嵌套内容粘连到上一项。 示例： - 第一层 - 第二层 - 第三层 任务列表适合记录待办，写法为 `- [ ] 未完成`、`- [x] 已完成`。注意：并非所有 Markdown 平台都支持任务列表，导出到纯 Markdown 环境时可能显示为普通列表。 判断标准：如果读者改变列表顺序也不会影响理解，就不要用 `1.`。 ## 三、代码与引用：行内用反引号，整块用围栏 适用场景：技术文档、命令说明、配置示例。 - 行内代码用单个反引号包裹，例如 `print("hello")`。正文里提到文件、命令、参数时，优先使用行内代码，例如 `config.yaml`、`--verbose`。 - 多行代码用三个反引号围栏，并标注语言，例如： python print("hello") 语言标注有利于高亮，但即使不高亮也保留可读性。 - 如果行内代码中还需要包含反引号，应使用双反引号包裹；更稳妥的做法是避免在行内代码里再嵌套反引号，或改用代码块。 引用用 `>`，适合放提示、注意事项或摘录。多个引用段连写时，每个段落前都要加 `>`。嵌套引用用 `>>`，但不要超过两层，否则可读性下降。 注意事项：代码块前后留空行；围栏语言的名称用小写，如 `bash`、`json`、`python`，不要随意写成 `Bash` 或 `py`，部分渲染器只识别常见小写别名。 ## 四、链接、图片和表格：先检查可读性 适用场景：文档中的外部资源、截图、对比信息。 链接写法：`[显示文字](地址 "标题")`。标题可选，但地址不要直接裸露，尤其长链接会破坏段落节奏。显示文字要说明目标，例如 `[配置示例](config.md)`，不要写“点击这里”。 图片写法：``。替代文字必须描述图片内容，不能为空，否则屏幕阅读器和图片加载失败场景下没有信息。相对路径优于绝对路径；如果发布到不同平台，需要确认图片资源是否随文档一起上传。 表格用 GFM 表格： | 工具 | 适用场景 | 注意 | | --- | :---: | --- | | 标题 | 分节 | 不跳级 | | 列表 | 要点 | 不混用符号 | 表格列数要保持一致；单元格内需要出现竖线时写作 `\|`。复杂归纳关系不适合用表格，宁可改写为列表。 步骤：写完表格后在预览模式检查对齐线和列数；如果某列内容过长，考虑把表格改为小标题加段落。 ## 五、转义与兼容：知道什么时候要写反斜杠 适用场景：需要显示 Markdown 符号本身，而不是触发格式。 Markdown 中这些符号有特殊含义：`*`、`_`、`#`、`-`、`+`、`. `、`>`、`[ ]`、`( )`、`!`、`\`、反引号。正文里如果要显示符号本身，需要在其前面加反斜杠，例如 `\*` 显示为 `*`。 但并不是所有地方都需要转义。例如 URL 中的下划线通常不需要转义；代码块和行内代码中的符号也不需转义。过多转义会降低源码可读性。 平台差异需注意： - CommonMark 是基础规范，GFM 在表格、任务列表、删除线、自动链接上有扩展。 - 表格、任务列表、删除线属于 GFM 扩展，并非所有 CommonMark 环境都支持。 - 自动链接在 GFM 下可以直接写 URL，但普通 CommonMark 环境可能不会自动识别，手动使用 `[URL](URL)` 更稳妥。 判断标准：发布前确认目标平台是否支持 GFM。如果文档可能离开当前平台，优先使用最基础语法，或把扩展语法控制在表格和任务列表范围内。 ## 小结 Markdown 技巧的核心不是符号记忆，而是结构约束。写作时优先固定标题层级、列表类型和代码围栏；排版时再检查表格对齐、链接可读性和转义。按“先骨架、后内容、再预览”的流程，可以减少大部分后期返工。对不支持的扩展语法，回到段落、列表和链接这些基础元素，通常已经足够。