markerdown语法

标题里的“markerdown”通常按 Markdown 理解。判断一份 Markdown 文档是否合格，可以看三点：不渲染时源文本仍可读；渲染后标题、列表、代码层级清楚；复制到目标平台后不出现大面积破版。满足这三点，语法就用对了；只追求花哨扩展，往往会增加迁移成本。 ## 一、先确定语法边界：基础优先，扩展按平台启用 Markdown 分基础语法和扩展语法。基础语法包括标题、段落、粗体、斜体、列表、引用、链接、图片、行内代码、代码块和分隔线；扩展语法包括表格、任务列表、删除线、脚注、数学公式等。 选择建议： - 写 README、工单、聊天消息、邮件草稿时，优先只用基础语法，兼容性最好。 - 写博客、产品文档、知识库时，确认平台支持后再用表格、任务列表和脚注。 - 不确定时，先看平台预览结果；若复制到纯文本后出现大量符号，说明该语法不适合当前场景。 - 不要混用 HTML 与 Markdown 实现同一效果，除非平台明确要求。 ## 二、标题与段落：建立层级，避免渲染合并 标题用 `#` 到 `######` 表示，`#` 后加一个空格。一般只用二至四级，文章大标题由后台或模板生成，正文从二级或三级开始。不要用加粗代替标题，否则目录、锚点和阅读器无法识别。 段落之间空一行。连续文本若没有空行，很多解析器会合并为同一段。需要换行但不分段时，可在行尾留两个空格，或使用平台支持的 `
`；不过从可维护性看，直接分段通常更稳。 检查标准：预览中标题层级是否连续，是否从三级跳到五级；目录能否正确生成；长段落是否被空行切开。 ## 三、列表、引用与强调：让信息可扫描 无序列表用 `-`、`*` 或 `+`，有序列表用 `1.`。同一文档尽量统一符号。嵌套列表缩进两到四个空格，但不要混用 Tab 和空格，否则不同平台显示不一致。 引用用 `>`，适合摘录、提示和注意事项。引用可以嵌套，但层级过深会降低可读性。强调用 `**粗体**` 表示关键结论，用 `*斜体*` 表示术语或语气，用反引号表示行内代码、文件名和命令。 注意事项： - 粗体不要整段使用，否则重点失效。 - 行内代码中的特殊符号通常不会被解析，适合写变量、路径和命令。 - 任务列表写作 `- [ ]` 和 `- [x]`，但它属于扩展语法，发布前要确认平台支持。 ## 四、链接、图片与代码：兼顾可维护与安全 链接写作 `[显示文字](URL)`，图片写作 ``。替代文字不是装饰，它影响无障碍阅读和图片加载失败时的提示。链接文字应描述目标，不要写“点击这里”。 代码分两种：行内代码用一对反引号，代码块用三个反引号开头和结尾，并尽量标注语言，例如 `python`、`bash`、`json`。如果代码本身包含三反引号，可改用四个反引号围栏。 可执行建议： - 内部文档优先用相对路径，迁移仓库时不易失效。 - 外部链接发布前检查是否可访问，避免死链。 - 不要粘贴密钥、令牌、内网地址、个人手机号等敏感信息；示例用占位符。 - 代码块内保持原格式，不要为了排版手工加空格。 ## 五、表格、转义与校验：处理边界情况 表格适合字段少、对比关系明确的场景。基本写法是表头行、分隔行、内容行，各列用竖线分隔。列数不宜过多，移动端通常难以阅读。对齐方式通过分隔行中的冒号控制，例如左对齐、居中、右对齐。 需要显示 Markdown 符号本身时，用反斜杠转义，例如 `\*`、`\_`、`\#`。常见故障包括：中文全角符号导致语法不识别；列表前缺少空行；缩进不一致；标题 `#` 后漏空格；链接地址含空格未编码。 发布前按这个清单检查： 1. 预览中标题、列表、代码块是否正常。 2. 链接和图片是否可打开。 3. 表格在窄屏是否溢出。 4. 复制到目标平台后是否破版。 5. 是否包含不该公开的信息。 ## 小结 Markdown 的价值在于用简单标记表达结构，而不是替代排版软件。优先掌握标题、段落、列表、引用、链接、图片、代码和表格这些高频语法；扩展语法按平台启用。写作时保持符号统一、空行清楚、链接可维护，发布前做一次预览和迁移检查。这样即使平台不同，源文本仍然可读，渲染结果也稳定。