Skip to content
Source
Sign inSign up
TanStack/markdown

Support custom inline nodes in framework renderers #9

Send to my agent
ClosedStanzilla(GitHub profile, opens in a new tab) opened this issue 2 comments

Problem

MarkdownExtension.transformInline can transform InlineNode[], but the InlineNode union has no custom component node. The existing ComponentNode is block-only because its children are BlockNode[].

This leaves a gap for inline application UI such as mentions, channels, custom emoji, and embedded assets:

  • an extension can detect and transform the syntax;
  • the HTML renderer has the extension-level renderHtml hook;
  • framework renderers use a closed switch over the built-in inline node types;
  • the React components map can replace emitted tags, but an extension cannot emit a typed custom inline tag.

Consumers must therefore misuse a built-in node such as ImageNode or LinkNode, encode data in sentinel properties, and recover it through the component map. The other option is to replace the framework renderer. The first approach gives non-image or non-link content incorrect semantics; the second loses the benefit of the provided renderer.

Suggested API direction

One option is an inline equivalent of ComponentNode, for example:

interface InlineComponentNode {
  type: 'inlineComponent'
  name: string
  attributes: Record<string, string>
  children: InlineNode[]
  tagName?: string
  properties?: Record<string, string>
}

It could be added to InlineNode and rendered through the existing framework components map, in the same way that block ComponentNode is handled.

Another option is a framework renderer extension hook that can return custom output for an inline node before the built-in renderer handles it.

Example use case

const mentionExtension: MarkdownExtension = {
  name: 'mentions',
  transformInline(nodes) {
    return transformMentions(nodes, mention => ({
      type: 'inlineComponent',
      name: 'mention',
      tagName: 'mention',
      attributes: { id: mention.id },
      children: [{ type: 'text', value: mention.label }],
    }))
  },
}

<Markdown
  extensions={[mentionExtension]}
  components={{ mention: Mention }}
>
  {source}
</Markdown>

The important part is a typed way for transformInline to produce portable custom inline output that React and other framework renderers can render without raw HTML or built-in-node semantic workarounds.

  1. tannerlinsley added labelsenhancement

  2. Confirmed on 0.0.14. InlineNode has no custom component variant, and the framework renderers have no branch for one. ComponentNode is block-only; using link/image nodes as sentinels is not an API we want to recommend.

    I prototyped an InlineComponentNode using the existing component maps, with escaped children, a span fallback, JSON round-tripping, and equivalent HTML/React/Octane output. Those tests passed. Combined with the code-metadata proposal in #7, the renderer entries still grew by roughly 34-50 gzip bytes after local simplifications, so that prototype was not retained. Those are combined costs, not a measurement of this feature alone.

    Keeping this open as the canonical issue for portable custom inline output, including the extension use case raised in #13. A future implementation must fit the current minified, gzip, and Brotli sizes, preserve existing block components and HTML hooks, and work without allowHtml. Built-in math or a framework renderer hook is not required if the component-map approach can meet those constraints.

  3. Confirmed on 0.0.14. InlineNode has no custom component variant, and the framework renderers have no branch for one. ComponentNode is block-only; using link/image nodes as sentinels is not an API we want to recommend.

    I prototyped an InlineComponentNode using the existing component maps, with escaped children, a span fallback, JSON round-tripping, and equivalent HTML/React/Octane output. Those tests passed. Combined with the code-metadata proposal in #7, the renderer entries still grew by roughly 34-50 gzip bytes after local simplifications, so that prototype was not retained. Those are combined costs, not a measurement of this feature alone.

    Keeping this open as the canonical issue for portable custom inline output, including the extension use case raised in #13. A future implementation must fit the current minified, gzip, and Brotli sizes, preserve existing block components and HTML hooks, and work without allowHtml. Built-in math or a framework renderer hook is not required if the component-map approach can meet those constraints.

    What would you suggest as a workaround for now?

  4. tannerlinsley closed this

Sign in to join this conversation.