2-06 · 文档站架构（上）：manifest 驱动的 VitePress

// apps/docs/.vitepress/config.ts L1-11
import { defineConfig } from "vitepress";
import { componentDocsSidebarGroups } from "../../../packages/components/component-manifest";
import {
  proComponentDocsSidebarGroups,
  proComponentExampleSidebarGroups
} from "../../../packages/pro-components/component-manifest";
import { workspaceAlias } from "../../../scripts/config/aliases";
import { demoMdPlugin } from "./plugins/demo";
import { demoSourcePlugin } from "./plugins/demo-source";
import { markdownTransform } from "./plugins/markdown-transform";
import { tableWrapperMdPlugin } from "./plugins/table-wrapper";

// apps/docs/.vitepress/config.ts L13-25
export default defineConfig({
  title: "xiaoye-components",
  description: "通用基础组件库 + 中后台业务增强组件库",
  head: [
    ["link", { rel: "icon", type: "image/svg+xml", href: "/favicon.svg" }],
    ["meta", { property: "og:title", content: "xiaoye-components" }],
    ["meta", { property: "og:description", content: "企业级 Vue 3 组件库 — 基础组件 + 中后台增强组件 + 完整 TypeScript 支持" }],
    ["meta", { property: "og:type", content: "website" }],
    ["meta", { name: "keywords", content: "vue3, component library, typescript, xiaoye-components, 企业级组件库" }],
    ["script", { defer: "", src: "https://analytics.zhangzhengyang.com/script.js", "data-website-id": "4bdd9d50-f117-42dc-87c1-d25c2f7fb6ed" }]
  ],
  cleanUrls: true,
  lastUpdated: true,

// packages/components/component-manifest.ts L1-33
import manifestJson from "./component-manifest.json" with { type: "json" };

export type ComponentDocsGroup = "basic" | "form" | "feedback" | "data";

interface RawComponentInstallCheck {
  kind: "component" | "directive" | "globalProperty";
  name: string;
}

interface RawComponentManifestEntry {
  name: string;
  docsGroup: ComponentDocsGroup;
  docsText: string;
  installExports: string[];
  installChecks: RawComponentInstallCheck[];
  styleImports: string[];
}

export interface ComponentManifestEntry {
  name: string;
  docsGroup: ComponentDocsGroup;
  docsText: string;
  installExports: string[];
  installChecks: RawComponentInstallCheck[];
  install: {
    components: string[];
    directives: string[];
    globals: string[];
  };
  styleImports: string[];
}

const rawManifest = manifestJson as RawComponentManifestEntry[];

// packages/components/component-manifest.ts L35-57
const docsGroupTextMap: Record<ComponentDocsGroup, string> = {
  basic: "基础组件",
  form: "表单与录入",
  feedback: "反馈与浮层",
  data: "数据展示"
};

const docsGroupOrder: ComponentDocsGroup[] = ["basic", "form", "feedback", "data"];

export const componentManifest = rawManifest.map((entry) => ({
  ...entry,
  install: {
    components: entry.installChecks
      .filter((check) => check.kind === "component")
      .map((check) => check.name),
    directives: entry.installChecks
      .filter((check) => check.kind === "directive")
      .map((check) => check.name),
    globals: entry.installChecks
      .filter((check) => check.kind === "globalProperty")
      .map((check) => check.name)
  }
})) satisfies ComponentManifestEntry[];

// packages/components/component-manifest.ts L59-81
export const publicComponentNames = componentManifest.map((entry) => entry.name);

export const installableComponentExportNames = componentManifest.flatMap(
  (entry) => entry.installExports
);

export const installCheckEntries = componentManifest.flatMap((entry) => entry.installChecks);

export const themeStyleImportNames = Array.from(
  new Set(componentManifest.flatMap((entry) => entry.styleImports))
);

export const componentStyleImports = themeStyleImportNames;

export const componentDocsSidebarGroups = docsGroupOrder.map((group) => ({
  text: docsGroupTextMap[group],
  items: componentManifest
    .filter((entry) => entry.docsGroup === group)
    .map((entry) => ({
      text: entry.docsText,
      link: `/components/${entry.name}`
    }))
}));

// apps/docs/.vitepress/config.ts L104-110
      "/components/": [
        {
          text: "总览",
          items: [{ text: "组件总览", link: "/components/overview" }]
        },
        ...componentDocsSidebarGroups
      ],

// packages/pro-components/component-manifest.ts L72-90
export const proComponentDocsSidebarGroups = docsGroupOrder.map((group) => ({
  text: docsGroupTextMap[group],
  items: proComponentManifest
    .filter((entry) => entry.docsGroup === group)
    .map((entry) => ({
      text: entry.docsText,
      link: `/pro-components/${entry.name}`
    }))
}));

export const proComponentExampleSidebarGroups = docsGroupOrder.map((group) => ({
  text: docsGroupTextMap[group],
  items: proComponentManifest
    .filter((entry) => entry.docsGroup === group)
    .map((entry) => ({
      text: entry.docsText,
      link: `/examples/pro/${entry.name}`
    }))
}));

// apps/docs/.vitepress/config.ts L111-139
      "/pro-components/": [
        {
          text: "总览",
          items: [{ text: "增强组件总览", link: "/pro-components/overview" }]
        },
        ...proComponentDocsSidebarGroups
      ],
      "/examples/": [
        {
          text: "页面示例",
          items: [
            { text: "管理后台闭环示例", link: "/examples/admin" },
            { text: "Skeleton 场景示例", link: "/examples/skeleton" },
            { text: "Timeline 场景示例", link: "/examples/timeline" },
            { text: "Scheduler 场景示例", link: "/examples/scheduler" },
            { text: "Scheduler 业务接入模板", link: "/examples/scheduler-template" }
          ]
        },
        {
          text: "增强组件示例",
          items: [{ text: "增强组件总览", link: "/examples/pro/overview" }]
        },
        ...proComponentExampleSidebarGroups
          .map((group) => ({
            text: group.text,
            items: group.items
          }))
          .filter((group) => group.items.length > 0)
      ]

// apps/docs/.vitepress/config.ts L143-153
  markdown: {
    config(md) {
      demoMdPlugin(md);
      tableWrapperMdPlugin(md);
    }
  },
  vite: {
    plugins: [markdownTransform(), demoSourcePlugin()],
    resolve: {
      alias: workspaceAlias
    },

// apps/docs/.vitepress/plugins/demo.ts L116-119
        setDemoSource(demoPath, sourceItems);

        return `<Demo :source-loader="${componentName}SourceLoader" path="${demoPath}" description="${encodedDescription}"${needsSandbox ? " sandbox" : ""}>
  <template #source><${componentName} /></template>`;

// apps/docs/.vitepress/plugins/markdown-transform.ts L19-35
function injectImports(code: string, id: string, demoPaths: string[]) {
  const examplesRoot = resolveExamplesRoot(id);
  const declarations = demoPaths.map((demoPath) => {
    const componentName = getDemoComponentName(demoPath);
    const examplePath = path.resolve(examplesRoot, `${demoPath}.vue`);
    let relativePath = path.relative(path.dirname(id), examplePath).replaceAll(path.sep, "/");

    if (!relativePath.startsWith(".")) {
      relativePath = `./${relativePath}`;
    }

    return [
      `const ${componentName} = defineAsyncComponent(() => import("${relativePath}"));`,
      `const ${componentName}SourceLoader = () => import("virtual:xy-demo-source:${demoPath}");`
    ].join("\n");
  });
  const injectedBlock = `import { defineAsyncComponent } from "vue";\n${declarations.join("\n")}`;

// scripts/config/aliases.ts L103-115
  // xiaoye-components (bare import)
  {
    find: "xiaoye-components",
    replacement: resolveWorkspacePath("../../packages/components/index.ts")
  },
  {
    find: /^xiaoye-components\/(.*)$/,
    replacement: `${resolveWorkspacePath("../../packages/components/")}/$1`
  },
  {
    find: "xiaoye-pro-components",
    replacement: resolveWorkspacePath("../../packages/pro-components/index.ts")
  }

// scripts/config/aliases.ts L1-14
import { fileURLToPath, URL } from "node:url";

const resolveWorkspacePath = (target: string) => fileURLToPath(new URL(target, import.meta.url));

export const workspaceAlias = [
  // CSS files (must come before the general @xiaoye/primitives alias)
  {
    find: "@xiaoye/primitives/style.css",
    replacement: resolveWorkspacePath("../../packages/xiaoye-primitives/style.css")
  },
  {
    find: "xiaoye-primitives/style.css",
    replacement: resolveWorkspacePath("../../packages/xiaoye-primitives/style.css")
  },

// apps/docs/.vitepress/config.ts L154-157
    build: {
      // VitePress 1.6 依赖 cssCodeSplit:false 合并 CSS 并注入每个页面的 head；
      // 覆盖为 true 会导致构建产物全部样式丢失（dev 不受影响，故此前未暴露）。
      chunkSizeWarningLimit: 700,

// apps/docs/.vitepress/config.ts L158-183
      rollupOptions: {
        output: {
          manualChunks(id) {
            if (id.includes("node_modules/echarts")) {
              return "vendor-echarts";
            }

            if (
              id.includes("node_modules/video.js") ||
              id.includes("node_modules/vditor") ||
              id.includes("node_modules/howler")
            ) {
              return "vendor-media";
            }

            if (
              id.includes("node_modules/@fullcalendar") ||
              id.includes("node_modules/sortablejs") ||
              id.includes("node_modules/rrule")
            ) {
              return "vendor-scheduler";
            }
          }
        }
      }

// apps/docs/.vitepress/theme/index.ts L1-16
import { watch } from "vue";
import DefaultTheme from "vitepress/theme";
import type { Theme } from "vitepress";
import { useData, inBrowser } from "vitepress";
import XiaoyeComponents, {
  configProviderKey,
  createConfigProviderContext
} from "xiaoye-components";
import XiaoyeProComponents from "xiaoye-pro-components";
import Demo from "./components/Demo.vue";
import HomeProductLineDemo from "./components/HomeProductLineDemo.vue";
import ProjectIconGallery from "./components/ProjectIconGallery.vue";
import SchedulerPlaygroundFrame from "./components/SchedulerPlaygroundFrame.vue";
import "xiaoye-components/style.css";
import "xiaoye-pro-components/style.css";
import "./style.css";

// apps/docs/.vitepress/theme/index.ts L18-35
const DOCS_OVERLAY_Z_INDEX = 2100;

function syncDataTheme() {
  if (!inBrowser) return;
  const { isDark } = useData();
  const html = document.documentElement;

  const apply = (dark: boolean) => {
    if (dark) {
      html.setAttribute("data-theme", "dark");
    } else {
      html.removeAttribute("data-theme");
    }
  };

  apply(isDark.value);
  watch(isDark, apply);
}

// apps/docs/.vitepress/theme/index.ts L37-58
const theme: Theme = {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.provide(
      configProviderKey,
      createConfigProviderContext({
        zIndex: DOCS_OVERLAY_Z_INDEX
      })
    );
    app.use(XiaoyeComponents);
    app.use(XiaoyeProComponents);
    app.component("Demo", Demo);
    app.component("HomeProductLineDemo", HomeProductLineDemo);
    app.component("ProjectIconGallery", ProjectIconGallery);
    app.component("SchedulerPlaygroundFrame", SchedulerPlaygroundFrame);
  },
  setup() {
    syncDataTheme();
  }
};

export default theme;

// packages/xiaoye-primitives/src/composables/shared-context.ts L1-28（全文）
import type { ComputedRef, InjectionKey } from "vue";

export const configProviderKey: InjectionKey<SharedConfigContext> =
  Symbol.for("xiaoye-config-provider") as InjectionKey<SharedConfigContext>;

export type ComponentSize = "" | "xs" | "sm" | "md" | "lg" | "xl";

export interface Locale {
  emptyTitle?: string;
  emptyDescription?: string;
  popconfirmConfirmButtonText?: string;
  popconfirmCancelButtonText?: string;
}

export interface SharedConfigContext {
  namespace: ComputedRef<string>;
  locale: ComputedRef<Locale>;
  zIndex: ComputedRef<number>;
  size: ComputedRef<ComponentSize>;
  dialog: ComputedRef<unknown>;
  loading: ComputedRef<unknown>;
  message: ComputedRef<unknown>;
  notification: ComputedRef<unknown>;
}

export const DEFAULT_NAMESPACE = "xy";
export const DEFAULT_Z_INDEX = 2000;
export const DEFAULT_SIZE: ComponentSize = "md";

// packages/xiaoye-primitives/src/composables/use-z-index.ts（全文，17 行）
import { computed, ref } from "vue";

const seed = ref(0);

export function useZIndex() {
  const zIndex = computed(() => 2000);

  const next = () => {
    seed.value += 1;
    return zIndex.value + seed.value;
  };

  return {
    current: computed(() => zIndex.value + seed.value),
    next
  };
}

/* packages/xiaoye-primitives/src/theme/tokens.css L10（文件头注释） */
 * 主题切换协议：[data-theme="dark"] 只覆写语义层的值；基元层与刻度层全局共享。

/* packages/xiaoye-primitives/src/theme/tokens.css L256-266 */
/* ====================================================================
 * 暗色主题 — 语义层整体覆写（暗面锚点取自 Stripe 官方暗色目录：
 * 页面底 #0e0f2e / 主色提亮 #665efd / 标题 #e8ecf0 / 正文 #8a95a8 /
 * 边框 rgba(255,255,255,0.1) / 成功文字 #4cdf80 / 柠檬 #d4a04a）
 * ==================================================================== */
[data-theme="dark"] {
  /* 文字 */
  --xy-text-heading: #f2f5fa;
  --xy-text-primary: #e8ecf0;
  --xy-text-secondary: #b6c0cf;

// apps/docs/.vitepress/theme/components/Demo.vue L1-11
<script setup lang="ts">
import { computed, onMounted, ref, watch } from "vue";
import { useData } from "vitepress";
import type { DemoSourceItem } from "../../utils/demo-source";

const props = defineProps<{
  path: string;
  description: string;
  sandbox?: boolean;
  sourceLoader?: () => Promise<{ default: DemoSourceItem[] }>();
}>();

// apps/docs/.vitepress/theme/components/Demo.vue L30-40
const codeLink = computed(() => {
  const repo = theme.value.repo as string | undefined;
  const docsBranch = (theme.value.docsBranch as string | undefined) ?? "main";
  const docsDir = (theme.value.docsDir as string | undefined) ?? "apps/docs";

  if (!repo) {
    return "";
  }

  return `https://github.com/${repo}/blob/${docsBranch}/${docsDir}/examples/${props.path}.vue`;
});

// apps/docs/.vitepress/theme/components/Demo.vue L42-56
async function ensureSourcesLoaded() {
  if (sourcesLoaded.value || sourcesLoading.value || !props.sourceLoader) {
    return;
  }

  sourcesLoading.value = true;

  try {
    const module = await props.sourceLoader();
    sourceItems.value = module.default.filter((item) => item.raw.trim().length > 0);
    sourcesLoaded.value = true;
  } finally {
    sourcesLoading.value = false;
  }
}

// apps/docs/.vitepress/theme/components/Demo.vue L89-95
watch(expanded, async (value) => {
  if (!value) {
    return;
  }

  await ensureSourcesLoaded();
});

<!-- apps/docs/.vitepress/theme/components/Demo.vue L106-165 -->
<template>
  <div class="vp-demo-block" v-html="decodedDescription" />

  <div class="vp-demo" :class="{ 'vp-demo--table': isTableDemo }">
    <div class="vp-demo__showcase">
      <div v-if="needsSandbox" class="xy-doc-sandbox">
        <slot name="source" />
      </div>
      <slot v-else name="source" />
    </div>

    <div class="vp-demo__toolbar">
      <div v-if="sourceItems.length" class="vp-demo__tabs">
        <button
          v-for="item in sourceItems"
          :key="item.label"
          class="vp-demo__tab"
          :class="{ 'is-active': item.label === activeLang }"
          type="button"
          @click="activeLang = item.label"
        >
          {{ item.label }}
        </button>
      </div>

      <div class="vp-demo__actions">
        <a
          v-if="codeLink"
          class="vp-demo__icon-btn"
          :href="codeLink"
          target="_blank"
          rel="noreferrer"
          aria-label="查看源码"
        >
          <xy-icon icon="mdi:github" />
        </a>

        <button class="vp-demo__icon-btn" type="button" aria-label="复制代码" @click="copySource">
          <xy-icon :icon="copied ? 'mdi:check' : 'mdi:content-copy'" />
        </button>

        <button
          class="vp-demo__icon-btn"
          type="button"
          :aria-label="expanded ? '收起代码' : '查看代码'"
          @click="expanded = !expanded"
        >
          <xy-icon :icon="expanded ? 'mdi:chevron-up' : 'mdi:code-tags'" />
        </button>
      </div>
    </div>

    <div v-if="expanded && sourcesLoading" class="vp-demo__source">
      <div class="vp-demo__loading">代码加载中...</div>
    </div>

    <div v-else-if="expanded && currentSource" class="vp-demo__source">
      <div class="vp-demo__source-inner" v-html="currentSource.rendered" />
    </div>
  </div>
</template>