Markstream custom components

Markstream Custom Components

Use this skill when the task is to change how Markstream renders specific nodes or custom tags.

Read references/patterns.md before choosing an override strategy.

Workflow

1. Classify the request.
   • built-in override: replace an existing renderer such as image, link, code_block, mermaid, d2, or inline_code.
   • custom tag: support trusted HTML-like tags such as thinking.
   • parser-level: requires token transforms or AST reshaping. Only then should you leave this skill and use low-level parser hooks.
2. Prefer scoped mappings.
   • Use setCustomComponents(customId, mapping) instead of global mappings whenever practical.
   • Pass the same customId or custom-id to the renderer instance.
   • In Vue 3 app/plugin setup, import { VueRendererMarkdown } from markstream-vue and install it with { components } when the override should be scoped to the Vue app instance.
3. Start with the smallest safe override.
   • Leaf-like nodes (image, link, inline_code, mermaid) are easier than container nodes (heading, paragraph, list_item).
   • If the request only changes Mermaid, use mermaid, not code_block.
4. Preserve nested Markdown when needed.
   • For trusted custom tags with inner Markdown, render node.content with a nested renderer.
   • Pass the same custom-tag allowlist to nested renderers.
   • Nested renderers inside a smooth-streaming parent are automatically suppressed from double pacing — do not add smooth-streaming to child renderers.
5. Keep props and cleanup intact.
   • Preserve node, loading, indexKey, customId, and isDark.
   • For mermaid and infographic overrides, preserve estimatedPreviewHeightPx so async preview shells keep stable height during remounts.
   • Remove temporary scoped mappings with removeCustomComponents(customId) when the scope is no longer needed.
6. Validate with the smallest useful check.
   • Prefer a local demo, targeted test, or docs build.
   • Call out whether the implementation is safe for repeated and nested custom tags.

Default Decisions

• Scoped overrides first, global overrides only when the whole app truly needs them.
• Leaf-node overrides before container-node overrides.
• customHtmlTags plus scoped custom components before parser hooks.
• Nested renderers for tag bodies that contain Markdown.

Useful Doc Targets

• docs/guide/component-overrides.md
• docs/guide/custom-components.md
• docs/guide/components.md
• docs/guide/advanced.md