markstream-migration

Markstream Migration

Overview

Replace an existing Markdown renderer without silently dropping transforms, custom components, URL policy, raw-HTML behavior, or streaming semantics. Read [references/adoption-checklist.md](references/adoption-checklist.md) first.

When to Use

Use when replacing react-markdown, markdown-it, marked, or another renderer; migrating node renderers; or choosing between Markstream content, smooth streaming, and nodes.

Workflow

Before changing dependencies or source files, inspect the existing package manager and project conventions, preview the intended edits, and obtain explicit user approval.

1. Inventory renderer imports, call sites, plugins, HTML policy, URL transforms, allowlists, custom renderers, CSS, and tests.
2. Classify the migration as direct, renderer-custom, plugin-heavy, or security-heavy.
3. Install the framework package and explicit CSS. Preserve visible behavior before optional features.
4. Map built-ins to scoped overrides; in React prefer renderer-local component maps.
5. Use trusted custom tags only for trusted content and reserve parse transforms for irreducible token/AST requirements.
6. Keep content with smooth streaming for ordinary token streams. Use nodes only for worker parsing, shared AST ownership, or structural transforms.
7. Preserve safe HTML and strict Mermaid defaults; scope and document