跳到正文
@amamo/doctrine
本页目录

自定义

Doctrine 有两个项目级扩展点：用样式表调整外观，用 React 组件映射扩展 MDX。内置组件参考见 MDX 组件。

添加样式表

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

TypeScript
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-foregroundHover 与选中控件
--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-displayUI、正文与标题字体栈
--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：

Shell
pnpm add -D 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
TypeScript
export default defineConfig({
  components: './docs/components.tsx',
})

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

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

copyright © 2026 白熱。