写稿、改稿、返稿这件事在技术写作、文档维护和内容协作里经常比写代码本身更耗时。Notion 提供了灵活的块编辑体验但很多人在做逐句批注时仍然习惯性地复制全文到 Word再用批注功能来回传递VS Code 是开发者最熟悉的编辑器自带 Markdown 预览与编辑能力但在更新到新版 Markdown 编辑器后很多人还没有真正把它用起来。这篇内容围绕三个关键词展开Notion 的逐块批注机制、Markdown 的编辑协作方式、VS Code 新 Markdown 编辑器的实际用法。目标不是做一个“哪个工具更强”的对比而是把批注审稿这条链路拆开讲清楚让你在 Notion 和 VS Code 之间找到一套适合自己的写作-审稿-修订流程。这篇文章适合以下几类读者经常在 Notion 里组织内容、却苦于多人批注不够精细的人习惯用 Markdown 写作但需要把文档分发给他人审阅的开发者或技术作者以及想了解 VS Code 新版 Markdown 编辑器到底新增了哪些能力、能不能替代第三方插件的人。读完本文后你会理解 Notion 的 block 数据结构与批注实现方式能按步骤在 Notion 里对单个文本块做批注也能在 VS Code 中配置出适合审稿的 Markdown 编辑环境并掌握从 Markdown 到其他格式、从本地文档到协作平台的转换思路。1. 先理解 Notion 的逐块批注为什么适合审稿而不是简单“选中文字加评论”很多人第一次用 Notion 时以为它和 Word 一样批注是针对“选中的一段文字”存在的。这个理解不算全错但没说到本质。Notion 的批注对象不是任意文本区间而是 block也就是块。你在页面上看到的每一段文字、每一个标题、每一个列表项、每一张图片底层都是一个独立的 block。批注是挂在这个 block 上的内容而不是绑定在某几个字符上。1.1 block 模型是 Notion 批注机制的技术基础Notion 页面本质上是一个 block 列表每个 block 有自己的类型、属性和内容。常见的 block 类型包括段落、标题、列表项、待办事项、引用、代码块、图片、表格、看板、日历等。当你把鼠标移动到某个段落左侧会出现一个六个点组成的拖拽手柄这个手柄对应的就是 block 的容器。批注操作的核心逻辑是你先把光标定位到某个 block 内部或者选中整个 block然后在右侧栏的 Comment 区域添加评论。此时评论会与这个 block 建立关联。如果 block 被移动批注跟着移动如果 block 被删除批注也随之消失。这个设计决定了 Notion 的批注天然是“块级”的而不是“字符级”的。理解这一点对审稿非常重要。比如你在审阅一篇技术教程时发现某个步骤描述不够清楚。在 Word 里你可以只选中“步骤三”三个字加批注但在 Notion 中更合理的做法是把“步骤三”所在的整个段落作为一个 block 来加批注因为后续修改者需要看到上下文而不只是被圈出来的几个字。注意Notion 的批注不是针对字符的富文本标注。它不像 Word 的批注那样可以在句子中间画一条红色竖线把某几个字单独框出来。Notion 的批注最小粒度是一个 block。如果你真的要批注一句话中的某个词语通常做法是把这句话单独拆成一个 block或者用加粗、高亮对词语做视觉标记再在评论里说明。1.2 Notion 批注的适用场景与边界Notion 的逐块批注适合以下场景场景是否适合原因多人协作审稿按段落给修改意见适合block 天然对应段落、列表项等完整内容单元对一句话中的某个词做精细批注不太适合批注粒度是块不能只挂在局部字符上对图片、表格、代码块提出修改意见非常适合这些元素本身就是独立 block批注位置清晰需要把批注导出为外部审阅记录一般Notion 没有原生“导出批注”功能需要自己整理多人同时编辑并实时看到批注非常适合评论采用实时同步机制与页面内容一起保存需要特别提醒的是Notion 的评论功能虽然好用但它的定位是“协作沟通”不是“正式的评审流程管理”。如果你想做严格的审稿流程比如要求每条批注必须关联一个处理状态、对应的责任人和截止日期Notion 逐块批注满足不了。这时候更好的做法是在 Notion 里做一个数据库表来管理待办或者在评论里约定固定的前缀格式比如“待修改”“已确认”。1.3 用 Talk to Notion 类似思路理解批注的交互逻辑这里提一个实际的协作习惯当你在 Notion 页面里给某个 block 添加评论后被 的人会收到通知。该 block 的右侧会出现一个小气泡图标提示这里有评论。点击后可以继续追加评论、引用其他 block或者直接输入“Done”把评论标记为已解决。在多人审稿时建议所有人遵循同一套批注规则一条评论只提一个问题。不要在一段话下面同时写格式问题、内容问题、数据问题这会让修改者很难逐条消解。必须 具体负责人。不 的评论容易被忽略因为 Notion 的通知机制依赖 和订阅。明确用前缀表示批注类型。例如“事实错误”“表述建议”“格式问题”“疑问”或者“可以忽略”。修改完成后在原评论里回复处理方式再标记已解决而不是直接删除评论。这样做可以保留完整的审稿记录。这套规则不依赖任何插件只靠 Notion 原生的 block 和评论能力就能落地比每次复制全文到 Word 再发回来高效得多。2. VS Code 新版 Markdown 编辑器到底更新了什么值得重新审视2.1 Markdown 与 Notion 在编辑体验上的本质差异Notion 的编辑体验是所见即所得你看到的就是渲染后的效果块结构隐藏得很深。而 Markdown 是纯文本的标记语言最早的设计目标是让作者关注内容把排版指令以简单的符号嵌入文本中再由解析器渲染成 HTML 或其他格式。两者各有优劣。Notion 适合快速组织内容但想导出干净的 Markdown 文件往往要借助第三方工具或者在导出后做大量清理Markdown 适合版本管理、代码仓库协作和多格式发布但纯文本编辑的即时反馈需要编辑器配合。VS Code 在这个场景中的位置比较特殊。它不是一个专门的 Markdown 编辑器而是一个通用代码编辑器但它的 Markdown 支持却足够完整甚至在某些方面比在线文档工具更适合技术写作。原因在于VS Code 的项目文件组织能力、Git 集成、快捷键体系和扩展生态让 Markdown 写作可以嵌入到程序员已有的工作流里。2.2 新版 Markdown 编辑器新增的关键能力微软在 VS Code 中持续投入 Markdown 编辑体验。较新的版本中Markdown 编辑器的变化不只是界面调整而是围绕“编写预览、导航校验、粘贴处理”等场景做了增强。需要关注的核心能力包括能力作用适用场景内置 Markdown 预览不需要装插件就能打开渲染视图Markdown 文件双击后按 CtrlShiftV 或 CtrlK VMarkdown 大纲面板根据标题层级生成文档目录长文档审稿、跳转章节编辑器和预览同步滚动编辑位置与预览位置双向联动检查长段落与标题的对应关系粘贴图片自动生成 markdown 图片语法从剪贴板粘贴图片时自动生成文件链接技术文章插图、截图说明链接、锚点、路径校验检测相对链接是否失效多文档之间互相跳转时所见即所得开关启用后编辑区显示渲染效果类似打字机模式想用纯文本写作但不希望完全是源码效果其中“所见即所得”模式WYSIWYG是很多从 Notion 转过来的用户最容易忽略的功能。打开后Markdown 语法标记会被隐藏你看到的是标题、加粗、斜体已经渲染好的效果但底层仍然是纯文本文件。这让 VS Code 在“编辑体验”上接近 Notion同时保留了 Markdown 文件本身的便携性。2.3 如何打开 VS Code 中的新 Markdown 编辑器能力要使用新版 Markdown 编辑器不需要额外安装大型扩展VS Code 自带的能力已经覆盖了日常写作。前提是确认你的 VS Code 版本不是太旧。检查方式很简单打开任意 Markdown 文件按CtrlShiftP打开命令面板输入Markdown看是否能看到以下命令Markdown: Open Preview to the SideMarkdown: Open PreviewMarkdown: Show SourceMarkdown: Toggle Code Block Highlighting如果你在命令面板里能看到这些命令说明当前 VS Code 的 Markdown 支持是完整的。如果看不到建议先更新 VS Code 到较新版本再重新打开命令面板。# 查看 VS Code 版本 code --version输出示例1.100.0 abcdef1234567890abcdef1234567890abcdef12 x64这里要说明不同的 VS Code 版本在 Markdown 编辑器细节上会有差异。比如某些版本的默认 Markdown 预览样式是浅色某些版本对 Mermaid 图表的支持需要额外配置。遇到差异时不要先怀疑代码问题而是先看版本。推荐的工作区配置可以写在项目根目录的.vscode/settings.json中让所有协作者共享同一套 Markdown 编辑体验{ markdown.preview.breaks: true, markdown.preview.fontSize: 14, markdown.preview.lineHeight: 1.6, markdown.styles: [], markdown.preview.scrollPreviewWithEditor: true, markdown.preview.scrollEditorWithPreview: true, editor.wordWrap: on, files.autoSave: afterDelay }markdown.preview.breaks控制普通换行是否渲染成br。Markdown 标准中单换行通常不换行必须空一行才是新段落但很多中文写作场景希望单个换行也能生效。打开这个配置可以在预览时更接近普通文档的表现但要注意导出 HTML 或 PDF 时行为可能不同。editor.wordWrap打开软换行避免长段落超出屏幕。scrollPreviewWithEditor和scrollEditorWithPreview让编辑区和预览区同步滚动审稿时非常实用。3. 把 Notion 和 VS Code Markdown 组合成个人审稿工作流3.1 从 Markdown 到 Notion一套可复用的协作路线如果你日常用 VS Code 写 Markdown需要把文档放到 Notion 里给同事审最直接的方式是新建 Notion 页面后往里粘贴 Markdown 内容。Notion 对粘贴 Markdown 的支持比较成熟基本规则是标题层级映射为 Notion 的标题块段落映射为段落块列表映射为项目符号列表代码块映射为代码块引用块映射为引用块。粘贴之后要做三件事检查代码块的语言标注是否保留。Notion 粘贴 Markdown 时代码块的语言标注有时会丢失变成未指定语言的代码块影响阅读时的语法高亮。检查图片链接。Markdown 中如果使用相对路径引用本地图片粘贴到 Notion 后图片不会自动上传只会保留一个失效链接。处理方式是先把图片拖入 Notion 页面或先上传到图床再使用图片 URL。检查嵌套列表。Markdown 中多层缩进的列表粘贴到 Notion 后层级关系偶尔会扁平化。需要在 Notion 中用 Tab 键调整缩进。3.2 从 Notion 到 Markdown导出时要注意哪些问题Notion 官方的导出功能支持 Markdown 格式入口是页面右上角的...菜单选择 Export格式选择 Markdown CSV。导出的结果是一个.zip压缩包里面包含 Markdown 文件和图片目录。但这个导出过程有几个值得注意的问题问题表现处理建议图片路径图片会保存在 zip 的 assets 目录Markdown 中引用相对路径解压后图片和 md 文件相对位置变化时引用会失效代码块语法高亮部分代码块导出后语言标注丢失在 VS Code 中打开后逐个检查代码块语言行内代码与链接绝大多数能正确转换注意检查含特殊字符的链接是否被转义数据库视图数据库导出为 CSV不会内嵌到 md需要单独处理数据库内容嵌套页面子页面导出为独立 md 文件主文档中保留链接不会内嵌正文因此导出后不要立即发邮件或者直接提交到 Git先在 VS Code 里打开执行一遍检查清单确认标题层级、确认代码块语言、确认图片能显示、确认表格没有断列。3.3 在 VS Code 中搭建一个审稿专用工作区审稿和日常写作的差异在于你不仅需要编辑还需要追踪改动、记录审阅意见、生成导出版本。VS Code 里可以按以下方式搭建一个最小可用的审稿工作区。目录结构示例review-workspace/ ├── README.md ├── docs/ │ ├── chapter-01.md │ ├── chapter-02.md │ └── images/ │ ├── screenshot-01.png │ └── screenshot-02.png ├── review/ │ ├── review-chapter-01.md │ └── review-chapter-02.md └── .vscode/ └── settings.json这里的思路是原稿放在docs/审稿意见放在review/图片资源集中在images/。审稿意见文件本身也是 Markdown可以和原稿放在同一个仓库里进行版本管理。每一份审稿意见可以按照下面的结构组织# Chapter 01 审稿意见 审稿人张三 日期2025-06-01 状态待修改 ## 批注清单 - [ ] 第 12 行事实错误VS Code 版本号不准确建议改为实际验证版本 - [ ] 第 18 行表述建议把“很好用”改成具体描述 - [ ] 第 24 行格式问题标题层级跳过了 H3直接到了 H4 - [ ] 第 30 行疑问这里引用的图片来源没有说明 ## 总体评价 结构清晰但第三部分的步骤不够具体建议补充命令示例和预期输出。这样的审稿意见文件天然可以被 Git 追踪也可以用 VS Code 的任务列表插件展示待办状态。同时审稿人可以直接在原 Markdown 文件里修改内容并另存为chapter-01-revised.md原稿和修订稿对比时使用 VS Code 的编辑差异功能。选中两个文件后右键Compare Selected就能看到逐行差异和代码 review 没有本质区别。3.4 用对比与合并思路处理多人审稿结果当多位审稿人各自修改了 Markdown 文件时最常见的需求是合并所有人的修改。VS Code 本身不提供复杂的多文件合并能力但与 Git 配合后这个流程会变得非常清晰。推荐的做法是每个审稿人从主分支创建自己的审稿分支。审稿修改完成后提交到自己的分支。通过 Pull Request 或 Merge Request 发起合并。合并时处理冲突逐条确认保留哪些修改。这样Notion 的逐块批注和 VS Code 的 Markdown 审稿流就形成了互补Notion 负责“沟通和确认”VS Code 负责“编辑和版本管理”。前者解决人与人之间的意见同步后者解决修改记录和版本追溯。4. 常见问题排查从“批注不见了”到“Markdown 预览不更新”4.1 Notion 批注相关的典型问题问题一批注不见了现象刷新页面后之前添加的评论全部消失或者某个 block 上的评论气泡不见了。排查顺序检查是否切换到了数据库视图而不是页面视图。如果页面被嵌入数据库或在表格视图里展示block 的评论入口可能会被隐藏。检查右上角的通知中心。Notion 的通知中心里会保留评论记录通过搜索可以找到原评论。检查 block 是否被删除。如果有人在协同时删除了整个 block评论会跟随 block 一起删除无法恢复。确认是否登录了正确的账号。Notion 的评论是带用户身份的不同账号看到的评论权限不同。问题二批注无法 同事现象在评论里输入 没有弹出成员列表。排查顺序确认对方是否已经被添加到当前页面或工作区。确认你在评论权限范围内。如果当前页面权限是“只读”评论能力可能被关闭。检查浏览器或桌面端是否为旧版本建议升级后重试。4.2 VS Code Markdown 编辑环境常见问题问题一预览不更新或显示空白现象在 Markdown 文件中输入内容预览区没有变化或者一直显示空白。排查顺序检查是否同时打开了多个 Markdown 编辑器预览可能绑定到了错误的文件。关闭所有预览重新执行Markdown: Open Preview to the Side。检查工作区配置中是否设置了markdown.styles如果配置了远端 CSS 且网络不可用预览可能加载失败。尝试用命令面板重新加载窗口Developer: Reload Window。问题二粘贴图片提示 local download failed现象在远程开发场景中使用 VS Code Remote 连接到远端服务器粘贴图片时提示error: localdownloadfailed (未能下载 vs code 服务器(failed to fetch))。原因分析VS Code 的 Markdown 编辑器在粘贴图片时需要先把剪贴板内容转交给扩展或者编辑器处理在 Remote 场景下这个转交过程依赖 VS Code 客户端和服务器之间的通信。当网络不稳定或服务器端下载失败时就会报这个错。处理建议检查 VS Code 客户端和远程服务器之间的网络连接。将图片手动保存到本地再通过文件拖拽方式放入远程目录。改用图片上传组件或图床工具直接把图片上传后插入 URL。问题三Markdown 表格复制到其他工具后格式错乱现象在 VS Code 里看到的表格正常复制到 Notion 或 Word 后列对齐错乱或者表格被拆成了纯文本。原因分析Markdown 表格本质上是一段带管道符和分隔线的纯文本。不同工具在粘贴时会做不同的解析有的能识别成表格有的只能识别为文本。遇到这个问题时不要直接在两个工具之间复制粘贴建议使用 Pandoc 等转换工具做格式转换。# 将 Markdown 转换为 Word 文档 pandoc chapter-01.md -o chapter-01.docx # 将 Markdown 转换为 HTML pandoc chapter-01.md -o chapter-01.html如果本机没有安装 Pandoc也可以先在 VS Code 中打开 Markdown 预览再从预览页面中复制渲染后的表格粘贴到目标工具时通常能保留表格结构。4.3 排查清单从写作到审稿的完整顺序无论遇到什么问题建议按下面清单逐层检查1. 文件本身是否完整 - Markdown 文件是否存在特殊字符导致解析失败 - 是否使用了中文全角符号导致格式判断错误 2. 编辑器配置是否正确 - 是否打开了错误的工作区 - 工作区 settings.json 是否被其他配置覆盖 3. 预览绑定是否正确 - 是否只有一个 Markdown 文件处于活动状态 - 预览窗口是否指向了旧文件 4. 路径引用是否有效 - 图片路径、链接路径是否相对当前文件位置正确 - 中文文件名是否导致路径解析异常 5. 网络与远程环境是否正常 - 远程开发场景下是否有下载失败或同步延迟 - 在线图床或 CDN 是否可访问 6. 工具版本是否过旧 - VS Code 是否低于支持新版 Markdown 编辑器的版本 - Notion 桌面端或浏览器扩展是否需要更新5. 扩展方向Markdown 渲染、版本管理与自动化流程5.1 在 VS Code 中增强 Markdown 渲染能力虽然 VS Code 内置的 Markdown 预览已经够用但做技术文档或课程讲义时有些渲染需求是内置能力覆盖不了的数学公式渲染需要启用markdown.math.enabled或安装支持 KaTeX 的扩展。Mermaid 类图表需要安装扩展或在预览中使用 Markdown Preview Mermaid Support 类似组件。自定义 CSS 样式可以通过markdown.styles配置让预览展示更接近最终发布效果。{ markdown.styles: [./style/custom.css] }这里要注意markdown.styles里的 CSS 路径是相对工作区根目录的。自定义样式适合调整预览时的字体、标题颜色、代码块背景等但不会影响最终发布平台的样式因为发布平台自己有一套主题。5.2 Markdown 与自动化内容管道的组合如果你经常把 Markdown 转成 Word、PDF、HTML推荐用一个脚本或者配置文件管理这套转换流程。最简单的方案是写一个 Makefile 或 shell 脚本把固定命令串起来# convert.sh #!/bin/bash set -e for file in docs/*.md; do base$(basename $file .md) pandoc $file -o dist/${base}.docx --toc pandoc $file -o dist/${base}.html --standalone done echo 转换完成输出目录dist/脚本里用set -e表示任一步骤出错就停止避免后续文件在错误状态下继续处理。--toc参数让生成 Word 时自动插入目录。--standalone参数让生成的 HTML 是完整文档而不是缺失 head 和 body 的片段。5.3 从逐块批注到结构化评审数据库如果你的评审流程越来越复杂可以考虑在 Notion 里建一个“审稿任务”数据库而不是只在页面评论区讨论。这个数据库的字段可以包括字段类型说明评审主题标题对应的章节或文档名称原文位置文本标记原文中的章节或行号批注类型单选事实错误、表述建议、格式问题、疑问责任人人员 某个成员处理状态单选待修改、修改中、已解决截止日期日期便于跟踪进度原评论链接URL指向 Notion 页面对应 block 的链接在 Notion 中你可以把页面里的某个 block 右键复制链接这个链接能定位到具体的 block。把链接放到数据库的“原评论链接”字段里就能从数据库记录跳到具体的批注位置。这样一来“批注”不再局限于页面内评论而可以变成结构化任务支持排序、筛选和统计。5.4 新手建议不要一开始就追求“最完美工作流”技术写作的协作方式没有标准答案。有人习惯在 Notion 里完成所有内容创建和批注有人则希望把 Markdown 文件当成唯一事实来源。对于新手建议分阶段尝试阶段目标实践建议第一阶段熟悉块级批注把一个章放入 Notion练习添加评论、 同事、标记已解决第二阶段熟悉 Markdown 基础在 VS Code 里写一篇技术笔记掌握标题、列表、代码块、表格语法第三阶段实现双工具转换把 Markdown 传入 Notion或者把 Notion 页面导出为 Markdown第四阶段建立版本管理把 Markdown 放入 Git 仓库用分支和合并代替来回发文件第五阶段优化审稿流程根据团队习惯设计批注前缀、状态管理或数据库评审表不要一开始就同时引入 Pandoc、Git、自定义 CSS、Notion 数据库等所有工具。每次只引入一个变量确认它解决了实际问题再进入下一步。6. 参考资料与后续学习路径如果你希望深入学习相关能力可以围绕下面几个方向继续实践Markdown 语法本身掌握标准语法与扩展语法之间的差异尤其是表格、删除线、任务列表、代码块语言标注和脚注。Notion 的 API 与数据库能力通过 Notion API 可以把页面内容拉取到本地也可以把本地 Markdown 推送到 Notion 页面实现更自动化的同步链路。Pandoc 的转换能力Pandoc 是 Markdown 生态里最重要的格式转换工具支持多种输入输出格式值得系统性学习。Git 协作流程在多人审稿场景中分支、合并、冲突解决能力比编辑器本身更重要。技术写作工具的变化很快但底层的需求始终是内容要清晰、修改要有记录、意见要能被追踪。Notion 的逐块批注解决的是“意见挂在哪里”的问题VS Code 的 Markdown 编辑器解决的是“如何高效编辑和保留历史”的问题。把两者组合起来你就能在轻量协作和严谨版本管理之间获得平衡。下一篇文章如果继续这个方向可以深入讲解如何通过 Notion API 把 Notion 页面同步到本地 Git 仓库实现“在线批注、本地修订、自动合并”的完整闭环。