markdown表格需严格遵循三步法：先写表头（如|姓名|部门|入职时间|），再写分隔行（如|---|---|---|），最后写数据行；分隔行缺失是最常见渲染失败原因；对齐方式通过冒号控制（:---左、:---:居中、---:右）；前后空行、内容转义\|、扩展启用等细节影响兼容性。

要在 Markdown 文档中准确呈现结构化数据，必须用纯文本写出可被解析器识别的表格语法，漏掉分隔行或错放冒号会导致整张表格无法渲染。

基础表格三步构建法

第一步：输入表头，用竖线 | 分隔各列，首尾建议保留 | 提高可读性。例如：|姓名|部门|入职时间|

第二步：紧接表头下方，写分隔行，每列下方至少填三个连字符 -，且必须用 | 对齐列数。错误示例：|---|----|（第二列多一个 - 但没用 | 隔开）→ 正确应为 |---|---|---|

第三步：在分隔行下方逐行添加数据行，每行格式与表头一致，内容可含空格、数字、中文，【分隔行缺失是表格不显示的最常见原因】。

控制列对齐方式

方法一：左对齐列

在分隔行对应列的连字符左侧加冒号，写作 :---。例如：|:---|:---:|---:| 中第一列为左对齐。

方法二：居中对齐列

文档整理技能 (convert-markdown)

基于 MarkItDown 实现 PDF、Word、PPT、Excel、图片、音频等文件批量转 Markdown，适用于文档数字化、知识库构建、内容提取等场景。

下载

在连字符两侧都加冒号，即 :---:。这种写法对数值型标题（如“完成率”“评分”）特别友好，视觉上更稳重。

方法三：右对齐列

在连字符右侧加冒号，写作 ---:。适合金额、日期、序号等右端对齐更符合阅读习惯的内容。

实战排版技巧

① 表格前后务必留空行，否则可能被当作普通段落渲染成一行乱码。

② 列宽无需手动对齐，但手动空格对齐源码能大幅降低后期维护成本——尤其当表格超过5列时，错一格竖线就可能让整行偏移。

③ 遇到内容含竖线 | 的情况，必须转义为 \|，否则解析器会误判为新列起点。比如写“Windows \| macOS”就得写成 Windows \| macOS。

④ GitHub、Typora、Obsidian 均支持原生表格，但部分静态站点生成器（如 Hugo 默认配置）可能禁用表格扩展，此时需确认已启用 tables 扩展。