Implement Root Toggle for multi-root documentation structure

[Copilot]

Enables switching between multiple documentation roots (e.g., Core Engine, Platform) via Fumadocs' native Root Toggle dropdown, following the "configuration as code" philosophy.

Changes

Content Structure

• Restructured content/docs/ to support multiple roots (core/, platform/)
• Moved existing docs to core/, added sample Platform documentation

Configuration

• Extended docs.site.json with products array for defining documentation roots
• Updated SiteConfig TypeScript interface to support products configuration

{
  "products": [
    {
      "title": "Documentation",
      "description": "Core documentation engine",
      "url": "/docs/core",
      "icon": "FileText"
    },
    {
      "title": "Platform",
      "description": "Enterprise platform docs", 
      "url": "/docs/platform",
      "icon": "Layers"
    }
  ]
}

Source Configuration

• Modified source.config.ts to define multiple defineDocs() instances
• Created separate loaders (coreLoader, platformLoader) for independent documentation roots
• Updated page and search routes to use appropriate loader based on URL

Layout Integration

• Updated app/[lang]/docs/layout.tsx to render Root Toggle dropdown via tabs prop
• Implemented icon mapping with 10+ lucide-react icons
• Uses theme colors (primary/primary-foreground) for consistency
• Dynamic loader selection based on current URL path

Dependencies

• Added lucide-react for icon support
• Fixed MDX module resolution by installing in content/ directory

Screenshots

Root Toggle Dropdown:

The dropdown selector appears at the top of the sidebar (below the search bar) and allows users to switch between documentation roots:

Core Documentation:

Platform Documentation:

How It Works

The Root Toggle dropdown uses Fumadocs' native SidebarTabsDropdown component, which automatically renders when the tabs prop contains multiple items. Users can click the dropdown to see all available documentation roots (with icons and descriptions) and navigate between them. Each root has its own independent page tree and URL structure (/docs/core, /docs/platform).

Usage

Add new documentation roots by updating docs.site.json and creating corresponding content directories. No React knowledge required.

{
  "products": [
    {
      "title": "Your Product",
      "description": "Product description",
      "url": "/docs/your-product",
      "icon": "Package"
    }
  ]
}

Then create content/docs/your-product/ and add it to source.config.ts.

Original prompt

Fumadocs 官网左上角的那个“多框架/多产品选择器”，官方术语叫 Root Toggle (根节点切换器)。
它的核心原理是：把文档内容拆分成几个独立的“根目录” (Roots)，通过 UI 组件在它们之间切换。
比如 Fumadocs 官网就是拆分成了 Core (核心库) 和 UI (组件库) 两个独立的部分，侧边栏是互不干扰的。
结合你想要的 元数据驱动 (JSON) 模式，实现这个功能的完整步骤如下：

1. 目录结构设计
   首先，你的 content/docs 必须从“单根”变成“多根”。
   Before (单产品):
   content/docs/
   ├── index.mdx
   └── guide/

After (多产品/多框架):
content/docs/
├── core/ # 第一个产品（例如 Amis）
│ ├── meta.json
│ └── index.mdx
└── ui/ # 第二个产品（例如 Steedos）
├── meta.json
└── index.mdx

2. 定义元数据 (site.json)
   我们需要在你的 site.json 里增加一个 products 字段，用来定义下拉菜单里的选项。
   config/site.json
   {
   "products": [
   {
   "title": "Amis 引擎",
   "description": "前端低代码渲染器",
   "url": "/docs/core",
   "icon": "Box"
   },
   {
   "title": "Steedos 平台",
   "description": "企业级后端低代码",
   "url": "/docs/platform",
   "icon": "Layers"
   }
   ]
   // ... 其他配置
   }

3. 代码实现 (Layout 集成)
   Fumadocs 提供了一个现成的组件 ，它可以直接放在 Sidebar 的 Banner 位置。
   你需要做两件事：

• 渲染切换器：把 JSON 转换成 的 props。
• 切割侧边栏：根据当前 URL，只显示对应产品的侧边栏（否则 Amis 和 Steedos 的菜单会混在一起）。
  文件：app/docs/[[...slug]]/layout.tsx
  import { DocsLayout } from 'fumadocs-ui/layout';
  import { RootToggle } from 'fumadocs-ui/components/layout/root-toggle'; // 核心组件
  import { source } from '@/lib/source';
  import { config } from '@/lib/config-loader'; // 你的 JSON
  import { Box, Layers } from 'lucide-react'; // 图标

// 图标映射表 (因为 JSON 不能存组件)
const icons = {
Box: Box,
Layers: Layers
};

export default function Layout({ children, params }: {
children: React.ReactNode,
params: { slug?: string[] }
}) {

// 1. 获取当前属于哪个产品 (core 或 platform)
// 假设 slug[0] 就是产品名
const currentProduct = params.slug?.[0] || 'core';

// 2. 这里的核心魔法：只筛选出当前产品的 pageTree
// source.pageTree 是全量的，我们需要根据 root 过滤
const tree = source.pageTree[currentProduct] || source.pageTree;

return (
<DocsLayout
tree={tree} // 传入切割后的树

  sidebar={{
    // 3. 在侧边栏顶部植入 Root Toggle
    banner: (
      <RootToggle
        options={config.products.map(product => ({
          title: product.title,
          description: product.description,
          url: product.url,
          icon: (
            <div className="bg-gradient-to-br from-blue-500 to-purple-500 p-1 rounded-md text-white">
              {/* 动态渲染图标 */}
              {icons[product.icon] ? icons[product.icon]({}) : <Box />}
            </div>
          ),
        }))}
      />
    ),
  }}
  // ... 其他配置
>
  {children}
</DocsLayout>

);
}

4. 这里的核心逻辑 (How it works)

• Visual (视觉)： 组件自带了类似 Popover/Select 的交互，点击后弹出下拉菜单，样式非常精美（支持标题+描述+图标）。
• Routing (路由)：当你点击下拉菜单里的 "Steedos 平台" 时，URL 会跳转到 /docs/platform。
• Context (上下文)：layout.tsx 重新执行，params.slug[0] 变成了 platform。代码逻辑会去 source.pageTree['platform'] 拿新的侧边栏数据。
• Result (结果)：左侧菜单瞬间从 Amis 的文档变成了 Steedos 的文档，实现了“隔离”。

5. 如果你不需要分目录，只是想单纯做个链接跳转
   如果你的需求没那么复杂（不需要切割侧边栏），只是想在左上角放个下拉菜单跳转到 GitHub 或其他地方，你可以直接用自定义组件：
   sidebar={{
   banner: (
   选择版本 window.location.href = e.target.value}> Version 1.0 Version 2.0

)
}}

但强烈建议使用官方的 ，因为它就是你要的那种“Fumadocs 原味”体验。

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
objectdocs-site	Ready	Preview, Comment	Jan 18, 2026 3:18am

[huangyiirene]

@copilot 没有看到下拉框的切换效果

[hotlong]

@copilot 继续

[Copilot]

@copilot 继续

已实现 Root Toggle 下拉框切换功能！✅

Changes in commit bb67cb1:

• 创建了独立的文档加载器 (coreLoader, platformLoader)
• 在 docs.site.json 中添加了 products 配置
• 实现了基于 URL 的动态树选择
• Fumadocs 自动渲染原生下拉选择器

下拉框位于侧边栏顶部（搜索框下方），点击可切换"Documentation"和"Platform"两个文档根目录。

[github-actions]

🚀 Preview Deployment

This pull request will be automatically deployed to Vercel.

Preview Links

• 📝 Documentation: Will be available once Vercel deployment completes
• 🌍 Languages: English (/en/docs) and Chinese (/cn/docs)

Build Status

Check the CI workflow for build status and any errors.

---

Automated preview information for PR #12

[github-actions]

🚀 Preview Deployment

This pull request will be automatically deployed to Vercel.

Preview Links

• 📝 Documentation: Will be available once Vercel deployment completes
• 🌍 Languages: English (/en/docs) and Chinese (/cn/docs)

Build Status

Check the CI workflow for build status and any errors.

---

Automated preview information for PR #12

[huangyiirene]

分拆为guide ,dev 两个 root @copilot