Markstream

简体中文

English

简体中文

English

Appearance

...

React 安装 ​

使用 pnpm、npm 或 yarn 安装 markstream-react。

已经在用 react-markdown？

如果你是从 react-markdown 迁过来，先看迁移指南获取整体路径，再看迁移 Cookbook查具体场景。

bash
pnpm add markstream-react
# 或
npm install markstream-react
# 或
yarn add markstream-react

要求 ​

markstream-react 需要：

  • React 18+ 和 ReactDOM 18+
  • stream-markdown-parser（作为依赖自动安装）

可选的对等依赖 ​

markstream-react 通过可选的对等依赖支持各种功能。只安装你需要的功能：

功能所需包安装命令
增强代码块（推荐）stream-diffspnpm add stream-diffs
Mermaid 图表mermaidpnpm add mermaid
D2 图表@terrastruct/d2pnpm add @terrastruct/d2
数学公式渲染（KaTeX）katexpnpm add katex

增强代码块使用可选的对等依赖 stream-diffs。未安装时会回退渲染普通 <pre>。直接 CodeBlockNode 与顶层 MarkdownRender 都接收 codeBlockOptions；已注册的主题名称通过 darkTheme / lightTheme 传入，themes 是用于预加载的 [dark, light] 对。

可选：在 Vite / Vite 兼容打包器中启用线程外 Worker ​

安装后会自动加载 Mermaid/KaTeX。?worker import 语法适用于 Vite 兼容打包器。Next.js 项目请看 Next.js SSR 指南，并把浏览器专属 worker 初始化放在 client boundary 后面。

如果你在 Vite 兼容应用中需要线程外解析/渲染，可在入口注入 Worker：

tsx
import { setKaTeXWorker, setMermaidWorker } from 'markstream-react'
import KatexWorker from 'markstream-react/workers/katexRenderer.worker?worker'
import MermaidWorker from 'markstream-react/workers/mermaidParser.worker?worker'

setMermaidWorker(new MermaidWorker())
setKaTeXWorker(new KatexWorker())

同时记得导入必需的 CSS：

tsx
import 'markstream-react/index.css'
import 'katex/dist/katex.min.css'

markstream-react 不会从 JavaScript 入口自动注入渲染器样式。请在应用 shell 或组件入口显式导入一个 Markstream CSS 文件：index.css、index.px.css 或 index.tailwind.css。

注意：markstream-react/index.css 的样式被限制在内部的 .markstream-react 容器下，以减少全局样式冲突。MarkdownRender 默认在该容器内渲染。如果你单独渲染节点组件，请用 <div className="markstream-react">...</div> 包裹它们。

Tailwind CSS 支持 ​

如果你的项目使用 Tailwind，并希望避免重复注入 Tailwind utilities，请改用 Tailwind-ready 输出：

tsx
import 'markstream-react/index.tailwind.css'

并在 tailwind.config.js 的 content 中加入该包导出的 class 列表：

js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    require('markstream-react/tailwind'),
  ],
}

这种方式可以确保 Tailwind 在清除未使用的样式时包含 markstream-react 使用的所有工具类，从而获得更小的最终打包体积。

快速安装：所有功能 ​

一次性启用所有功能：

bash
pnpm add stream-diffs mermaid @terrastruct/d2 katex
# 或
npm install stream-diffs mermaid @terrastruct/d2 katex

功能详情 ​

代码语法高亮 ​

需要安装 stream-diffs：

bash
pnpm add stream-diffs

stream-diffs 提供增强 CodeBlockNode runtime。受支持的配置使用 codeBlockOptions；未安装时会回退渲染普通 <pre>。需要自定义行为时，可通过 setCustomComponents 覆盖 code_block 渲染器：

tsx
import { setCustomComponents } from 'markstream-react'

setCustomComponents({
  code_block: ({ node, isDark, ctx }: any) => (
    <MyCodeBlock
      node={node}
      isDark={isDark}
      stream={ctx?.codeBlockStream}
      codeBlockOptions={ctx?.codeBlockOptions}
      {...(ctx?.codeBlockProps || {})}
    />
  ),
})

主题值是已注册的 string 名称。直接 CodeBlockNode 使用 darkTheme / lightTheme，themes 是用于预加载的 [dark, light] 对；旧 JSON theme object 需先调用 stream-diffs/pierre 的 registerCustomTheme，再传入注册名称。

Mermaid 图表 ​

渲染 Mermaid 图表：

bash
pnpm add mermaid

D2 图表 ​

渲染 D2 图表：

bash
pnpm add @terrastruct/d2

KaTeX 数学公式渲染 ​

数学公式渲染：

bash
pnpm add katex

同时在应用入口文件中导入 KaTeX CSS：

tsx
import 'katex/dist/katex.min.css'

快速测试 ​

导入并渲染一个简单的 markdown 字符串：

tsx
import MarkdownRender from 'markstream-react'
import 'markstream-react/index.css'

function App() {
  const md = '# Hello from markstream-react!'

  return <MarkdownRender content={md} />
}

export default App

TypeScript 支持 ​

markstream-react 使用 TypeScript 编写，并包含完整的类型定义，无需额外配置：

tsx
import type { NodeRendererProps } from 'markstream-react'
import MarkdownRender from 'markstream-react'

const props: NodeRendererProps = {
  content: '# Hello TypeScript!',
}

function App() {
  return <MarkdownRender {...props} />
}

Next.js 集成 ​

在 Next.js 中，优先使用专门的 SSR 双入口：

tsx
import MarkdownRender from 'markstream-react/next'
import 'markstream-react/index.css'

export default function MarkdownPage() {
  return <MarkdownRender content="# Hello Next.js!" final />
}

如果你需要一条纯 server、只输出稳定 fallback 的路径：

tsx
import MarkdownRender from 'markstream-react/server'

export default function MarkdownPage() {
  return <MarkdownRender content="# Hello Next.js!" final />
}

更完整的 App Router、Pages Router、自定义组件和验证说明见 React Next SSR。

Vite 集成 ​

对于 Vite 项目，只需导入组件和样式：

tsx
// src/main.tsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import 'markstream-react/index.css'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
)
tsx
// src/App.tsx
import MarkdownRender from 'markstream-react'

function App() {
  const content = `# Hello Vite!

这是 markstream-react 与 **Vite** 配合使用。`

  return <MarkdownRender content={content} />
}

export default App

Webpack 集成 ​

对于使用 Webpack 的项目，确保你的配置处理 CSS 导入：

js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader']
      }
    ]
  }
}

自定义组件设置 ​

要使用自定义节点组件，你需要创建自定义渲染器。详情请参阅 组件文档。