# 配置

全站设置放在项目根目录的 `onedocs.config.ts` 中。将导出的对象传给会读取它的 `DocsLayout`、`HomePage` 和 `createMetadata`。内容所在位置在 `source.config.ts` 中设置，不在这里（参阅 [入门](https://onedocs.inline0.dev/zh/docs/getting-started)）。

## 基本设置

```ts title="onedocs.config.ts"
import { defineConfig } from "onedocs/config";

export default defineConfig({
  title: "My Project",
  description: "Documentation for My Project",
});
```

这就是最低配置。其他内容都是可选的。

## 完整示例

功能图标是 React 元素，因此使用它们的配置必须是 `.tsx` 文件：

```tsx title="onedocs.config.tsx"
import { defineConfig } from "onedocs/config";
import { Rocket, Zap } from "lucide-react";

export default defineConfig({
  title: "My Project",
  description: "Documentation for My Project",

  // Logo (string or light/dark variants)
  logo: "/logo.svg",
  // logo: { light: "/logo-light.svg", dark: "/logo-dark.svg" },

  // Favicon (string or light/dark variants), used by createMetadata
  icon: "/icon.png",

  // Navigation bar
  nav: {
    links: [
      { label: "Blog", href: "/blog" },
      { label: "Changelog", href: "/changelog" },
    ],
    github: "username/repo",
  },

  // Homepage
  homepage: {
    hero: {
      title: "My Project",
      description: "Documentation that ships with the code",
      cta: { label: "Get Started", href: "/docs" },
    },
    features: [
      {
        title: "Fast",
        description: "Static pages built by Next.js",
        icon: <Zap className="size-5 text-fd-primary" />,
      },
      {
        title: "Simple",
        description: "Write markdown, get docs",
        icon: <Rocket className="size-5 text-fd-primary" />,
      },
    ],
  },

  // Homepage footer
  footer: {
    links: [{ label: "License", href: "https://github.com/username/repo/blob/main/LICENSE" }],
  },
});
```

## 选项

### 标题（必需）

你的网站名称。未设置 `logo` 时，导航栏会显示该名称；`createMetadata` 会将它用作默认页面标题，并用于 `%s | Title` 模板；主页会将它用作主视觉标题，并显示在页脚版权行中。

```ts
title: "My Project"
```

### 描述

简短描述。`createMetadata` 会将其用作元描述；未设置 `homepage.hero.description` 时，主页会在主视觉标题下方显示该描述。

```ts
description: "Documentation for My Project"
```

### 徽标

替换导航栏中的标题。可以使用单个路径，或分别指定浅色和深色变体；图片高 24 px，并将 `title` 作为替代文本。

```ts
// Single logo
logo: "/logo.svg"

// Light/dark mode
logo: {
  light: "/logo-light.svg",
  dark: "/logo-dark.svg"
}
```

### 图标

通过 `createMetadata` 设置站点图标。浅色和深色变体通过 `prefers-color-scheme` 媒体查询提供。

```ts
icon: "/icon.png"

// Light/dark mode
icon: {
  light: "/icon-light.png",
  dark: "/icon-dark.png"
}
```

### 导航栏

供 `DocsLayout` 和 `HomePage` 使用的导航栏配置。

```ts
nav: {
  // Extra links in the navbar
  links: [
    { label: "Blog", href: "/blog" },
    { label: "API", href: "/api" },
  ],

  // GitHub repo as "owner/name" (adds an icon link to https://github.com/owner/name)
  github: "username/repo",
}
```

### 主页

由 `HomePage` 渲染的主视觉和功能网格。

```tsx
homepage: {
  hero: {
    title: "My Project",        // Defaults to config.title
    description: "Description", // Defaults to config.description
    cta: {
      label: "Get Started",     // Default: "Get Started"
      href: "/docs",            // Default: "/docs"
    },
  },
  features: [
    {
      title: "Feature 1",
      description: "Description of feature 1",
      icon: <Rocket className="size-5" />, // Optional React element
    },
  ],
}
```

`icon` 会按原样渲染，因此请传入 `lucide-react` 图标之类的元素。像 `"rocket"` 这样的字符串会作为文本显示。

还有两个主视觉选项可替换默认主视觉的部分内容：

- `hero.left` 会用你自己的内容替换标题、描述、安装区块和按钮。它接受 React 节点，或返回该节点的函数。
- `hero.right` 会填充主视觉右半部分。在 `lg` 断点以下会隐藏。

### 页脚

位于 `HomePage` 页脚中的链接和社交图标，显示在版权行旁边。两者都会在新标签页中打开。

```tsx
// import { GitHubIcon } from "onedocs";
footer: {
  links: [{ label: "Privacy", href: "/privacy" }],
  socials: [
    { label: "GitHub", href: "https://github.com/username/repo", icon: <GitHubIcon /> },
  ],
}
```

每个社交链接都使用 `label` 作为其无障碍名称。

## 尚未生效的选项

`OnedocsConfig` 还会为 `docs`、`theme` 和 `i18n` 提供类型定义，`defineConfig` 也会补全 `docs.dir` 和 `theme.darkMode` 的默认值，但没有任何 Onedocs 代码会读取这些选项（[问题 #2](https://github.com/inline0/onedocs/issues/2)）。设置它们不会产生任何效果：

- `docs.dir`：内容文件夹就是你在 `source.config.ts` 中传给 `defineDocs` 的 `dir`。
- `theme.primaryColor` 和 `theme.darkMode`：颜色来自 CSS 预设导入的 Fumadocs UI 主题，浅色和深色模式来自 Fumadocs UI 的 `RootProvider`。
- `i18n`：Onedocs 不支持多语言。

## TypeScript

`defineConfig` 辅助函数可提供完整的自动补全：

```ts
import { defineConfig, type OnedocsConfig } from "onedocs/config";

const config: OnedocsConfig = {
  title: "My Project",
};

export default defineConfig(config);
```

`defineConfig` 会返回你传入的对象，以及上文所述未使用的 `docs` 和 `theme` 默认值。