如何用 remark-npm 插件在 Fumadocs MDX 中生成多包管理器的安装命令代码块？

如何用 remark-npm 插件在 Fumadocs MDX 中生成多包管理器的安装命令代码块？

【免费下载链接】fumadocsThe beautiful & flexible React.js docs framework.项目地址: https://gitcode.com/GitHub_Trending/fu/fumadocs

在文档站点里写安装步骤时，同一条命令往往需要针对 npm、pnpm、yarn、bun 分别写一遍。Fumadocs Core 提供的remarkNpm插件可以解决这个问题：你在 MDX 中只写一条npm语言的代码块，编译时插件会自动把它转换成一个带 Tab 的代码块结构，渲染出可切换的四种包管理器命令。本文介绍如何接入该插件、编写对应的 MDX 内容，以及可选的persist配置。

前提：两条接入路径

remarkNpm来自fumadocs-core/mdx-plugins，文档给出了两种使用方式，按你的文档构建方式二选一：

• Fumadocs MDX（fumadocs-mdx）：该插件默认启用，通常不需要额外引入，只有在需要定制时通过remarkNpmOptions配置。这一点可以从 fumadocs-mdx 的 MDX 预设实现 得到印证——预设中只要remarkNpmOptions不为false就会挂上该插件。
• MDX Compiler（直接用@mdx-js/mdx的compile）：需要手动把插件加入remarkPlugins。

第一步：启用插件

使用 MDX Compiler 直接编译时，把remarkNpm加入remarkPlugins：

import { compile } from '@mdx-js/mdx'; import { remarkNpm } from 'fumadocs-core/mdx-plugins'; await compile('...', { remarkPlugins: [remarkNpm], });

使用 Fumadocs MDX 时，插件默认已启用，source.config.ts中只有需要定制时才写remarkNpmOptions：

import { defineConfig } from 'fumadocs-mdx/config'; export default defineConfig({ mdxOptions: { remarkNpmOptions: { // it is enabled by default, customize it here }, }, });

第二步：定义渲染所需的组件

插件生成的不是普通代码块，而是一组CodeBlockTabs系列组件，MDX 组件解析表里必须能找到它们。

使用 Fumadocs UI：这些组件已包含在defaultComponents中，只要像 本仓库的组件配置 那样展开即可：

import defaultComponents from 'fumadocs-ui/mdx'; import type { MDXComponents } from 'mdx/types'; export function getMDXComponents(components?: MDXComponents) { return { // it's included by default in `defaultComponents` ...defaultComponents, ...components, } satisfies MDXComponents; }

自定义 UI：需要自行提供四个组件并挂到组件解析表上：

import { CodeBlockTabs, CodeBlockTab, CodeBlockTabsList, CodeBlockTabsTrigger } from 'my-ui'; import type { MDXComponents } from 'mdx/types'; export function getMDXComponents(components?: MDXComponents) { return { CodeBlockTabs, CodeBlockTab, CodeBlockTabsList, CodeBlockTabsTrigger, ...components, } satisfies MDXComponents; }

四个组件各自接收的 props（文档给出的约定）：

第三步：在 MDX 中写 npm 代码块

转换的触发条件很简单：代码块语言标记为npm。例如文档页面里写：

```npm npm i my-package ``` ```npm npm i my-package -D ```

编译后，每个代码块会被替换成如下结构（文档给出的示例输出）：

<CodeBlockTabs defaultValue="npm"> <CodeBlockTabsList> <CodeBlockTabsTrigger value="npm">npm</CodeBlockTabsTrigger> <CodeBlockTabsTrigger value="pnpm">pnpm</CodeBlockTabsTrigger> <CodeBlockTabsTrigger value="yarn">yarn</CodeBlockTabsTrigger> <CodeBlockTabsTrigger value="bun">bun</CodeBlockTabsTrigger> </CodeBlockTabsList> <CodeBlockTab value="npm">...</CodeBlockTab> <CodeBlockTab value="pnpm">...</CodeBlockTab> <CodeBlockTab value="yarn">...</CodeBlockTab> <CodeBlockTab value="bun">...</CodeBlockTab> </CodeBlockTabs>

其中每个CodeBlockTab内是转换后的对应包管理器命令。默认生成的四个 Tab 来自 插件实现 中的packageManagers默认值：npm（原样保留）、pnpm、yarn、bun（后三者通过npm-to-yarn转换，逐行处理多行命令）。

验证结果

完成接入后，判断标准是页面上原本的单个npm代码块变成了可点击切换的 Tab 组：

• 默认选中npmTab（即defaultValue="npm"）；
• 切到pnpm/yarn/bun时显示对应命令；
• 如果切换后没有 Tab、或页面报组件未定义，先检查第二步的组件解析表里是否注册了CodeBlockTabs系列组件（自定义 UI 场景）。

可选：持久化用户选择的包管理器

与 Fumadocs UI 配合时，可以给插件加persist选项，把用户选择的 Tab 值持久化，生成persistprop 传给<CodeBlockTabs />。id是存储键名，由你指定：

import { defineConfig } from 'fumadocs-mdx/config'; export default defineConfig({ mdxOptions: { remarkNpmOptions: { persist: { id: 'package-manager', }, }, }, });

MDX Compiler 路径下则通过插件参数传入：

import { compile } from '@mdx-js/mdx'; import { remarkNpm, type RemarkNpmOptions } from 'fumadocs-core/mdx-plugins'; const remarkNpmOptions: RemarkNpmOptions = { persist: { id: 'package-manager', }, }; await compile('...', { remarkPlugins: [[remarkNpm, remarkNpmOptions]], });

persist的具体行为见 Fumadocs UI 的 Tabs 组件文档：指定groupId时值暂存于sessionStorage，加上persist后则写入localStorage，以组 ID 作为存储键。

边界与相关说明

• 只有语言标记为npm的代码块会被转换，其他语言的代码块不受影响。
• 如果你之前用的是旧的remarkInstall插件（package-install代码块，来自fumadocs-docgen），文档已标注其为Deprecated：在 Fumadocs MDX 中remarkNpm已默认启用，应当改用本插件，参考 Package Install 文档。
• 插件选项类型RemarkNpmOptions还包含packageManagers字段（见 插件源码），可用于替换或增删 Tab，默认四个管理器满足常规场景时无需配置。

主要参考文档：Remark NPM。

【免费下载链接】fumadocsThe beautiful & flexible React.js docs framework.项目地址: https://gitcode.com/GitHub_Trending/fu/fumadocs