如何在Docusaurus站点中以iframe加载外部页面并保留ToC？

一、Docusaurus 中的实现方式 #

1. 基础方案：新建嵌入页面 #

• 在你的 Docusaurus 项目里新增一个 Markdown 文件（比如 docs/external-api-method.md），直接在文件里写 iframe 代码：

<iframe src="https://你的外部API方法地址" width="100%" height="800px" frameborder="0"></iframe>

• 打开项目根目录的 sidebars.js，把这个新页面加到你想要的目录位置，比如：

module.exports = {
  docs: [
    'intro',
    {
      type: 'category',
      label: 'API 文档',
      items: [
        'internal-api-overview',
        'external-api-method' // 这里添加你新建的页面
      ],
    },
    // 保留原有所有目录项
  ],
};

这样点击目录里的对应选项，就会在 Docusaurus 原有布局（侧边栏、顶部导航都保留）里加载外部页面的 iframe。

2. 进阶方案：动态加载不同外部链接 #

如果需要在目录里直接指向多个不同的外部API方法，不用新建多个页面，可以用动态参数实现：

• 先建一个带 React 组件的页面（比如 docs/iframe-proxy.jsx），用来读取 URL 参数加载对应外部地址：

import React from 'react';
import { useLocation } from '@docusaurus/router';

export default function IframeProxy() {
  const location = useLocation();
  const params = new URLSearchParams(location.search);
  const targetUrl = params.get('url') || 'https://默认外部地址';
  return (
    <iframe src={targetUrl} width="100%" height="90vh" frameborder="0" />
  );
}

• 然后在 sidebars.js 里添加带参数的链接型目录项：

module.exports = {
  docs: [
    'intro',
    {
      type: 'category',
      label: 'API 文档',
      items: [
        'internal-api-overview',
        {
          type: 'link',
          label: '用户查询API',
          href: '/docs/iframe-proxy?url=https://你的外部API门户/用户查询方法',
        },
        {
          type: 'link',
          label: '数据提交API',
          href: '/docs/iframe-proxy?url=https://你的外部API门户/数据提交方法',
        },
      ],
    },
    // 原有目录项不动
  ],
};

二、其他 Markdown/RST 类工具的实现思路 #

• MkDocs：用 mkdocs-material 主题的话，可以直接在 Markdown 里写 iframe 代码，或者用第三方插件辅助，然后在 mkdocs.yml 的 nav 配置里添加指向该页面的导航项即可。
• Sphinx（RST）：用 raw 指令嵌入 iframe 代码生成对应页面，再把页面加入 toctree 结构，就能在 Sphinx 的默认布局里加载外部页面。

⚠️ 注意：部分外部网站会设置 X-Frame-Options 响应头禁止被嵌入 iframe，这种情况没法实现，需要先确认目标网站允许被 iframe 嵌套。

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