配置指南

学习如何配置和自定义你的 shadcn-docs-nuxt 文档站点。

配置指南

shadcn-docs-nuxt 通过 app.config.ts 文件进行配置。本指南将介绍所有可用的配置选项和详细说明。

配置文件结构

所有配置都在 app.config.ts 文件中的 shadcnDocs 对象下进行设置：

export default defineAppConfig({
  shadcnDocs: {
    // 所有配置选项
  }
});

基础配置

站点信息

export default defineAppConfig({
  shadcnDocs: {
    site: {
      name: '我的文档站点',           // 站点名称，显示在浏览器标签页标题中
      description: '这是我的文档站点描述。', // 站点描述，用于 SEO
      ogImage: '/og-image.png',        // Open Graph 图片路径
      ogImageComponent: 'ShadcnDocs',  // 动态 OG 图片组件 (ShadcnDocs, Nuxt, NuxtSeo)
      ogImageColor: 'light',           // OG 图片颜色模式 ('light' | 'dark')
    }
  }
});

Umami 分析

export default defineAppConfig({
  shadcnDocs: {
    site: {
      umami: {
        // Umami 分析配置
      }
    }
  }
});

主题配置

export default defineAppConfig({
  shadcnDocs: {
    theme: {
      customizable: true,    // 是否允许用户自定义主题（显示自定义按钮）
      color: 'zinc',         // 主题颜色
      radius: '0.5',         // 默认圆角大小
    }
  }
});

横幅配置

export default defineAppConfig({
  shadcnDocs: {
    banner: {
      enable: false,         // 是否启用横幅
      showClose: true,       // 是否显示关闭按钮
      to: '/announcement',   // 点击跳转链接（可选）
      content: '欢迎访问我们的文档！', // 横幅内容（支持 MDC 解析）
      target: '_blank',      // 链接打开方式
      border: true,          // 是否显示底部边框
    }
  }
});

头部配置

基本设置

export default defineAppConfig({
  shadcnDocs: {
    header: {
      showLoadingIndicator: true,  // 是否显示 Nuxt 加载指示器
      title: '我的文档',           // 头部标题
      showTitle: true,             // 是否显示标题文本
      border: false,               // 是否显示头部底部边框
      darkModeToggle: true,        // 是否显示深色模式切换按钮
      languageSwitcher: {          // 语言切换器配置
        // 语言切换器选项
      },
      logo: {
        light: '/logo.svg',        // 浅色模式下的 Logo
        dark: '/logo-dark.svg',    // 深色模式下的 Logo
      },
      showTitleInMobile: false,    // 是否在移动端显示 Logo 和标题
    }
  }
});

导航菜单

export default defineAppConfig({
  shadcnDocs: {
    header: {
      nav: [
        {
          title: '首页',
          to: '/'
        },
        {
          title: '文档',
          to: '/docs/getting-started/introduction'
        },
        {
          title: '指南',
          to: '/docs/guide/configuration'
        }
      ],
      links: [
        {
          icon: 'lucide:github',
          to: 'https://github.com/Yan-nian/YY-Docs',
          target: '_blank',
        }
      ]
    }
  }
});

侧边栏配置

export default defineAppConfig({
  shadcnDocs: {
    aside: {
      useLevel: true,              // 是否使用层级样式侧边栏
      levelStyle: 'aside',         // 层级样式类型 ('header' | 'aside')
      headerLevelNavAlign: 'start', // 头部层级导航对齐方式 ('start' | 'center' | 'end')
      collapse: false,             // 是否默认折叠所有文件夹
      collapseLevel: 1,            // 折叠深度超过指定级别的文件夹
      folderStyle: 'default',      // 文件夹样式 ('default' | 'tree' | 'group')
    }
  }
});

::: tip 层级样式说明

levelStyle: 'header'：顶级链接显示在头部
levelStyle: 'aside'：顶级链接显示在侧边栏
headerLevelNavAlign 仅在 levelStyle 设置为 header 时生效 :::

主内容区配置

export default defineAppConfig({
  shadcnDocs: {
    main: {
      padded: true,              // 页面是否有内边距
      breadCrumb: true,          // 显示面包屑导航
      showTitle: true,           // 显示标题部分
      codeCopyToast: false,      // 代码复制时是否显示提示
      codeCopyIcon: 'lucide:copy', // 代码复制按钮图标
      codeCopyToastText: 'Copied to clipboard!', // 复制提示文本
      fieldRequiredText: 'required', // 字段必填提示文本
      pm: ['npm', 'pnpm', 'bun', 'yarn'], // 包管理器组件显示的选项
      codeIcon: {                // 代码组件头部的语言/文件名图标映射
        'javascript': 'vscode-icons:file-type-js',
        'typescript': 'vscode-icons:file-type-typescript',
        'vue': 'vscode-icons:file-type-vue',
        // 更多映射...
      },
      imageZoom: true,           // 是否启用图片缩放功能（点击图片放大）
    }
  }
});

编辑链接配置

export default defineAppConfig({
  shadcnDocs: {
    main: {
      editLink: {
        // 编辑链接配置
      },
      backToTop: true,           // 是否显示返回顶部按钮
    }
  }
});

目录配置

export default defineAppConfig({
  shadcnDocs: {
    toc: {
      enable: true,              // 是否启用目录部分
      enableInMobile: false,     // 是否在移动端启用目录
      enableInHomepage: false,   // 是否在首页启用目录
      title: 'On This Page',     // 目录部分标题
      links: [                   // 目录下方的链接
        {
          title: 'GitHub',
          icon: 'lucide:github',
          to: 'https://github.com/Yan-nian/YY-Docs',
          target: '_blank',
        }
      ],
      iconLinks: [               // 目录下方的图标链接
        {
          icon: 'lucide:github',
          to: 'https://github.com/Yan-nian/YY-Docs',
          target: '_blank',
        }
      ]
    }
  }
});

Carbon Ads 配置

export default defineAppConfig({
  shadcnDocs: {
    toc: {
      carbonAds: {
        // Carbon Ads 广告配置
      }
    }
  }
});

搜索配置

export default defineAppConfig({
  shadcnDocs: {
    search: {
      enable: true,                    // 是否启用搜索功能
      inAside: false,                  // 是否在侧边栏显示搜索栏
      style: 'input',                  // 搜索栏样式 ('input' | 'button')
      placeholder: 'Search...',        // 搜索栏占位符文本
      placeholderDetailed: 'Search documentation...', // 搜索对话框输入框占位符
      data: {
        // 搜索数据配置
      }
    }
  }
});

::: tip 搜索样式说明

style: 'input'：搜索栏显示为输入框
style: 'button'：搜索栏显示为按钮（推荐在移动端显示 Logo 和标题时使用） :::

页脚配置

export default defineAppConfig({
  shadcnDocs: {
    footer: {
      credits: 'Copyright © 2024 我的公司',
      links: [
        {
          icon: 'lucide:github',
          to: 'https://github.com/Yan-nian/YY-Docs',
          target: '_blank',
        }
      ]
    }
  }
});

完整配置示例

export default defineAppConfig({
  shadcnDocs: {
    site: {
      name: '我的文档站点',
      description: '一个基于 shadcn-docs-nuxt 构建的文档站点。',
      ogImage: '/og-image.png',
      ogImageComponent: 'ShadcnDocs',
      ogImageColor: 'light',
    },
    theme: {
      customizable: true,
      color: 'blue',
      radius: '0.5',
    },
    banner: {
      enable: false,
      showClose: true,
      content: '欢迎访问我们的文档站点！',
      border: true,
    },
    header: {
      showLoadingIndicator: true,
      title: '我的文档',
      showTitle: true,
      border: false,
      darkModeToggle: true,
      logo: {
        light: '/logo.svg',
        dark: '/logo-dark.svg',
      },
      showTitleInMobile: false,
      nav: [
        { title: '首页', to: '/' },
        { title: '文档', to: '/docs/getting-started/introduction' },
        { title: '指南', to: '/docs/guide/configuration' }
      ],
      links: [
        {
          icon: 'lucide:github',
          to: 'https://github.com/Yan-nian/YY-Docs',
          target: '_blank',
        }
      ]
    },
    aside: {
      useLevel: true,
      levelStyle: 'aside',
      headerLevelNavAlign: 'start',
      collapse: false,
      collapseLevel: 1,
      folderStyle: 'default',
    },
    main: {
      padded: true,
      breadCrumb: true,
      showTitle: true,
      codeCopyToast: false,
      codeCopyIcon: 'lucide:copy',
      imageZoom: true,
      backToTop: true,
    },
    footer: {
      credits: 'Copyright © 2024',
      links: [
        {
          icon: 'lucide:github',
          to: 'https://github.com/Yan-nian/YY-Docs',
          target: '_blank',
        }
      ]
    },
    toc: {
      enable: true,
      enableInMobile: false,
      enableInHomepage: false,
      title: 'On This Page',
      links: [
        {
          title: 'GitHub',
          icon: 'lucide:github',
          to: 'https://github.com/Yan-nian/YY-Docs',
          target: '_blank',
        }
      ]
    },
    search: {
      enable: true,
      inAside: false,
      style: 'input',
      placeholder: 'Search...',
      placeholderDetailed: 'Search documentation...',
    }
  }
});

图标配置

所有可配置的图标都可以设置为 iconify 图标、emoji 和 URL，使用 smart icon 进行处理。

export default defineAppConfig({
  shadcnDocs: {
    // 示例：使用不同类型的图标
    header: {
      logo: {
        light: '/logo.svg',           // URL 图标
        dark: '/logo-dark.svg',       // URL 图标
      }
    },
    main: {
      codeCopyIcon: 'lucide:copy',    // Iconify 图标
    },
    footer: {
      links: [
        {
          icon: '🚀',                 // Emoji 图标
          to: '/getting-started',
        },
        {
          icon: 'lucide:github',      // Iconify 图标
          to: 'https://github.com/example',
        }
      ]
    }
  }
});

类型定义

INav 接口

interface INav {
  title: string;
  to?: string;
  target?: string;
  // 其他导航属性
}

ILink 接口

interface ILink {
  title?: string;
  icon?: string;
  to: string;
  target?: string;
}

高级配置

默认配置

shadcn-docs-nuxt 提供了合理的默认配置，你只需要覆盖需要自定义的部分。0

配置验证

配置文件会在构建时进行验证，确保所有选项都符合预期的类型和格式。

环境变量

某些配置选项可以通过环境变量进行覆盖，特别是在不同部署环境中需要不同配置的情况下。

更多详细信息和最新配置选项，请参考 shadcn-docs-nuxt 官方文档。

使用指南

详细的使用指南和教程，帮助你快速上手和深入了解项目。

组件使用教程

shadcn-docs-nuxt 中所有可用组件的详细使用指南和示例。