markdown all in one 和 markdown preview enhanced 是 vs code 编写 markdown 的必备插件：前者补全目录生成、格式化等底层能力，后者支持 mermaid、latex、导出 pdf 等高级预览功能，二者共存无冲突但需正确配置路径、命令与参数。
Markdown All in One 必装，不是“可选”而是“默认启用”
它不是锦上添花的插件，而是 VS Code 写 Markdown 时缺失的底层能力补丁。没装它，Create Table of Contents、Format Document、Toggle Bold 这些命令根本不存在——原生编辑器只提供基础语法高亮和简单预览。
安装后立刻生效，无需重启：搜索 Markdown All in One（作者 Yu Zhang），点击安装即可。注意别误装同名但非官方的分支版本，认准 GitHub 仓库地址 https://gitcode.com/gh_mirrors/vs/vscode-markdown。
- 自动补全触发条件很实际：输入
##后按Tab，不是空格；输入- [ ]回车，才识别为任务列表 - 目录生成默认插入位置是光标所在行，不是文件开头——如果光标在末尾，
TOC就会插到最底下，得手动剪切上去 -
Ctrl+Shift+P输入命令时，名称带空格，必须输全Markdown All in One: Create Table of Contents，缩写或漏掉冒号会找不到
Preview Enhanced 补足原生预览的硬伤
VS Code 原生预览不支持 Mermaid 流程图、LaTeX 数学公式、双向滚动同步，也不支持导出 PDF 或 HTML。Markdown Preview Enhanced 是唯一能稳定覆盖这些需求的插件，尤其适合写接口文档、系统设计稿这类含图表和公式的场景。
它和 Markdown All in One 共存无冲突，但需手动启用预览：右键 Markdown 文件 → Open Preview to the Side，或用快捷键 Ctrl+K V（Windows/Linux）/Cmd+K V（macOS）。
- Mermaid 渲染依赖本地 Node.js 环境，若报错
mermaid not found，需全局安装：npm install -g mermaid-cli - 数学公式渲染用的是 KaTeX，不是 MathJax，所以
$$...$$和\[...\]都支持，但$...$（行内）必须前后紧贴文字，中间不能有空格，否则不触发 - 导出 PDF 时中文可能乱码，需在设置里加配置：
"markdown-preview-enhanced.enableChineseExport": true
toc.levels 控制目录深度，别让三级标题塞进 TOC
默认 toc.levels 是 1..6，意味着所有 # 到 ###### 都进目录——但实际文档中，### 及以下多为细节说明，放进 TOC 反而干扰导航。建议显式设为 "2..4"，只保留二级到四级标题。
这个配置写在 settings.json 里，作用域可以是用户级，也可以是工作区级（推荐后者）：项目根目录下 .vscode/settings.json 中加一行：
"markdown.extension.toc.levels": "2..4"
- 值必须是字符串格式，写成
2..4，不是数组[2,3,4]，也不是数字4 - 修改后不用重启，但已有 TOC 不会自动重刷——得手动运行一次
Update Table of Contents - 如果某节标题想彻底排除（比如“致谢”“附录”），在标题上方加注释：
<!-- omit from toc -->
图片路径别用拖拽，统一走 assets/ 目录
直接拖图片进编辑器，VS Code 默认生成相对路径如 ，但一旦文档挪动位置或换人协作，路径就断。真实项目里应强制走 assets/ 子目录，且路径全部小写、无空格、用连字符分隔。
设置方法：在项目根目录建 assets/ 文件夹，然后在 .vscode/settings.json 加：
"markdown.extension.image.previewPath": "./assets"
- 插入图片时用
Ctrl+Shift+P→Markdown: Insert Image，路径会自动补全为./assets/xxx.png - 预览时若图片不显示，先确认
assets/和图片文件都在 Git 工作区里，而不是被.gitignore忽略了 - 绝对路径（
/assets/）在本地预览能用，但导出 HTML/PDF 会失效，必须用相对路径./assets/
真正卡住人的从来不是“有没有插件”，而是插件装了但没配对参数、路径设错、或者混淆了两个插件各自的命令入口。比如 Update Table of Contents 是 Markdown All in One 的命令，Export to PDF 是 Preview Enhanced 的功能——混用就会找不到。
