Back to Details

markstream-migration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Markstream Migration

Markstream迁移指南

Use this skill when a repo already renders Markdown and the task is to adopt Markstream safely.
Read references/adoption-checklist.md before changing code.
当仓库已在使用Markdown渲染且需要安全迁移至Markstream时，可使用本技能。
在修改代码前，请阅读references/adoption-checklist.md。

Workflow

工作流程

  1. Audit the repo's current renderer usage.
    • Search for markdown renderers, plugin chains, raw HTML handling, security props, and custom renderers.
    • List every call site that will be touched.
  2. Classify the migration. 
    • direct
      : simple string-in renderer swap.
    • renderer-custom
      : custom renderers but limited parser work.
    • plugin-heavy
      : remark, rehype, markdown-it, or other transform-heavy pipelines.
    • security-heavy
      : allow or deny lists, URL rewriting, sanitization, or raw HTML policies.
  3. Swap the renderer first.
    • Introduce the correct Markstream package and CSS.
    • Preserve user-visible behavior before adding richer Markstream-only features.
  4. Migrate custom renderers.
    • Convert tag-based renderers into node-type overrides with scoped 
      setCustomComponents
      .
    • For trusted tag-like content, prefer 
      customHtmlTags
      .
  5. Review gaps honestly.
    • Do not claim 1:1 parity where none exists.
    • Call out parser, plugin, security, or HTML behavior that still needs manual review.
  6. Treat streaming as a second pass unless clearly required now.
    • Move to 
      nodes
      only when the app receives streaming or high-frequency updates.
  7. Validate and summarize.
    • Run the smallest relevant tests or build.
    • Report direct mappings, TODOs, and remaining verification work.
  1. 审核仓库当前的渲染器使用情况。
    • 搜索Markdown渲染器、插件链、原始HTML处理、安全属性及自定义渲染器。
    • 列出所有需要修改的调用位置。
  2. 对迁移类型进行分类。 
    • direct
      ：简单的字符串输入渲染器替换。
    • renderer-custom
      ：存在自定义渲染器但解析工作有限。
    • plugin-heavy
      ：依赖remark、rehype、markdown-it或其他重度转换流水线。
    • security-heavy
      ：涉及允许/拒绝列表、URL重写、内容清理或原始HTML策略。
  3. 优先替换渲染器。
    • 引入正确的Markstream包及CSS。
    • 在添加Markstream专属的丰富功能前，先保留用户可见的原有行为。
  4. 迁移自定义渲染器。
    • 将基于标签的渲染器转换为使用作用域
      setCustomComponents
      的节点类型覆盖项。
    • 对于受信任的类标签内容，优先使用
      customHtmlTags
      。
  5. 如实审查差距。
    • 不要声称不存在的1:1功能对等。
    • 指出仍需人工审查的解析器、插件、安全或HTML行为问题。
  6. 除非当前明确需要，否则将流式渲染作为第二阶段任务。
    • 仅当应用需要流式传输或高频更新时，才切换至
      nodes
      模式。
  7. 验证并总结。
    • 运行最相关的小型测试或构建任务。
    • 报告直接映射关系、待办事项（TODOs）及剩余的验证工作。

Default Decisions

默认决策

  • Renderer swap first, streaming optimization second.
  • Preserve safety over feature parity when HTML or security rules are involved.
  • Prefer explicit TODOs over vague claims.
  • Recommend against migration when the current stack depends heavily on transforms that Markstream does not mirror directly.
  • 优先替换渲染器，其次进行流式渲染优化。
  • 涉及HTML或安全规则时，优先保留安全性而非功能对等。
  • 优先使用明确的待办事项（TODOs）而非模糊表述。
  • 当当前栈严重依赖Markstream无法直接镜像的转换逻辑时，建议不进行迁移。

Useful Doc Targets

实用文档目标

  • docs/guide/react-markdown-migration.md
  • docs/guide/react-markdown-migration-cookbook.md
  • docs/guide/installation.md
  • docs/guide/component-overrides.md
  • docs/guide/advanced.md
  • docs/guide/react-markdown-migration.md
  • docs/guide/react-markdown-migration-cookbook.md
  • docs/guide/installation.md
  • docs/guide/component-overrides.md
  • docs/guide/advanced.md