问题

在缺少实时预览的情况下撰写 Markdown，会带来格式错误、容器失效、图片路径不正确等问题。这些问题往往要等到内容进入生产环境后才会暴露。结果是用户体验糟糕，维护者不得不为渲染问题推送紧急修复。

为什么重要

高质量的文档是开发者信任的基石。一个损坏的警告框或未渲染的语法显得不专业，也会误导用户。在上线前看到"真实"的文档，是发现错误、提升可读性并保证用户体验顺畅的最佳方式。

方法

采用多阶段预览策略：撰写时使用 docmd 的 本地开发 服务器获得即时反馈；在 Pull Request 内审时，使用类似 Vercel 或 Cloudflare Pages 的临时云环境。

实现

1. 即时的本地预览

查看改动最快的方式是运行 npx @docmd/core dev 服务器。它支持热模块替换 (HMR)，会在您保存 Markdown 文件的那一刻自动刷新浏览器。

# 启动本地开发服务器
npx @docmd/core dev

2. 基于云的预览环境

为支持协作评审，可将您的 CI/CD 平台配置为：为每个 Pull Request 生成独立的"预览 URL"。docmd 输出的是标准静态文件，因此兼容所有主流托管服务。

• 构建命令：npx @docmd/core build
• 输出目录：site

这样评审者就能在类生产环境中准确看到改动后的效果与行为，再决定是否合并到 main 分支。

3. 使用 Threads 进行协作评审

将云端预览与 Threads 插件 结合使用，团队成员就能直接在已渲染的预览页面上留下反馈。它打通了 Markdown 源文件与最终用户体验之间的隔阂。

取舍

在大型仓库里为每次提交都构建完整的静态站点，会消耗大量 CI/CD 时间与资源。一种优化方式是：只在源码目录（例如 /docs）中的文件发生变化时，才触发文档构建。