tanstack-highlight-integrate-framework-code-blocks

用途

本技能用于把 @tanstack/highlight 接入具体框架的代码块渲染流程，覆盖 React 组件数据、Octane 组件数据、Octane MDX 插件以及 SSR 与客户端水合场景。适配器本身不导入 React、Octane 或 MDX 运行时，也不注册任何语言，语言选择由应用传入的 highlighter 决定。

前提：需先阅读 configure-selective-highlighting 与 integrate-markdown-pipelines，前者说明注册表行为，后者说明树变换行为。

主要能力

集成设置：在同构模块中创建 highlighter，然后传入适配器。

import { createHighlighter } from '@tanstack/highlight/core'
import { ts } from '@tanstack/highlight/languages/ts'
import { tsx } from '@tanstack/highlight/languages/tsx'
import { createHighlightedCodeBlockProps } from '@tanstack/highlight/react'

const highlighter = createHighlighter({ languages: [ts, tsx] })

export const block = createHighlightedCodeBlockProps({
  highlighter,
  code: 'const answer = 42',
  lang: 'ts',
  title: 'answer.ts',
  className: 'docs-code',
})

React 集成：适配器给出的是数据，不是组件。应用在生成的标记外围渲染自己拥有的控件（复制按钮、标签页、文件名、布局）。

import type { HighlightedCodeBlockProps } from '@tanstack/highlight/react'

export function CodeBlock({
  className,
  copyText,
  htmlMarkup,
  title,
}: HighlightedCodeBlockProps) {
  return (
    <figure className={className}>
      {title ? <figcaption>{title}</figcaption> : null}
      <div dangerouslySetInnerHTML={{ __html: htmlMarkup }} />
      <button
        type="button"
        onClick={() => navigator.clipboard.writeText(copyText)}
      >
        Copy
      </button>
    </figure>
  )
}

Octane MDX：使用插件元组配置。

import { octaneMdx } from '@octanejs/mdx/vite'
import { createOctaneMdxHighlight } from '@tanstack/highlight/octane'
import { highlighter } from './src/highlight'

export default {
  plugins: [
    octaneMdx({
      rehypePlugins: [
        createOctaneMdxHighlight({
          highlighter,
          lineNumbers: true,
        }),
      ],
    }),
  ],
}

该元组包装了 @octanejs/mdx 期望的同步 Rehype 适配器。

水合后新增内容：只对水合之后引入的内容做高亮。

import { highlighter } from './highlight'

export function renderClientNavigationCode(code: string, lang: string) {
  return highlighter.renderCodeBlockData({ code, lang })
}

服务端首屏渲染的代码已是静态高亮 HTML；新路由、预览或交互式源码变更使用客户端注册表。

常见错误

HIGH 在 code 中嵌套完整标记。错误做法是返回 <pre><code dangerouslySetInnerHTML=... /></pre>，因为 htmlMarkup 已包含完整的 pre > code 树，再包一层会产生非法的嵌套块标记。正确做法是直接 <div dangerouslySetInnerHTML={{ __html: block.htmlMarkup }} />。来源：docs/guides/react.md。

CRITICAL 通过块属性插入任意 HTML。高亮器会转义代码源码，但插入属性不会净化无关 HTML，因此应使用 createHighlightedCodeBlockProps({ highlighter, code, lang: 'plaintext' }) 而非直接把外部 html 交给 dangerouslySetInnerHTML。来源：docs/guides/react.md。

HIGH 水合期间重新高亮初始 DOM。服务端渲染的高亮 HTML 是静态的，不需要水合副作用；正确做法是接收 htmlMarkup 并渲染。来源：docs/guides/ssr-and-client.md。

HIGH 向 Octane 传入裸 transformer。Octane MDX 消费的是其适配器返回的“插件加选项”元组，应使用 createOctaneMdxHighlight({ highlighter })，而非 rehypeHighlightCodeBlocks({ highlighter })。来源：docs/guides/octane.md。

CRITICAL 服务端与客户端注册表不一致。不要按 typeof window 分支注册不同语言；不同注册会在水合期间改变归一化语言与内嵌输出，应始终使用 createHighlighter({ languages: [html, js] })。来源：docs/guides/ssr-and-client.md。

CRITICAL 混用精确 API 与块归一化 API。块数据适配器会裁掉尾部空白，而核心 highlight() 会保留，因此服务端与客户端都应使用 createHighlightedCodeBlockProps(...).htmlMarkup。来源：docs/guides/ssr-and-client.md。

取舍提示

HIGH 便利性与客户端体积的张力：适配器要求显式传入 highlighter，以便应用控制保留的语言；把根级 helper 到处传递会破坏这一边界。参见 ../tanstack-highlight-configure-selective-highlighting/SKILL.md。

HIGH 结构化输出与原始 HTML 的张力：MDX 管道中使用结构化 HAST，仅在应用自有的直接组件内插入生成的 htmlMarkup。参见 ../tanstack-highlight-integrate-markdown-pipelines/SKILL.md。

HIGH 精确源码与块归一化的张力：服务端与客户端使用同一适配器和选项。主题选择不影响标记，但源码归一化会影响。参见 ../tanstack-highlight-integrate-markdown-pipelines/SKILL.md。

限制

适配器不注册语言，语言需由应用配置；SSR 与客户端输出要求相同的注册表与包版本。资料未提供支持的具体框架版本、性能数据、收费或许可信息。

技能介绍

用途

主要能力

常见错误

取舍提示

限制