用途:在不悄悄丢失转换逻辑、自定义组件、URL 策略、原始 HTML 行为和流式语义的前提下,替换既有 Markdown 渲染器。适用于替换 react-markdown、markdown-it、marked 或其他渲染器,迁移节点渲染器,或在 Markstream 的 content、smooth streaming 与 nodes 之间做选择。使用前应先阅读 references/adoption-checklist.md。
主要流程:改动依赖或源码前,先检查现有包管理器与项目约定,预览拟进行的修改并取得用户明确批准;盘点渲染器导入、调用点、插件、HTML 策略、URL 转换、允许列表、自定义渲染器、CSS 与测试;将迁移归类为直接、渲染器自定义、插件密集或安全密集;安装框架包与显式 CSS,先保留可见行为再考虑可选功能;把内置能力映射为作用域覆盖,React 中优先使用渲染器本地组件映射;可信自定义标签只用于可信内容,解析转换仅用于无法化简的 token/AST 需求;普通 token 流使用 content 加 smooth streaming,仅在 worker 解析、共享 AST 所有权或结构转换时使用 nodes;保留安全 HTML 与严格 Mermaid 默认值,任何可信旧例外都要限定范围并记录;运行相关构建与行为测试,报告映射、有意差异与未解决的评审项。
示例要点:从 react-markdown 迁移时导入 MarkdownRender 与 'markstream-react/index.css',以 content、final、fade、typewriter、smoothStreaming、htmlPolicy 等属性控制流式与安全行为(具体属性见资料示例,代码保持原样)。
限制:Markstream 无法自动复现每一个 remark、rehype 或 markdown-it 插件;视觉一致不能证明安全或 URL 策略一致;大型迁移可能需要分阶段转换。安全提示:不要为截图一致而削弱净化,需显式审查依赖、原始 HTML、URL 转换与信任边界。