Перейти к содержимому

Конфигурация

Просмотреть как 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" }],
  },
});

Параметры

title (обязательно)

Название сайта. Оно отображается в панели навигации, если не задан 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"
}

значок

Favicon задается через 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: папка с контентом — это dir, которую вы передаёте в defineDocs в source.config.ts.
  • theme.primaryColor и theme.darkMode: цвета берутся из темы Fumadocs UI, которую импортирует пресет CSS, а светлая и тёмная темы — из RootProvider Fumadocs UI.
  • 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, описанные выше.