给文档提修改意见是每个技术人躲不掉的工作。你在微信里回一句“第三部分好像有问题”对方只能全文搜索“第三部分”在哪里你在 Word 里批注互动体验又像回到了上个世纪。这也是为什么越来越多团队开始用 Notion它的每个段落都是一个独立的块审稿人可以直接在那一块上评论作者原地回复、逐条解决体验和给 GitHub PR 提 review 几乎一样。但很多程序员真正落笔写文档时最顺手的工具不是在线文档而是 VS Code。Markdown 属于纯文本格式天然适合放在 Git 仓库里做版本管理代码块高亮、表格渲染、目录跳转都是现成的能力。VS Code 内置的 Markdown 编辑器则把“左边编辑、右边预览”的写作体验直接放进了每天写代码的同一个窗口。这篇文章不打算争论 Notion 和 VS Code 谁更强而是要讲清楚一条真实可用的工作流用 VS Code 的 Markdown 编辑器完成初稿用 Notion 的逐块批注完成审稿最后再回到 Markdown 定稿。读完你会知道逐块批注到底怎么用VS Code 的 Markdown 编辑器应该怎么配置以及这两个工具之间如何衔接。1. 这篇文章真正要解决的问题先说一个判断传统文档审稿的最大痛点不是“沟通效率低”而是“审稿意见没有锚点”。用微信沟通意见和上下文完全割裂作者要把一段几秒的语音自行翻译成具体修改动作既费时又容易理解偏差。用 Word 批注精确度提高了一些但多人协作、版本同步、移动端查看的体验都不够好。用普通在线文档可以做到段落级评论但很多在线文档的编辑器和技术人习惯的 Markdown 工作流是脱节的。本文要解决的就是这三类问题让审稿意见可以精确定位到具体段落。让技术写作环境回到 Markdown 和代码库的熟悉节奏。让“写作—评审—修改—定稿”的流程有可追踪的完整记录。这条工作流适合的人也很明确需要写技术方案、架构设计、接口文档的程序员。需要给团队文档做 review 的技术负责人。需要改论文、给同学或同事反馈意见的研究生和产品经理。想把手写笔记、临时草稿迁移到 Markdown 体系的人。如果以上任意一条命中这篇文章都值得读完文中的操作可以直接照着做不需要额外购买工具也不需要复杂的部署。2. 先对齐三个概念Markdown、块、Markdown 编辑器2.1 Markdown 不是编程语言是给写作者用的纯文本格式Markdown 是一种轻量级标记语言核心思想是用一组简单符号表达文档结构。#表示标题-表示列表表示引用反引号包裹代码。因为本质是纯文本任何编辑器都能打开Git 可以精确跟踪每一次改动程序员不需要额外工具就能直接阅读和修改。比如下面这段内容# 订单导出方案 ## 背景 当前订单导出全部走同步接口数据量大时响应很慢。 ## 优化方向 - 增加异步任务 - 拆分导出文件在浏览器中渲染出来就是一个带层级标题和列表的普通文档。这种“纯文本写、随时渲染”的特性让 Markdown 成了技术写作的事实标准。2.2 Notion 中的“块”是什么Notion 的页面不是一整张“纸”而是由无数个“块”堆叠组成的。一个块可以是一个段落、一个标题、一个列表项、一张图片、一个代码块或一个提示框。输入文字时每次回车产生的新段落本质上就是一个新的块。逐块批注就是在“块”的粒度上添加讨论。它不等于整篇文档的评论而是把评论锚定在具体内容上。这一点和 GitHub PR review 的“在某一行上评论”非常像只是把“代码行”换成了“文档块”。2.3 VS Code 的 Markdown 编辑器VS Code 是一款代码编辑器但它内置了完整的 Markdown 支持。新建一个.md文件VS Code 会识别为 Markdown 文档提供语法高亮、标题折叠、代码块高亮、预览等功能。不需要额外安装专门的写作软件一个 VS Code 就能完成编辑、预览、版本管理的闭环。需要说明的是VS Code 的 Markdown 支持不是某个新版本凭空出现的能力而是长期迭代积累的结果。对没用过的人来说它确实像一个“新编辑器”因为很多人并不了解里面有多少细节可以调。维度Word 批注Notion 逐块批注GitHub PR review微信口头反馈意见锚点段落/文字块代码行无讨论历史较弱强强几乎无移动端体验一般好一般方便但不专业与 Markdown 融合无部分强无技术支持弱强强无这张表最关键的差异在“意见锚点”这一行。3. 为什么“逐块批注”对审稿这么重要3.1 审稿的本质是精准反馈想象一个真实场景你提交了一份 5000 字的技术方案Leader 看完后说“这几个方案你对比一下第三部分的关系型数据库选型有点问题。”你只能先翻到第三部分再逐个读取“关系型数据库选型”那一节猜对方指的是哪一句。逐块批注把这一过程彻底简化了。审稿人不需要再描述“在哪里”只需要在对应块上点一下“添加评论”输入意见。意见自动锚定到那个块作者点开评论就看到具体位置和上下文。信息从“作者主动猜测”变成“读者被动接收”沟通成本大幅下降。3.2 评论区是线程化讨论不是一次性留言Notion 的每条评论都会形成一条讨论线程作者可以在原位置回复也可以 相关成员要求确认。同一个块的多个评论会汇总显示审稿人可以随时把已经确认的评论标记为 Resolve。这样一篇文档的评审状态一目了然还有几条未解决评论、每条评论在哪个块、负责人是谁。这套体验和 GitHub 的 Review 流程高度相似对开发团队来说几乎没有学习成本。如果团队里有人做过代码评审带文档评审会非常快。3.3 对论文、对外文档同样有效写论文时导师说“绪论的贡献点写得太笼统”你可以在 Notion 里把绪论拆成几个小块导师直接对“贡献点”块写意见你改完再回复。对外输出产品文档、运营方案时批注让参与评审的人针对各自专业的部分提意见而不是在文档末尾堆一大段“整体意见”。所以逐块批注真正改变的不是“能不能评论”而是“评论能不能被精准定位、跟踪和收敛”。这是传统文档工具长期没有解决好的问题也是 Notion 在这个场景下值得被认真对待的原因。4. 环境准备VS Code 安装与 Notion 账号准备4.1 安装 VS CodeVS Code 官方提供 Windows、macOS、Linux 三个平台的安装包。Windows 下建议选择 User Installer不需要管理员权限安装后直接在当前用户下使用。如果希望免安装也可以下载 zip 包解压运行Code.exe然后把解压目录下的bin文件夹加入系统 PATH这样终端里就能直接使用code命令。安装完成或解压完成后打开终端执行code --version如果能看到版本号说明code命令已经可用。如果你是在终端里从项目目录启动可以用code .用 VS Code 打开当前目录这是打开项目最常见的方式。4.2 安装 Markdown 相关扩展VS Code 内置能力已经够用但结合扩展体验更好。终端执行code --install-extension yzhang.markdown-all-in-one code --install-extension davidanson.vscode-markdownlint第一个扩展提供自动格式化、目录生成、表格对齐等能力第二个扩展是 Markdown 规范检查器能帮你提前发现格式问题。这两个扩展在 Markdown 写作场景里属于标配组合。4.3 Notion 账号准备Notion 支持网页版和桌面客户端。注册时如果遇到“你是什么身份”的选项选择学生、个人或团队都可以选错不影响后续功能不需要为此重新注册。如果你一开始选了学生后来发现不是学生也不用担心这只是用来做功能引导的不会锁定你的账户类型。登录后建议先创建一个空白页面把最近正在写的文档粘贴进去作为后续批注实验场。这里要提醒一点Notion 是海外服务使用前请确保当前网络环境可以正常访问官方网页和客户端。本文只讨论正常使用场景下的功能操作。5. Notion 逐块批注实操像代码 review 一样审稿5.1 添加批注在 Notion 页面中把鼠标悬停在任意一个段落块上块的右侧会出现拖拽手柄和图标。点击图标菜单里就能看到“添加评论”入口。如果没有看到也可以选中块后在块的右键菜单里找到评论入口。点击后页面右侧会展开评论区输入你的意见然后发布。评论会锚定到当前块审稿人和作者都能看到这条评论挂在哪个块上。5.2 回复、提及与解决作者打开同一页面会在对应块旁边看到评论气泡。点击气泡进入评论区在下方输入框里回复即可。如果想通知同事输入再选择成员对方会在通知中心收到提醒。评论内容可以是一句话也可以附带待办比如“这里需要补充性能数据我 一下建模组的同学”。每条评论线程最后都可以点击 Resolve 标记为已解决。已解决的评论不会消失而是折叠归档方便后续追溯。5.3 用 Notion API 把批注自动化如果团队想把“机器人审稿”“自动打点评论”引入工作流可以通过 Notion API 创建评论。这个能力来自官方开放接口和人工添加评论是同一套数据模型。使用前需要两步准备在 Notion 官方的集成管理页面新建一个集成获得 Token。在目标页面右上角点击...选择“连接”把刚才创建的集成添加进来授予页面权限。然后用 curl 创建一条评论curl -X POST https://api.notion.com/v1/comments \ -H Authorization: Bearer $NOTION_TOKEN \ -H Notion-Version: 2022-06-28 \ -H Content-Type: application/json \ --data { parent: { page_id: 你的页面ID }, rich_text: [ { type: text, text: { content: 这里需要补充性能测试数据 } } ] }NOTION_TOKEN从环境变量读取页面 ID 是页面 URL 中最后一个斜杠后的一串字符。如果请求成功接口会返回创建好的评论对象。真实项目中更推荐用 Python、Node.js 等语言封装这个 API把评论写入流程和内部的 CI 或消息机器人结合起来。5.4 批注后的协作流程在实际团队协作中批注建议配合以下流程使用审稿人开始评审前先明确文档目标和评审范围。遇到问题直接在对应块上添加评论一条评论只聚焦一个问题。如果多个问题在同一块使用多条评论不要写成长篇大论。作者修改后在评论下补充说明不要静默删除评论。处理完的评论统一 Resolve最后归档评审记录。这套流程和代码评审高度相似团队里如果有做过 code review 的人带起来非常快。6. VS Code 中把 Markdown 编辑器用好6.1 新建 Markdown 文件并打开预览在 VS Code 中新建一个review.md输入内容后按CtrlK V会在右侧打开 Markdown 预览按CtrlShiftV则单独打开预览标签页。这是 VS Code 内置的默认快捷键不需要额外配置。预览区会实时渲染标题、列表、表格、代码块滚动时和编辑区联动。对于写作场景来说这套体验已经非常接近专门的 Markdown 编辑器。6.2 用 settings.json 调优 Markdown 编辑体验VS Code 的配置都集中在 settings.json 中。对 Markdown 写作建议加入以下配置{ markdown.preview.fontSize: 16, markdown.preview.lineHeight: 1.7, markdown.preview.breaks: true, editor.wordWrap: on, [markdown]: { editor.fontSize: 14, editor.lineHeight: 1.8, editor.wordWrap: on, editor.quickSuggestions: { comments: off, strings: off, other: off } }, markdownlint.config: { MD013: false } }配置含义markdown.preview.fontSize/lineHeight控制预览区的字号和行高长时间阅读更舒服。markdown.preview.breaks让换行在预览中直接生效符合中文写作习惯。[markdown]编辑器区块让 Markdown 文件在编辑时不自动换行同时关闭代码块外的干扰性补全。markdownlint.config中关闭MD013行长限制因为中文技术文档经常会写较长的自然段。修改 settings.json 后立即生效不需要重启。6.3 设计一份技术评审稿模板下面是一份技术方案评审稿的 Markdown 模板结构上覆盖了背景、方案、数据库、代码和评审清单# 技术方案评审稿订单导出服务 作者张三 评审人李四 / 王五 状态待评审 ## 1. 背景与目标 当前订单导出全部走同步接口数据量大时响应很慢目标是将导出任务改造成异步任务。 ## 2. 总体方案 - 新增导出任务表 - 通过消息队列触发异步处理 - 导出完成后发送通知 ## 3. 数据库设计 | 字段 | 类型 | 说明 | | --- | --- | --- | | task_id | varchar | 任务 ID | | status | int | 任务状态 | | file_url | text | 导出文件地址 | ## 4. 核心代码 java public class OrderExporter { public void export(String orderId) { // TODO: 补充导出逻辑 } } ## 5. 评审清单 - [ ] 确认订单量级 - [ ] 确认导出格式 - [ ] 确认失败重试策略这份模板的核心不是排版漂亮而是把评审人需要关注的信息提前结构化暴露出来背景、方案、数据表、代码位置、清单。即使审稿人只看 Markdown 渲染后的预览也能快速进入状态。6.4 VS Code 写 Markdown 和 Notion 写文档怎么分工很多人的困惑是既然 Notion 也能写 Markdown为什么还要用 VS Code更合理的分工是初稿和重写用 VS Code评审和协作用 Notion。在 VS Code 里写 Markdown可以享受本地保存、Git 版本管理、与代码库同一环境等优势写技术方案时可以直接引用项目中的真实代码路径。在 Notion 里利用逐块批注功能让团队成员参与评审评论区完整记录讨论过程。定稿后把 Notion 批注全部 Resolve再回到 Markdown 仓库归档。如果想减少迁移成本可以直接在 Notion 里新建页面、粘贴 Markdown 内容Notion 会自动识别大部分语法。这个方法适合只需要协作评审的文档但对于要长期维护、要进 Git 仓库的文档VS Code Markdown 更合适。6.5 扩展Markdown 与代码开发工作流结合对程序员来说VS Code 的 Markdown 编辑器和代码工作流的结合才是真正的增量。比如技术方案放在 Git 仓库的docs/目录PR 里附带文档改动评审人可以在 PR review 中看到 Markdown diff。代码示例直接写在 Markdown 的代码块中语法高亮、缩进、注释都遵循代码规范。目录树、正则搜索、批量替换这些 VS Code 原生能力在处理长文档时比在线文档编辑器更顺手。这也是为什么“VS Code 安装教程”“VS Code 配置教程”一直是热门搜索。很多人并不是要深度定制 IDE而是希望把 VS Code 用成一个足够顺手的写作和开发工具Markdown 恰好是两者之间的桥梁。7. 常见问题与排查思路问题现象可能原因排查方式解决方案按CtrlK V没有反应快捷键冲突或当前文件不是.md文件确认文件后缀和当前焦点切换到.md文件在快捷键
给文档提修改意见是每个技术人躲不掉的工作。你在微信里回一句“第三部分好像有问题”对方只能全文搜索“第三部分”在哪里你在 Word 里批注互动体验又像回到了上个世纪。这也是为什么越来越多团队开始用 Notion它的每个段落都是一个独立的块审稿人可以直接在那一块上评论作者原地回复、逐条解决体验和给 GitHub PR 提 review 几乎一样。但很多程序员真正落笔写文档时最顺手的工具不是在线文档而是 VS Code。Markdown 属于纯文本格式天然适合放在 Git 仓库里做版本管理代码块高亮、表格渲染、目录跳转都是现成的能力。VS Code 内置的 Markdown 编辑器则把“左边编辑、右边预览”的写作体验直接放进了每天写代码的同一个窗口。这篇文章不打算争论 Notion 和 VS Code 谁更强而是要讲清楚一条真实可用的工作流用 VS Code 的 Markdown 编辑器完成初稿用 Notion 的逐块批注完成审稿最后再回到 Markdown 定稿。读完你会知道逐块批注到底怎么用VS Code 的 Markdown 编辑器应该怎么配置以及这两个工具之间如何衔接。1. 这篇文章真正要解决的问题先说一个判断传统文档审稿的最大痛点不是“沟通效率低”而是“审稿意见没有锚点”。用微信沟通意见和上下文完全割裂作者要把一段几秒的语音自行翻译成具体修改动作既费时又容易理解偏差。用 Word 批注精确度提高了一些但多人协作、版本同步、移动端查看的体验都不够好。用普通在线文档可以做到段落级评论但很多在线文档的编辑器和技术人习惯的 Markdown 工作流是脱节的。本文要解决的就是这三类问题让审稿意见可以精确定位到具体段落。让技术写作环境回到 Markdown 和代码库的熟悉节奏。让“写作—评审—修改—定稿”的流程有可追踪的完整记录。这条工作流适合的人也很明确需要写技术方案、架构设计、接口文档的程序员。需要给团队文档做 review 的技术负责人。需要改论文、给同学或同事反馈意见的研究生和产品经理。想把手写笔记、临时草稿迁移到 Markdown 体系的人。如果以上任意一条命中这篇文章都值得读完文中的操作可以直接照着做不需要额外购买工具也不需要复杂的部署。2. 先对齐三个概念Markdown、块、Markdown 编辑器2.1 Markdown 不是编程语言是给写作者用的纯文本格式Markdown 是一种轻量级标记语言核心思想是用一组简单符号表达文档结构。#表示标题-表示列表表示引用反引号包裹代码。因为本质是纯文本任何编辑器都能打开Git 可以精确跟踪每一次改动程序员不需要额外工具就能直接阅读和修改。比如下面这段内容# 订单导出方案 ## 背景 当前订单导出全部走同步接口数据量大时响应很慢。 ## 优化方向 - 增加异步任务 - 拆分导出文件在浏览器中渲染出来就是一个带层级标题和列表的普通文档。这种“纯文本写、随时渲染”的特性让 Markdown 成了技术写作的事实标准。2.2 Notion 中的“块”是什么Notion 的页面不是一整张“纸”而是由无数个“块”堆叠组成的。一个块可以是一个段落、一个标题、一个列表项、一张图片、一个代码块或一个提示框。输入文字时每次回车产生的新段落本质上就是一个新的块。逐块批注就是在“块”的粒度上添加讨论。它不等于整篇文档的评论而是把评论锚定在具体内容上。这一点和 GitHub PR review 的“在某一行上评论”非常像只是把“代码行”换成了“文档块”。2.3 VS Code 的 Markdown 编辑器VS Code 是一款代码编辑器但它内置了完整的 Markdown 支持。新建一个.md文件VS Code 会识别为 Markdown 文档提供语法高亮、标题折叠、代码块高亮、预览等功能。不需要额外安装专门的写作软件一个 VS Code 就能完成编辑、预览、版本管理的闭环。需要说明的是VS Code 的 Markdown 支持不是某个新版本凭空出现的能力而是长期迭代积累的结果。对没用过的人来说它确实像一个“新编辑器”因为很多人并不了解里面有多少细节可以调。维度Word 批注Notion 逐块批注GitHub PR review微信口头反馈意见锚点段落/文字块代码行无讨论历史较弱强强几乎无移动端体验一般好一般方便但不专业与 Markdown 融合无部分强无技术支持弱强强无这张表最关键的差异在“意见锚点”这一行。3. 为什么“逐块批注”对审稿这么重要3.1 审稿的本质是精准反馈想象一个真实场景你提交了一份 5000 字的技术方案Leader 看完后说“这几个方案你对比一下第三部分的关系型数据库选型有点问题。”你只能先翻到第三部分再逐个读取“关系型数据库选型”那一节猜对方指的是哪一句。逐块批注把这一过程彻底简化了。审稿人不需要再描述“在哪里”只需要在对应块上点一下“添加评论”输入意见。意见自动锚定到那个块作者点开评论就看到具体位置和上下文。信息从“作者主动猜测”变成“读者被动接收”沟通成本大幅下降。3.2 评论区是线程化讨论不是一次性留言Notion 的每条评论都会形成一条讨论线程作者可以在原位置回复也可以 相关成员要求确认。同一个块的多个评论会汇总显示审稿人可以随时把已经确认的评论标记为 Resolve。这样一篇文档的评审状态一目了然还有几条未解决评论、每条评论在哪个块、负责人是谁。这套体验和 GitHub 的 Review 流程高度相似对开发团队来说几乎没有学习成本。如果团队里有人做过代码评审带文档评审会非常快。3.3 对论文、对外文档同样有效写论文时导师说“绪论的贡献点写得太笼统”你可以在 Notion 里把绪论拆成几个小块导师直接对“贡献点”块写意见你改完再回复。对外输出产品文档、运营方案时批注让参与评审的人针对各自专业的部分提意见而不是在文档末尾堆一大段“整体意见”。所以逐块批注真正改变的不是“能不能评论”而是“评论能不能被精准定位、跟踪和收敛”。这是传统文档工具长期没有解决好的问题也是 Notion 在这个场景下值得被认真对待的原因。4. 环境准备VS Code 安装与 Notion 账号准备4.1 安装 VS CodeVS Code 官方提供 Windows、macOS、Linux 三个平台的安装包。Windows 下建议选择 User Installer不需要管理员权限安装后直接在当前用户下使用。如果希望免安装也可以下载 zip 包解压运行Code.exe然后把解压目录下的bin文件夹加入系统 PATH这样终端里就能直接使用code命令。安装完成或解压完成后打开终端执行code --version如果能看到版本号说明code命令已经可用。如果你是在终端里从项目目录启动可以用code .用 VS Code 打开当前目录这是打开项目最常见的方式。4.2 安装 Markdown 相关扩展VS Code 内置能力已经够用但结合扩展体验更好。终端执行code --install-extension yzhang.markdown-all-in-one code --install-extension davidanson.vscode-markdownlint第一个扩展提供自动格式化、目录生成、表格对齐等能力第二个扩展是 Markdown 规范检查器能帮你提前发现格式问题。这两个扩展在 Markdown 写作场景里属于标配组合。4.3 Notion 账号准备Notion 支持网页版和桌面客户端。注册时如果遇到“你是什么身份”的选项选择学生、个人或团队都可以选错不影响后续功能不需要为此重新注册。如果你一开始选了学生后来发现不是学生也不用担心这只是用来做功能引导的不会锁定你的账户类型。登录后建议先创建一个空白页面把最近正在写的文档粘贴进去作为后续批注实验场。这里要提醒一点Notion 是海外服务使用前请确保当前网络环境可以正常访问官方网页和客户端。本文只讨论正常使用场景下的功能操作。5. Notion 逐块批注实操像代码 review 一样审稿5.1 添加批注在 Notion 页面中把鼠标悬停在任意一个段落块上块的右侧会出现拖拽手柄和图标。点击图标菜单里就能看到“添加评论”入口。如果没有看到也可以选中块后在块的右键菜单里找到评论入口。点击后页面右侧会展开评论区输入你的意见然后发布。评论会锚定到当前块审稿人和作者都能看到这条评论挂在哪个块上。5.2 回复、提及与解决作者打开同一页面会在对应块旁边看到评论气泡。点击气泡进入评论区在下方输入框里回复即可。如果想通知同事输入再选择成员对方会在通知中心收到提醒。评论内容可以是一句话也可以附带待办比如“这里需要补充性能数据我 一下建模组的同学”。每条评论线程最后都可以点击 Resolve 标记为已解决。已解决的评论不会消失而是折叠归档方便后续追溯。5.3 用 Notion API 把批注自动化如果团队想把“机器人审稿”“自动打点评论”引入工作流可以通过 Notion API 创建评论。这个能力来自官方开放接口和人工添加评论是同一套数据模型。使用前需要两步准备在 Notion 官方的集成管理页面新建一个集成获得 Token。在目标页面右上角点击...选择“连接”把刚才创建的集成添加进来授予页面权限。然后用 curl 创建一条评论curl -X POST https://api.notion.com/v1/comments \ -H Authorization: Bearer $NOTION_TOKEN \ -H Notion-Version: 2022-06-28 \ -H Content-Type: application/json \ --data { parent: { page_id: 你的页面ID }, rich_text: [ { type: text, text: { content: 这里需要补充性能测试数据 } } ] }NOTION_TOKEN从环境变量读取页面 ID 是页面 URL 中最后一个斜杠后的一串字符。如果请求成功接口会返回创建好的评论对象。真实项目中更推荐用 Python、Node.js 等语言封装这个 API把评论写入流程和内部的 CI 或消息机器人结合起来。5.4 批注后的协作流程在实际团队协作中批注建议配合以下流程使用审稿人开始评审前先明确文档目标和评审范围。遇到问题直接在对应块上添加评论一条评论只聚焦一个问题。如果多个问题在同一块使用多条评论不要写成长篇大论。作者修改后在评论下补充说明不要静默删除评论。处理完的评论统一 Resolve最后归档评审记录。这套流程和代码评审高度相似团队里如果有做过 code review 的人带起来非常快。6. VS Code 中把 Markdown 编辑器用好6.1 新建 Markdown 文件并打开预览在 VS Code 中新建一个review.md输入内容后按CtrlK V会在右侧打开 Markdown 预览按CtrlShiftV则单独打开预览标签页。这是 VS Code 内置的默认快捷键不需要额外配置。预览区会实时渲染标题、列表、表格、代码块滚动时和编辑区联动。对于写作场景来说这套体验已经非常接近专门的 Markdown 编辑器。6.2 用 settings.json 调优 Markdown 编辑体验VS Code 的配置都集中在 settings.json 中。对 Markdown 写作建议加入以下配置{ markdown.preview.fontSize: 16, markdown.preview.lineHeight: 1.7, markdown.preview.breaks: true, editor.wordWrap: on, [markdown]: { editor.fontSize: 14, editor.lineHeight: 1.8, editor.wordWrap: on, editor.quickSuggestions: { comments: off, strings: off, other: off } }, markdownlint.config: { MD013: false } }配置含义markdown.preview.fontSize/lineHeight控制预览区的字号和行高长时间阅读更舒服。markdown.preview.breaks让换行在预览中直接生效符合中文写作习惯。[markdown]编辑器区块让 Markdown 文件在编辑时不自动换行同时关闭代码块外的干扰性补全。markdownlint.config中关闭MD013行长限制因为中文技术文档经常会写较长的自然段。修改 settings.json 后立即生效不需要重启。6.3 设计一份技术评审稿模板下面是一份技术方案评审稿的 Markdown 模板结构上覆盖了背景、方案、数据库、代码和评审清单# 技术方案评审稿订单导出服务 作者张三 评审人李四 / 王五 状态待评审 ## 1. 背景与目标 当前订单导出全部走同步接口数据量大时响应很慢目标是将导出任务改造成异步任务。 ## 2. 总体方案 - 新增导出任务表 - 通过消息队列触发异步处理 - 导出完成后发送通知 ## 3. 数据库设计 | 字段 | 类型 | 说明 | | --- | --- | --- | | task_id | varchar | 任务 ID | | status | int | 任务状态 | | file_url | text | 导出文件地址 | ## 4. 核心代码 java public class OrderExporter { public void export(String orderId) { // TODO: 补充导出逻辑 } } ## 5. 评审清单 - [ ] 确认订单量级 - [ ] 确认导出格式 - [ ] 确认失败重试策略这份模板的核心不是排版漂亮而是把评审人需要关注的信息提前结构化暴露出来背景、方案、数据表、代码位置、清单。即使审稿人只看 Markdown 渲染后的预览也能快速进入状态。6.4 VS Code 写 Markdown 和 Notion 写文档怎么分工很多人的困惑是既然 Notion 也能写 Markdown为什么还要用 VS Code更合理的分工是初稿和重写用 VS Code评审和协作用 Notion。在 VS Code 里写 Markdown可以享受本地保存、Git 版本管理、与代码库同一环境等优势写技术方案时可以直接引用项目中的真实代码路径。在 Notion 里利用逐块批注功能让团队成员参与评审评论区完整记录讨论过程。定稿后把 Notion 批注全部 Resolve再回到 Markdown 仓库归档。如果想减少迁移成本可以直接在 Notion 里新建页面、粘贴 Markdown 内容Notion 会自动识别大部分语法。这个方法适合只需要协作评审的文档但对于要长期维护、要进 Git 仓库的文档VS Code Markdown 更合适。6.5 扩展Markdown 与代码开发工作流结合对程序员来说VS Code 的 Markdown 编辑器和代码工作流的结合才是真正的增量。比如技术方案放在 Git 仓库的docs/目录PR 里附带文档改动评审人可以在 PR review 中看到 Markdown diff。代码示例直接写在 Markdown 的代码块中语法高亮、缩进、注释都遵循代码规范。目录树、正则搜索、批量替换这些 VS Code 原生能力在处理长文档时比在线文档编辑器更顺手。这也是为什么“VS Code 安装教程”“VS Code 配置教程”一直是热门搜索。很多人并不是要深度定制 IDE而是希望把 VS Code 用成一个足够顺手的写作和开发工具Markdown 恰好是两者之间的桥梁。7. 常见问题与排查思路问题现象可能原因排查方式解决方案按CtrlK V没有反应快捷键冲突或当前文件不是.md文件确认文件后缀和当前焦点切换到.md文件在快捷键
