配置

以 Markdown 格式查看在 GitHub 上编辑文档位置 7b38e05

全站设置放在项目根目录的 onedocs.config.ts 中。将导出的对象传给会读取它的 DocsLayout、HomePage 和 createMetadata。内容所在位置在 source.config.ts 中设置，不在这里（参阅入门）。

基本设置

TypeScript

import { defineConfig } from "onedocs/config";

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

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

完整示例

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

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 模板；主页会将它用作主视觉标题，并显示在页脚版权行中。

TypeScript

title: "My Project"

描述

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

TypeScript

description: "Documentation for My Project"

徽标

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

TypeScript

// Single logo
logo: "/logo.svg"

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

图标

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

TypeScript

icon: "/icon.png"

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

导航栏

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

TypeScript

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）。设置它们不会产生任何效果：

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

TypeScript

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

TypeScript

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

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

export default defineConfig(config);

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