markstream-custom-components

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markstream Custom Components

Markstream 自定义组件

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.

当任务需要修改Markstream渲染特定节点或自定义标签的方式时，使用该skill。

选择重写策略前，请先阅读references/patterns.md。

Workflow

工作流

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.
Prefer scoped mappings.
- Use
```
setCustomComponents(customId, mapping)
```
  instead of global mappings whenever practical.
- Pass the same
```
customId
```
  or
```
custom-id
```
  to the renderer instance.
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
```
  .
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.
Keep props and cleanup intact.
- Preserve
```
node
```
  ,
```
loading
```
  ,
```
indexKey
```
  ,
```
customId
```
  , and
```
isDark
```
  .
- Remove temporary scoped mappings with
```
removeCustomComponents(customId)
```
  when the scope is no longer needed.
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.

对请求进行分类。
- ```
内置重写
```
  ：替换现有渲染器，例如
```
image
```
  、
```
link
```
  、
```
code_block
```
  、
```
mermaid
```
  、
```
d2
```
  或
```
inline_code
```
  。
- ```
自定义标签
```
  ：支持可信任的类HTML标签，例如
```
thinking
```
  。
- ```
解析器级别
```
  ：需要令牌转换或AST重构。只有这种情况下你才应该停用该skill，使用底层解析器钩子。
优先使用作用域映射。
- 只要可行，就使用
```
setCustomComponents(customId, mapping)
```
  而非全局映射。
- 向渲染器实例传入相同的
```
customId
```
  或
```
custom-id
```
  。
从最小的安全重写开始。
- 叶子类节点（
```
image
```
  、
```
link
```
  、
```
inline_code
```
  、
```
mermaid
```
  ）比容器节点（
```
heading
```
  、
```
paragraph
```
  、
```
list_item
```
  ）更容易处理。
- 如果请求仅修改Mermaid的渲染，就使用
```
mermaid
```
  而非
```
code_block
```
  。
必要时保留嵌套Markdown。
- 对于内部包含Markdown的可信任自定义标签，使用嵌套渲染器渲染
```
node.content
```
  。
- 向嵌套渲染器传入相同的自定义标签白名单。
保持属性和清理逻辑完整。
- 保留
```
node
```
  、
```
loading
```
  、
```
indexKey
```
  、
```
customId
```
  和
```
isDark
```
  参数。
- 当不再需要作用域时，使用
```
removeCustomComponents(customId)
```
  移除临时作用域映射。
用最小的有效检查做验证。
- 优先选择本地演示、定向测试或文档构建。
- 说明实现是否对重复和嵌套的自定义标签安全。

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.

优先使用作用域重写，仅当整个应用确实需要时才使用全局重写。
优先重写叶子节点，再重写容器节点。
优先使用
```
customHtmlTags
```
加作用域自定义组件，再考虑解析器钩子。
包含Markdown的标签主体使用嵌套渲染器。

Useful Doc Targets

有用的文档目标

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

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