VSCode Markdown预览不支持双向编辑，需配置breakOnSingleNewline、toc.levels、math.enabled等参数并避免插件冲突；换行、目录、公式、代码块问题均源于设置未生效或插件干扰。
VSCode 的 Markdown 预览本身不支持实时双向编辑（即改预览内容 ≠ 改源码），它只是只读渲染；真正高效写技术文档和笔记，关键不在“怎么打开预览”，而在于如何让 markdown.preview.breakOnSingleNewline、markdown.extension.toc.levels、数学公式、代码块高亮这些配置真正生效，且不被插件冲突干扰。
为什么预览里换行不生效？检查 breakOnSingleNewline 设置
默认情况下，Markdown 换行需两个空格或一个空行，但技术文档常需要单回车就换行（比如参数说明列表）。VSCode 原生预览靠 markdown.preview.breakOnSingleNewline 控制该行为，但它默认是 false。
- 打开设置（
Ctrl+,或Cmd+,），搜breakOnSingleNewline - 勾选它，或在
settings.json中手动加："markdown.preview.breakOnSingleNewline": true
- 注意：此设置对原生预览有效，但部分 Markdown 插件（如 Markdown All in One）会接管预览，此时需关掉插件的预览功能，否则设置不生效
目录（TOC）不自动更新？优先用 markdown.extension.toc 而非原生
VSCode 内置预览不生成目录，必须依赖插件。推荐 Markdown All in One，但它的 TOC 行为受多个配置影响：
监控一个或多个 GitCode 仓库的 PR，通过 OpenClaw Gateway 自动执行 AI 审查，发布 PR 评论，并发送钉钉和企业微信通知。
-
markdown.extension.toc.githubCompatibility：设为true才能正确解析### 标题级别（GitHub 风格） -
markdown.extension.toc.levels：默认只到3，写内核文档常需到5，设为"2-5" - 生成 TOC 快捷键是
Ctrl+Shift+P→ 输入Markdown: Create Table of Contents，不是靠保存自动刷 - 若 TOC 乱码或链接失效，检查文件路径是否含中文空格——VSCode 插件对非 ASCII 路径 TOC 锚点生成不稳定
数学公式不渲染？禁用冲突插件 + 启用 markdown.math
LaTeX 公式（如 $E = mc^2$）在原生预览中默认不支持，需插件；但多个插件（如 Markdown Preview Enhanced、Markdown+Math）会互相抢夺渲染权，导致公式变纯文本或报错 MathJax is not defined。
- 卸载所有其他 Markdown 预览类插件，只留
Markdown All in One+ 官方Markdown Preview Mermaid Support（Mermaid 也常冲突） - 在
settings.json中启用数学支持："markdown.extension.math.enabled": true
- 公式必须独占一行并用
$$...$$包裹（行内公式$...$在 VSCode 预览中支持有限，易出错） - 若仍不渲染，右键预览页 → “Open Preview to the Side” → 再右键 → “Reload Preview”，原生预览有时缓存 MathJax 加载失败
代码块没语法高亮？确认语言标识符拼写 & 关闭格式化干扰
技术文档大量依赖代码块高亮，但 ```python 渲染成白底黑字，大概率是语言 ID 错误或格式化插件覆盖了渲染逻辑。
- 语言标识符必须是 VSCode 认可的 ID，例如：
py不行，得用python；bash可以，shell多数主题不识别 - 检查是否启用了
editor.formatOnPaste或editor.formatOnType：它们可能把代码块里的缩进/引号自动改掉，破坏高亮触发条件 - 某些主题（如 One Dark Pro）对 Markdown 代码块背景色定义不全，可临时切到
Default Dark+主题验证是否主题问题 - 如果用的是远程开发（SSH/WSL），确保远程端已安装对应语言扩展（如 Python 扩展），否则本地预览无法加载语法定义
最常被忽略的一点：VSCode 的 Markdown 预览是“静态快照”，每次保存后才重新解析整个文档。这意味着 YAML frontmatter 里的 date 或自定义字段不会动态注入，也不能像 MkDocs 那样做变量替换——它终究是个轻量写作辅助，不是静态站点生成器。
