시작하기

Markdown으로 보기 GitHub에서 수정 문서 위치 7b38e05

이 가이드에서는 빈 폴더에서 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).

설치

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

셸

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).

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

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

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만 필수이며 나머지는 구성을 참조하세요.

TypeScript

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에 알려줍니다. 콘텐츠 폴더는 여기서만 설정합니다:

TypeScript

import { defineDocs } from "fumadocs-mdx/config";

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

next.config.mjs

MDX 처리를 활성화합니다:

JavaScript

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을 실행합니다:

JavaScript

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

tsconfig.json

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

JSON

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

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

소스 설정

src/lib/source.ts

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

TypeScript

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

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 릴리스에서 InterVariable.woff2을 다운로드해 public/fonts/에 넣으세요. 파일이 없으면 시스템 산세리프 글꼴로 표시됩니다.

이 메타데이터를 구성에서 대신 생성하려면 API 레퍼런스의 createMetadata을 참조하세요.

src/app/globals.css

CSS 프리셋을 가져오세요:

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

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

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

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: 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

{
  "pages": ["index"]
}

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

실행

개발 서버를 시작하세요:

셸

npm run dev

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

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

셸

npm run build

다음으로 SEO 및 검색에서 검색, 사이트맵 및 llms.txt을 추가하세요.