본문으로 건너뛰기

구성

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 기본값을 더해 반환합니다.