Skeleton项目文档结构优化方案解析

背景与现状分析

Skeleton是一个支持多框架的UI组件库，目前文档系统采用了一种特殊的meta.mdx文件结构来管理不同框架间的共享元数据。这种设计虽然能够运行，但在实际使用中暴露出若干问题：

1. 数据分离：元数据与框架特定内容分离，需要手动合并
2. 内容重复：不同框架文档中存在大量重复内容
3. 扩展性差：当前方案仅适用于组件文档，难以扩展到指南类内容
4. URL处理复杂：需要在客户端重写URL以适配不同框架

优化方案设计

框架内容集合

首先建立一个框架内容集合作为单一数据源，包含项目支持的所有框架信息。例如创建svelte.json和react.json文件，定义各框架的基本属性。

动态框架组件

设计一个Astro框架组件，根据当前选择的框架动态渲染对应内容：

---
import { getCollection } from "astro:content";

const frameworks = await getCollection("frameworks");

function getSnippet(id?: string) {
  for (const framework of frameworks) {
    if (id === framework.id && Astro.slots.has(framework.id)) {
      return Astro.slots.render(framework.id);
    }
  }
  return Astro.slots.render("default");
}
---

<Fragment set:html={await getSnippet(Astro.params.framework)} />

该组件可灵活使用：

<Frameworks>
  <Fragment slot="svelte">Svelte专属内容</Fragment>
  <Fragment slot="react">React专属内容</Fragment>
</Frameworks>

文档结构调整

新的文档目录结构将框架标识前置：

docs/
 [framework]/
    [...page]/

URL格式变化示例：

• 旧URL: /docs/components/accordion/svelte
• 新URL: /docs/svelte/component/accordion

这种调整使得框架参数可在全站范围内访问，解决了框架特定内容的管理问题。

实现示例

以Accordion组件文档为例，新结构将合并原先分散的文件：

---
title: Accordion
description: 将内容划分为可折叠区域
sources:
- svelte: '/src/components/accordion'
- react: '/src/components/accordion'
- pattern: 'https://www.w3.org/WAI/ARIA/apg/patterns/accordion/'
- zag: 'https://zagjs.com/components/react/accordion'
showDocsUrl: true
---
import Frameworks from '@components/frameworks.astro';
import DefaultSvelte from '@examples/svelte/components/accordion/default.svelte';
import DefaultSvelteCode from '@examples/svelte/components/accordion/default.svelte?raw';
import DefaultReact from '@examples/react/components/accordion/default.tsx';
import DefaultReactCode from '@examples/react/components/accordion/default.tsx?raw';

## 默认示例

<Frameworks>
  <Fragment slot="svelte">
    <Preview client:load>
      <Fragment slot="preview">
        <DefaultSvelte client:visible />
      </Fragment>
      <Fragment slot="code">
        <Code code={DefaultSvelteCode} lang="svelte" />
      </Fragment>
    </Preview>
  </Fragment>
  <Fragment slot="react">
    <Preview client:load>
      <Fragment slot="preview">
        <DefaultReact client:visible />
      </Fragment>
      <Fragment slot="code">
        <Code code={DefaultReactCode} lang="tsx" />
      </Fragment>
    </Preview>
  </Fragment>
</Frameworks>

技术优势

1. 内容整合：消除分散的框架特定文件，统一管理内容
2. 减少重复：共享内容可直接编写，无需复制粘贴
3. 扩展性强：任何页面都可包含框架特定内容
4. SEO优化：服务端直接返回正确框架内容，提升搜索引擎收录质量
5. 维护简便：添加新框架只需在现有结构中增加对应插槽

实施考量

1. 渲染模式：需切换到Astro的按需渲染模式，放弃Pagefind搜索方案
2. URL变更：文档URL结构调整，用户需更新书签
3. 迁移成本：现有文档需要重构以适应新结构

专家建议

对于大型多框架项目，文档系统的设计应遵循以下原则：

1. DRY原则：尽可能避免重复，共享通用内容
2. 关注点分离：将框架特定内容与通用内容合理分离
3. 可扩展性：设计应便于新增框架支持
4. SEO友好：确保搜索引擎能正确索引各框架内容
5. 用户体验：保持URL结构清晰一致

Skeleton的文档优化方案体现了这些原则，通过Astro的动态组件能力和创新的内容组织结构，有效解决了多框架文档管理的核心痛点。虽然迁移需要一定成本，但从长期维护和扩展性角度看，这种调整将为项目带来显著收益。