---
description: 用 CSS 变量、稳定 slot 和可选 Tailwind CSS 自定义 Doctrine。
---

# 自定义

Doctrine 有两个项目级扩展点：用样式表调整外观，用 React 组件映射扩展 MDX。内置组件参考见
[MDX 组件](/zh-CN/mdx-components/)。

## 添加样式表

用 `styles` 指向从项目 root 解析出的现有文件：

```ts
import { defineConfig } from '@amamo/doctrine'

export default defineConfig({
  styles: './docs/theme.css',
})
```

Doctrine 会在预编译运行时 CSS 之后 import 这个文件。只覆盖网站实际需要的值：

```css
:root {
  --doctrine-accent: oklch(0.9 0.05 155);
  --doctrine-accent-foreground: oklch(0.25 0.04 155);
  --doctrine-separator: oklch(0.88 0.025 155);
  --doctrine-sidebar: oklch(0.97 0.01 155);
  --doctrine-ring: oklch(0.48 0.12 155);
  --doctrine-radius: 0.9rem;
  --doctrine-font-sans: Inter, sans-serif;
  --doctrine-font-mono: 'JetBrains Mono', monospace;
  --doctrine-content-width: 52rem;
}

[data-theme='dark'] {
  --doctrine-background: oklch(0.14 0.02 250);
  --doctrine-muted: oklch(0.21 0.02 250);
}
```

### 主题变量

| 变量                                                                | 控制内容               |
| ------------------------------------------------------------------- | ---------------------- |
| `--doctrine-background`、`--doctrine-foreground`                    | 页面背景与主要文字     |
| `--doctrine-card`、`--doctrine-card-foreground`                     | 抬升卡片表面           |
| `--doctrine-popover`、`--doctrine-popover-foreground`               | 菜单、选择器与 Dialog  |
| `--doctrine-primary`、`--doctrine-primary-foreground`               | 主要操作与链接         |
| `--doctrine-secondary`、`--doctrine-secondary-foreground`           | 次要表面               |
| `--doctrine-muted`、`--doctrine-muted-foreground`                   | 次要表面与次要文字     |
| `--doctrine-accent`、`--doctrine-accent-foreground`                 | Hover 与选中控件       |
| `--doctrine-border`、`--doctrine-separator`                         | 强边框与细分隔线       |
| `--doctrine-input`、`--doctrine-ring`                               | 输入框边界与键盘焦点   |
| `--doctrine-sidebar`、`--doctrine-sidebar-foreground`               | 导航表面与文字         |
| `--doctrine-sidebar-accent`、`--doctrine-sidebar-accent-foreground` | 导航 hover 与选中状态  |
| `--doctrine-code`、`--doctrine-code-foreground`                     | 代码块表面与文字       |
| `--doctrine-radius`                                                 | 共用表面圆角           |
| `--doctrine-font-sans`、`--doctrine-font-display`                   | UI、正文与标题字体栈   |
| `--doctrine-font-mono`                                              | 代码字体栈             |
| `--doctrine-content-width`                                          | 正文最大宽度           |
| `--doctrine-sidebar-width`、`--doctrine-toc-width`                  | 桌面导航与本页目录宽度 |
| `--doctrine-header-height`                                          | 吸顶 header 高度       |

亮色值写在 `:root`，暗色覆盖写在 `[data-theme='dark']`。

## 使用稳定布局 slot

请定位 `data-slot`，不要依赖生成的 utility class：

```css
[data-slot='header'] {
  box-shadow: 0 1px 0 color-mix(in oklab, var(--doctrine-ring) 25%, transparent);
}

[data-slot='brand'] {
  color: var(--doctrine-accent);
}

[data-slot='content'] {
  letter-spacing: 0.005em;
}
```

网站外壳提供 `header`、`header-inner`、`brand`、`navigation`、`sidebar`、`main`、`content`、
`page-actions-row`、`page-actions`、`page-actions-copy`、`page-actions-menu-trigger`、
`page-actions-menu`、`page-actions-markdown`、`page-actions-source`、`page-navigation` 和 `footer`。
内置组件提供 `badge`、`callout`、`card`、`card-grid`、`step`、`steps`、`tabs`、
`code-block`、`code-block-header`、`code-block-filename`、`code-block-language`、
`code-block-copy`、`file-tree`、`file-tree-list`、`file-tree-folder`、`file-tree-file`、
`live-preview`、`live-preview-title`、`live-preview-canvas`、`live-preview-code`、
`live-preview-code-toggle`、`live-preview-source`、`table-scroll`、`tab-list`、`tab` 和 `tab-panel`。

## 使用 Tailwind CSS

Doctrine 自己的界面已经编译，消费者不需要 Tailwind。要在 MDX 或自定义组件中使用 utility，
请在文档项目根 manifest 声明 Tailwind：

<InstallTabs dev packageName="tailwindcss" />

然后在配置的样式表中启用 Tailwind，并声明扫描范围：

```css
@import 'tailwindcss' source(none);
@source './';
```

Doctrine 会检查根 `package.json` 的 dependencies、dev dependencies 与 optional dependencies。
其中声明 `tailwindcss` 时，两个命令都会启用 `@tailwindcss/vite`；否则 `styles` 只是普通 CSS。

## 注册或覆盖组件

用 `components` 指向默认导出组件映射的模块。自定义条目在内置组件之后合并，因此同名条目会
替换默认实现：

```tsx
import type { IDoctrineComponents } from '@amamo/doctrine'
import type { ComponentProps } from 'react'
import { Callout } from '@amamo/doctrine/components'

function BrandedCallout(props: ComponentProps<typeof Callout>) {
  return <Callout className="branded-callout" {...props} />
}

export default { Callout: BrandedCallout } satisfies IDoctrineComponents
```

```ts
export default defineConfig({
  components: './docs/components.tsx',
})
```

在 `styles` 中定义 `.branded-callout`，或启用 Tailwind 后使用 utility。注册 `a` 会替换 Doctrine
能够处理 base 的链接组件，因此替代实现需要自行保留所需的子路径和外部链接行为。

自定义模块会在 Node.js SSR 与浏览器中执行。模块初始化和渲染阶段不能使用浏览器专属全局
变量；请在 effect 或事件处理器中访问它们。