# 시작하기

이 가이드에서는 빈 폴더에서 Onedocs을 사용해 문서 사이트를 설정합니다. 이미 Next.js 프로젝트가 있다면 기존 파일은 건너뛰고 나머지를 비교하세요.

## 사전 요구 사항

- Node.js 20.9 이상(Next.js 16에 필요)
- App Router가 포함된 Next.js 16, React 19.2 이상
- Tailwind CSS v4(Onedocs CSS 프리셋은 `tailwindcss`을 가져옵니다)

Fumadocs UI 16은 Next.js 16 및 React 19.2만 지원합니다. 따라서 `onedocs` 패키지 메타데이터에 여전히 기재되어 있어도 이전 버전의 Next.js 또는 React는 작동하지 않습니다([#5](https://github.com/inline0/onedocs/issues/5)).

## 설치

Onedocs에는 Next.js 또는 Fumadocs가 포함되어 있지 않습니다. 피어 종속성이므로 함께 설치해야 합니다:

```bash
npm install onedocs fumadocs-core fumadocs-mdx fumadocs-ui lucide-react@0.562 next react react-dom
npm install -D tailwindcss @tailwindcss/postcss typescript @types/react @types/react-dom @types/node
```

`lucide-react@0.562` 고정 버전을 유지하세요. `onedocs` 0.1.27는 `^0.562.0`를 `lucide-react` 피어 종속성으로 선언합니다. 버전을 고정하지 않으면 npm가 lucide-react 1.x을 설치하고 `ERESOLVE` 오류로 중단됩니다([#1](https://github.com/inline0/onedocs/issues/1)).

같은 패키지를 pnpm, yarn 또는 bun에서도 사용할 수 있습니다.

Next.js 스크립트를 `package.json`에 추가하세요:

```json title="package.json"
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}
```

## 프로젝트 구조

완성 후의 구조는 다음과 같습니다:

```
your-project/
├── content/
│   └── docs/
│       ├── index.mdx
│       └── meta.json
├── public/
│   └── fonts/
│       └── InterVariable.woff2
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   ├── globals.css
│   │   └── docs/
│   │       ├── layout.tsx
│   │       └── [[...slug]]/
│   │           └── page.tsx
│   └── lib/
│       └── source.ts
├── onedocs.config.ts
├── source.config.ts
├── next.config.mjs
├── postcss.config.mjs
├── tsconfig.json
└── package.json
```

각 파일을 만들어 보겠습니다.

## 구성 파일

### onedocs.config.ts

기본 구성 파일입니다. `title`만 필수이며 나머지는 [구성](https://onedocs.inline0.dev/ko/docs/configuration)을 참조하세요.

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

export default defineConfig({
  title: "My Docs",
  description: "Documentation for my project",
  nav: {
    github: "username/repo",
  },
});
```

### source.config.ts

콘텐츠가 있는 위치를 Fumadocs MDX에 알려줍니다. 콘텐츠 폴더는 여기서만 설정합니다:

```ts title="source.config.ts"
import { defineDocs } from "fumadocs-mdx/config";

export const docs = defineDocs({
  dir: "content/docs",
});
```

### next.config.mjs

MDX 처리를 활성화합니다:

```js title="next.config.mjs"
import { createMDX } from "fumadocs-mdx/next";

const withMDX = createMDX();

/** @type {import('next').NextConfig} */
const config = {};

export default withMDX(config);
```

Fumadocs MDX은 Next.js 시작될 때 `source.config.ts`에서 `.source/` 폴더를 생성합니다. `.source`를 `.gitignore`에 추가하세요.

### postcss.config.mjs

Onedocs CSS 프리셋의 기반이 되는 Tailwind CSS v4을 실행합니다:

```js title="postcss.config.mjs"
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};
```

### tsconfig.json

아래 예시에서는 `@/`에서 가져오므로 이를 `src/`에 매핑하세요:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

Next.js은 `next dev` 또는 `next build`를 처음 실행할 때 이 파일에 필요한 나머지 컴파일러 옵션을 추가합니다.

## 소스 설정

### src/lib/source.ts

문서 콘텐츠를 불러옵니다:

```ts title="src/lib/source.ts"
import { loader } from "fumadocs-core/source";
import { docs } from "../../.source/server";

export const source = loader({
  baseUrl: "/docs",
  source: docs.toFumadocsSource(),
});
```

## 앱 파일

### src/app/layout.tsx

루트 레이아웃:

```tsx title="src/app/layout.tsx"
import type { Metadata } from "next";
import { RootProvider } from "fumadocs-ui/provider/next";
import { FontHead } from "onedocs";
import "./globals.css";

export const metadata: Metadata = {
  title: "My Docs",
  description: "Documentation for my project",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <FontHead />
      </head>
      <body className="antialiased">
        <RootProvider>{children}</RootProvider>
      </body>
    </html>
  );
}
```

Fumadocs UI의 `RootProvider`는 검색 대화상자와 밝은 테마 및 어두운 테마를 제공합니다. `FontHead`는 `/fonts/InterVariable.woff2`에서 Inter Variable 글꼴을 미리 로드하고 페이지 글꼴로 설정합니다. Onedocs에는 글꼴 파일이 포함되어 있지 않습니다. [Inter 릴리스](https://github.com/rsms/inter/releases)에서 `InterVariable.woff2`을 다운로드해 `public/fonts/`에 넣으세요. 파일이 없으면 시스템 산세리프 글꼴로 표시됩니다.

이 메타데이터를 구성에서 대신 생성하려면 [API 레퍼런스](https://onedocs.inline0.dev/ko/docs/api-reference#createmetadata)의 `createMetadata`을 참조하세요.

### src/app/globals.css

CSS 프리셋을 가져오세요:

```css title="src/app/globals.css"
@import "onedocs/css/preset.css";

@source "./**/*.tsx";
@source "../../content/**/*.mdx";
```

프리셋은 Tailwind CSS, Fumadocs UI 스타일 및 Onedocs 레이아웃 스타일을 불러옵니다. `@source` 경로는 `globals.css`을 기준으로 하므로 이 두 줄은 각각 `src/app/`과 프로젝트 루트의 `content/` 폴더를 가리킵니다.

### src/app/page.tsx

홈페이지입니다. `HomePage`는 구성에 따라 히어로, 기능 및 푸터를 렌더링합니다:

```tsx title="src/app/page.tsx"
import { HomePage } from "onedocs";
import config from "../../onedocs.config";

export default function Home() {
  return <HomePage config={config} packageName="my-package" />;
}
```

`packageName`는 npm, yarn, pnpm 및 bun의 설치 명령을 히어로에 추가합니다. 프로젝트가 패키지가 아니라면 생략하세요.

### src/app/docs/layout.tsx

사이드바가 있는 문서 레이아웃:

```tsx title="src/app/docs/layout.tsx"
import { DocsLayout } from "onedocs";
import type { ReactNode } from "react";
import { source } from "@/lib/source";
import config from "../../../onedocs.config";

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <DocsLayout config={config} pageTree={source.pageTree}>
      {children}
    </DocsLayout>
  );
}
```

### src/app/docs/[[...slug]]/page.tsx

개별 문서 페이지:

```tsx title="src/app/docs/[[...slug]]/page.tsx"
import { source } from "@/lib/source";
import { DocsPage, mdxComponents } from "onedocs";
import { notFound } from "next/navigation";

export default async function Page(props: {
  params: Promise<{ slug?: string[] }>;
}) {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();

  const MDX = page.data.body;

  return (
    <DocsPage toc={page.data.toc}>
      <MDX components={mdxComponents} />
    </DocsPage>
  );
}

export async function generateStaticParams() {
  return source.generateParams();
}

export async function generateMetadata(props: {
  params: Promise<{ slug?: string[] }>;
}) {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();

  return {
    title: page.data.title,
    description: page.data.description,
  };
}
```

## 콘텐츠

### content/docs/index.mdx

각 페이지의 프런트매터에는 `title`가 필요합니다. `description`은 선택 사항입니다:

```mdx title="content/docs/index.mdx"
---
title: Introduction
description: What this project does.
---

Welcome to the docs. Components such as `<Callout>` work without imports; see [Components](/docs/components).
```

### content/docs/meta.json

사이드바 순서를 설정합니다:

```json title="content/docs/meta.json"
{
  "pages": ["index"]
}
```

다른 `.mdx` 파일을 만들고 `pages`에 이름을 등록해 페이지를 추가하세요.

## 실행

개발 서버를 시작하세요:

```bash
npm run dev
```

홈페이지는 `http://localhost:3000`에, 문서 페이지는 `http://localhost:3000/docs`에 있습니다.

프로덕션용으로 빌드하세요:

```bash
npm run build
```

다음으로 [SEO 및 검색](https://onedocs.inline0.dev/ko/docs/seo-search)에서 검색, 사이트맵 및 llms.txt을 추가하세요.