workspace/code/g3soft-libs/docs/.vitepress/config.mts

import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vitepress'
import type { DefaultTheme } from 'vitepress'
import llmstxt from 'vitepress-plugin-llms'
import { vitepressDemoPlugin } from 'vitepress-demo-plugin/markdown'

/**
 * VitePress 的 SidebarItem 没有 icon 字段，这里扩展一个。
 *
 * icon 必须是「名字字符串」（如 'boxes'），渲染时由 theme/sidebarIcons.ts
 * 查表映射到 Lucide 组件。不能直接写组件对象：themeConfig.sidebar 会被
 * VitePress 序列化，组件引用在此过程中丢失（详见 sidebarIcons.ts）。
 */
type G3SidebarItem = DefaultTheme.SidebarItem & {
  icon?: string
  items?: G3SidebarItem[]
}

/**
 * 文档站（VitePress 默认主题）。
 *
 * 几个刻意的选择：
 *  - srcDir: 'content' —— Markdown 全部在 docs/content 下，站点根即 content/
 *  - alias 直连 packages 源码 —— 组件库 / framework 尚未构建也能开发，改组件即时热更
 *    （tokens 例外：它是 SCSS 编译产物，alias 指向 dist/index.css，需先 build tokens）
 *
 * 部署到子路径时用环境变量 DOCS_BASE_URL=/docs/，不在配置里写死。
 */
export default defineConfig({
  srcDir: 'content',
  base: process.env.DOCS_BASE_URL || '/',
  cleanUrls: true,
  lang: 'zh-CN',
  title: 'G3Soft 技术文档',
  description: 'G3Soft 技术文档：组件库、设计变量、工程规范与设计决策。',

  // sitemap.xml 由 VitePress 内置生成，hostname 决定绝对 URL。
  sitemap: {
    hostname: process.env.DOCS_SITE_URL || 'https://ui.g3soft.dev',
  },

  markdown: {
    // 代码块配色（shiki 内置主题），亮/暗各一套
    theme: { light: 'vitesse-light', dark: 'vitesse-dark' },
    config(md) {
      // 组件示例容器：md 里写 <demo vue="button/basic.vue" />
      // demoDir 作为示例文件基准目录，路径相对它解析（这里指向 docs/examples）
      md.use(vitepressDemoPlugin, {
        demoDir: fileURLToPath(new URL('../examples', import.meta.url)),
        lightTheme: 'vitesse-light',
        darkTheme: 'vitesse-dark',
      })
    },
  },

  vite: {
    // 构建期生成 llms.txt / llms-full.txt 与每页 .md 版本
    plugins: [llmstxt()],
    resolve: {
      // 用正则做“精确匹配”：否则 '@g3soft/tokens' 的前缀别名会把
      // '@g3soft/tokens/scss' 也一并改写掉，导致组件里的 @use 找不到 SCSS。
      alias: [
        {
          find: /^@g3soft\/ui$/,
          replacement: fileURLToPath(new URL('../../packages/ui/src/index.ts', import.meta.url)),
        },
        {
          // framework 也直连源码：改布局 / 偏好即时热更
          find: /^@g3soft\/framework$/,
          replacement: fileURLToPath(
            new URL('../../packages/framework/src/index.ts', import.meta.url),
          ),
        },
        {
          // tokens 是 SCSS 编译产物：仅裸导入指向 dist/index.css（由 @g3soft/tokens 的 build 生成）
          find: /^@g3soft\/tokens$/,
          replacement: fileURLToPath(
            new URL('../../packages/tokens/dist/index.css', import.meta.url),
          ),
        },
      ],
    },
    server: {
      // 默认 5173 常被其它 Vite 项目占用，这里固定用 3100；
      // strictPort: false 让端口冲突时自动往后顺延（3101、3102…），
      // 而不是直接报错退出。实际端口以终端输出为准。
      port: 3100,
      strictPort: false,
      fs: {
        // 组件库源码在 docs 目录之外，需要放开读取范围
        allow: [fileURLToPath(new URL('../..', import.meta.url))],
      },
    },
  },

  themeConfig: {
    nav: [],

    // 按路径前缀分段，替代原 Docus 的 .navigation.yml 与 navigation.sub：
    // 进入某板块时侧边栏只显示该板块的页面。
    // collapsed: false 是 VitePress 渲染折叠箭头的前提 —— 只有显式设置
    // item.collapsed 才会输出 .caret 节点（见 VPSidebarItem.vue）。
    // 默认展开，与 Docus 侧栏一致。
    sidebar: {
      '/guide/': [
        {
          text: '指南',
          icon: 'component',
          collapsed: false,
          items: [{ text: '快速开始', link: '/guide/getting-started' }],
        },
      ] satisfies G3SidebarItem[],
      '/ui/': [
        {
          text: '使用',
          icon: 'boxes',
          collapsed: false,
          items: [{ text: '快速上手', link: '/ui/usage/getting-started' }],
        },
        {
          text: '通用组件',
          icon: 'layers',
          collapsed: false,
          items: [
            { text: 'Button 按钮', link: '/ui/general/button' },
            { text: 'ButtonGroup 按钮组', link: '/ui/general/button-group' },
            { text: 'Grid 栅格', link: '/ui/general/grid' },
            { text: 'Segmented 分段控制器', link: '/ui/general/segmented' },
            { text: 'Space 间距', link: '/ui/general/space' },
            { text: 'Tag 标签', link: '/ui/general/tag' },
          ],
        },
        {
          text: '数据录入',
          icon: 'form-input',
          collapsed: false,
          items: [
            { text: 'Checkbox 复选框', link: '/ui/form/checkbox' },
            { text: 'Form 表单', link: '/ui/form/form' },
            { text: 'Input 输入框', link: '/ui/form/input' },
            { text: 'Radio 单选框', link: '/ui/form/radio' },
            { text: 'Select 选择器', link: '/ui/form/select' },
            { text: 'Switch 开关', link: '/ui/form/switch' },
          ],
        },
        {
          text: '浮层与导航',
          icon: 'layers',
          collapsed: false,
          items: [
            { text: 'Drawer 抽屉', link: '/ui/overlay/drawer' },
            { text: 'Dropdown 下拉菜单', link: '/ui/overlay/dropdown' },
            { text: 'Modal 对话框', link: '/ui/overlay/modal' },
            { text: 'Popover 气泡卡片', link: '/ui/overlay/popover' },
            { text: 'Tooltip 文字提示', link: '/ui/overlay/tooltip' },
          ],
        },
        {
          text: '反馈',
          icon: 'message-square',
          collapsed: false,
          items: [
            { text: 'Message 轻提示', link: '/ui/feedback/message' },
            { text: 'Notification 通知提醒', link: '/ui/feedback/notification' },
            { text: 'Scrollbar 滚动容器', link: '/ui/feedback/scrollbar' },
            { text: 'Spin 加载中', link: '/ui/feedback/spin' },
          ],
        },
        {
          text: '数据展示',
          icon: 'table-properties',
          collapsed: false,
          items: [
            { text: 'DatePicker 日期选择', link: '/ui/data/date' },
            { text: 'Pagination 分页器', link: '/ui/data/pagination' },
            { text: 'Splitter 分割面板', link: '/ui/data/splitter' },
            { text: 'Tabs 标签页', link: '/ui/data/tabs' },
            { text: 'Tree 树形控件', link: '/ui/data/tree' },
          ],
        },
      ] satisfies G3SidebarItem[],
      '/framework/': [
        {
          text: '布局',
          icon: 'layout-dashboard',
          collapsed: false,
          items: [{ text: 'Layout 布局框架', link: '/framework/layout' }],
        },
      ] satisfies G3SidebarItem[],
      '/api/': [
        {
          text: '接口文档',
          icon: 'cable',
          collapsed: false,
          items: [{ text: '快速开始', link: '/api/getting-started' }],
        },
      ] satisfies G3SidebarItem[],
    },

    // 内置本地搜索（minisearch），不再依赖 better-sqlite3
    search: { provider: 'local' },
    outline: { level: [2, 3], label: '本页目录' },
  },
})