企业官网建设流程全解析

给文档提修改意见，是每个技术人躲不掉的工作。你在微信里回一句“第三部分好像有问题”，对方只能全文搜索“第三部分”在哪里；你在 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 工作流是脱节的。

本文要解决的，就是这三类问题：

1. 让审稿意见可以精确定位到具体段落。
2. 让技术写作环境回到 Markdown 和代码库的熟悉节奏。
3. 让“写作—评审—修改—定稿”的流程有可追踪的完整记录。

这条工作流适合的人也很明确：

• 需要写技术方案、架构设计、接口文档的程序员。
• 需要给团队文档做 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 支持不是某个新版本凭空出现的能力，而是长期迭代积累的结果。对没用过的人来说，它确实像一个“新编辑器”，因为很多人并不了解里面有多少细节可以调。

这张表最关键的差异在“意见锚点”这一行。

3. 为什么“逐块批注”对审稿这么重要

3.1 审稿的本质是精准反馈

想象一个真实场景：你提交了一份 5000 字的技术方案，Leader 看完后说：“这几个方案你对比一下，第三部分的关系型数据库选型有点问题。”你只能先翻到第三部分，再逐个读取“关系型数据库选型”那一节，猜对方指的是哪一句。

逐块批注把这一过程彻底简化了。审稿人不需要再描述“在哪里”，只需要在对应块上点一下“添加评论”，输入意见。意见自动锚定到那个块，作者点开评论就看到具体位置和上下文。信息从“作者主动猜测”变成“读者被动接收”，沟通成本大幅下降。

3.2 评论区是线程化讨论，不是一次性留言

Notion 的每条评论都会形成一条讨论线程，作者可以在原位置回复，也可以 @ 相关成员要求确认。同一个块的多个评论会汇总显示，审稿人可以随时把已经确认的评论标记为 Resolve。这样，一篇文档的评审状态一目了然：还有几条未解决评论、每条评论在哪个块、负责人是谁。

这套体验和 GitHub 的 Review 流程高度相似，对开发团队来说几乎没有学习成本。如果团队里有人做过代码评审，带文档评审会非常快。

3.3 对论文、对外文档同样有效

写论文时，导师说“绪论的贡献点写得太笼统”，你可以在 Notion 里把绪论拆成几个小块，导师直接对“贡献点”块写意见，你改完再回复。对外输出产品文档、运营方案时，批注让参与评审的人针对各自专业的部分提意见，而不是在文档末尾堆一大段“整体意见”。

所以，逐块批注真正改变的不是“能不能评论”，而是“评论能不能被精准定位、跟踪和收敛”。这是传统文档工具长期没有解决好的问题，也是 Notion 在这个场景下值得被认真对待的原因。

4. 环境准备：VS Code 安装与 Notion 账号准备

4.1 安装 VS Code

VS 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 创建评论。这个能力来自官方开放接口，和人工添加评论是同一套数据模型。

使用前需要两步准备：

1. 在 Notion 官方的集成管理页面新建一个集成，获得 Token。
2. 在目标页面右上角点击...，选择“连接”，把刚才创建的集成添加进来，授予页面权限。

然后用 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 批注后的协作流程

在实际团队协作中，批注建议配合以下流程使用：

1. 审稿人开始评审前，先明确文档目标和评审范围。
2. 遇到问题，直接在对应块上添加评论，一条评论只聚焦一个问题。
3. 如果多个问题在同一块，使用多条评论，不要写成长篇大论。
4. 作者修改后，在评论下补充说明，不要静默删除评论。
5. 处理完的评论统一 Resolve，最后归档评审记录。

这套流程和代码评审高度相似，团队里如果有做过 code review 的人，带起来非常快。

6. VS Code 中把 Markdown 编辑器用好

6.1 新建 Markdown 文件并打开预览

在 VS Code 中新建一个review.md，输入内容后，按Ctrl+K V会在右侧打开 Markdown 预览；按Ctrl+Shift+V则单独打开预览标签页。这是 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. 常见问题与排查思路