核心概念

主题

借助 Nuxt UI 灵活的主题系统自定义 Docus 文档外观。

Docus 构建在 Nuxt UI 之上，并充分利用 Tailwind CSS v4 与 CSS 变量。Tailwind Variants API 提供了灵活、可扩展的主题系统。

想了解 Nuxt UI 主题能力的完整概览，请查看 Nuxt UI 文档。

使用 `@theme` 覆盖

你可以在 @theme 指令中使用 CSS 变量来自定义主题，定义项目自己的设计 token，例如字体、颜色和断点。

要覆盖主题，请在项目中创建 app/app.css 文件：

app/app.css

@theme {
  --font-sans: 'Public Sans', sans-serif;

  --breakpoint-3xl: 1920px;

  --color-green-50: #EFFDF5;
  --color-green-100: #D9FBE8;
  --color-green-200: #B3F5D1;
  --color-green-300: #75EDAE;
  --color-green-400: #00DC82;
  --color-green-500: #00C16A;
  --color-green-600: #00A155;
  --color-green-700: #007F45;
  --color-green-800: #016538;
  --color-green-900: #0A5331;
  --color-green-950: #052E16;
}

Docus 会自动导入 app/app.css，你不需要把它添加到 nuxt.config.ts 的 css 数组中，也不应该在此文件中包含 @import "tailwindcss"，因为 Docus 会为你处理。

颜色

Docus 使用预配置的颜色别名来设置组件样式，并驱动整个 UI 中的 color props。

下面每个徽章都代表一个默认别名：

primary → 主品牌色，作为组件默认颜色
(默认：green)
secondary → 用于补充主色的辅助色
(默认：blue)
success → 用于成功状态
(默认：green)
info → 用于信息提示状态
(默认：blue)
warning → 用于警告状态
(默认：yellow)
error → 用于表单错误校验状态
(默认：red)
neutral → 用于背景、文字等中性色
(默认：slate)

你可以在 app.config.ts 的 ui.colors 下全局自定义这些颜色：

app.config.ts

export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',
      neutral: 'zinc'
    }
  }
})

组件

除了颜色，所有 Nuxt UI 组件都可以通过 app.config.ts 全局设置主题。

你可以使用与组件内部主题对象相同的结构覆盖任意组件外观（可在每个组件页面底部查看）。

例如，修改所有按钮的字体粗细：

app.config.ts

export default defineAppConfig({
  ui: {
    button: {
      slots: {
        base: 'font-bold'
      }
    }
  }
})

在这个例子中，font-bold class 会覆盖所有按钮默认的 font-medium class。

要查看每个组件可用的主题选项，请参考对应 Nuxt UI 文档页面中的 Theme 章节。

Docus 子组件

Docus 内部使用多个 Nuxt UI 组件来构建导航、目录和子导航。你可以在 app.config.ts 中通过 defaultVariants 键自定义它们的默认 variants，而无需覆盖整个组件。

以下组件可配置：

组件	Key	默认值
ContentToc	`ui.contentToc`	`highlight: true`
ContentNavigation	`ui.contentNavigation`	`variant: 'link'`, `highlight: true`
NavigationMenu	`ui.navigationMenu`	`variant: 'pill'`, `highlight: true`

例如，把目录高亮样式改为 circuit，并把侧边栏导航 variant 切换为 pill：

app.config.ts

export default defineAppConfig({
  ui: {
    contentToc: {
      defaultVariants: {
        highlightVariant: 'circuit',
        highlightColor: 'secondary'
      }
    },
    contentNavigation: {
      defaultVariants: {
        variant: 'pill',
        highlight: false
      }
    }
  }
})

每个组件支持以下 variant 选项：

highlight — 显示激活指示线（true 或 false）
highlightColor — 指示器颜色（primary、secondary、neutral 等）
variant — 视觉样式（适用时为 pill 或 link）
highlightVariant — 指示器样式（仅 ContentToc，straight 或 circuit）
color — 激活链接的基础颜色

配置

通过 Nuxt 应用配置文件自定义 Docus 文档。

自定义

学习如何覆盖 Docus 内置组件来自定义文档。

主题

使用 @theme 覆盖

颜色

组件

Docus 子组件

使用 `@theme` 覆盖