在Docusaurus的React组件中添加可显示于目录的标题

问题原因 #

Docusaurus的文档目录（TOC）是在构建时扫描页面中的原生标题元素（h1-h6）或MDX标题生成的。你之前使用的Heading组件仅实现了样式和链接功能，但未被TOC解析器识别；而MDX的用法有误，导致无法正常渲染并被TOC捕获。

解决方案 #

方法1：使用原生HTML标题+Docusaurus样式类 #

直接使用原生h2元素，并添加Docusaurus的样式类，既保证TOC能识别，又保持正确样式：

<h2 id="my-heading" className="text--primary font-size--xl">My Heading</h2>

（注：text--primary和font-size--xl是Docusaurus默认标题的样式类，可根据主题调整）

方法2：通过MDXComponents渲染标题 #

利用Docusaurus提供的useMDXComponents钩子，使用MDX体系内的标题组件，确保被TOC解析：

import { useMDXComponents } from '@docusaurus/theme-common';

export default function MyComponent() {
  const MDXComponents = useMDXComponents();
  return <MDXComponents.h2 id="my-heading">My Heading</MDXComponents.h2>;
}

方法3：手动注册标题到TOC #

如果标题是动态生成的，可使用useTOCClient钩子手动添加TOC项：

import { useTOCClient } from '@docusaurus/theme-common/internal';
import { useEffect } from 'react';

export default function MyComponent() {
  const tocClient = useTOCClient();

  useEffect(() => {
    const heading = {
      value: 'My Heading',
      id: 'my-heading',
      level: 2,
    };
    tocClient.addHeading(heading);
    
    // 组件卸载时移除
    return () => tocClient.removeHeading(heading.id);
  }, [tocClient]);

  return <h2 id="my-heading">My Heading</h2>;
}

纠正你之前的MDX用法错误 #

你之前的MDX代码存在用法问题，正确的方式是将MDX内容通过MDXContent渲染，而非传递给MDXProvider的components属性：

import { MDXContent } from '@mdx-js/react';

const mdxHeading = {
  type: 'heading',
  depth: 2,
  children: [{ type: 'text', value: 'My Heading' }],
  data: { id: 'my-heading' }
};

export default function MyComponent() {
  return <MDXContent>{mdxHeading}</MDXContent>;
}

内容的提问来源于stack exchange，提问作者Pandabotu