# API 참조

`onedocs` 패키지에서 내보내는 모든 항목입니다.

## 진입점

| 가져오기 | 설명 |
|--------|-------------|
| `onedocs` | 기본 진입점 - 레이아웃, 컴포넌트, `mdxComponents`, `defineConfig`, 소스 헬퍼 |
| `onedocs/components` | Fumadocs UI 컴포넌트와 `InstallBlock`, `CodeBlock`, `Button`, `Logo` |
| `onedocs/config` | 구성 헬퍼 |
| `onedocs/source` | 콘텐츠 소스 유틸리티 |
| `onedocs/metadata` | 메타데이터 생성 |
| `onedocs/og` | OpenGraph 이미지 생성 |
| `onedocs/llms` | LLMs.txt 생성 |
| `onedocs/seo` | 사이트맵 및 robots.txt |
| `onedocs/css/preset.css` | Tailwind CSS 프리셋 |

## 레이아웃

### DocsLayout

문서 페이지의 기본 레이아웃 래퍼입니다. 사이드바 탐색, 검색, 테마 전환 기능을 제공합니다.

```tsx
import { DocsLayout } from "onedocs";

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

**속성:**
- `config` - 사용자의 `OnedocsConfig` 객체
- `pageTree` - 소스의 페이지 트리(예: e.g, `source.pageTree`)
- `children` - 페이지 콘텐츠

### DocsPage

개별 문서 페이지를 감싸는 래퍼입니다. Fumadocs UI `DocsPage`를 감싸고 콘텐츠를 `DocsBody`에 넣습니다.

```tsx
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>
  );
}
```

**속성:**
- `toc` - 페이지 데이터의 목차
- `children` - MDX 콘텐츠
- Fumadocs UI `DocsPage`의 기타 속성(예: `full`)

### DocsBody

문서 콘텐츠용 내부 본문 래퍼입니다. `DocsPage`에서 내부적으로 사용됩니다.

```tsx
import { DocsBody } from "onedocs";

<DocsBody>
  <MDX components={mdxComponents} />
</DocsBody>
```

### HomePage

히어로 섹션, 주요 기능, 푸터가 포함된 전체 랜딩 페이지 컴포넌트입니다.

```tsx
import { HomePage, CTASection } from "onedocs";

export default function Home() {
  return (
    <HomePage config={config} packageName="my-package">
      <CTASection
        title="Ready to get started?"
        cta={{ label: "Read the Docs", href: "/docs" }}
      />
    </HomePage>
  );
}
```

**속성:**
- `config` - 사용자의 `OnedocsConfig` 객체
- `packageName` - 설치 블록의 패키지 이름(선택 사항)
- `children` - 기능과 푸터 사이에 표시할 콘텐츠(선택 사항)

구성이 제어하는 항목은 [홈페이지](https://onedocs.inline0.dev/ko/docs/configuration#homepage)와 [푸터](https://onedocs.inline0.dev/ko/docs/configuration#footer)를 참조하세요.

### HomeLayout

홈페이지의 기본 레이아웃입니다(내부적으로 `HomePage`에서 사용).

```tsx
import { HomeLayout } from "onedocs";

<HomeLayout config={config}>
  {/* Custom homepage content */}
</HomeLayout>
```

### createBaseOptions

구성에서 Fumadocs UI 레이아웃 옵션(내비게이션 바 제목 또는 로고, `nav.links` 및 GitHub 링크)을 만듭니다. `DocsLayout`와 `HomeLayout`에서 사용하며, Fumadocs UI 레이아웃을 직접 렌더링할 때는 직접 호출하세요.

```tsx
import { DocsLayout } from "fumadocs-ui/layouts/docs";
import { createBaseOptions } from "onedocs";

<DocsLayout {...createBaseOptions(config)} tree={source.pageTree}>
  {children}
</DocsLayout>
```

## 컴포넌트

### InstallBlock

npm, yarn, pnpm, bun의 설치 명령을 표시하는 패키지 관리자 탭입니다(`npm i`, `yarn add`, `pnpm add`, `bun add`). 비동기 서버 컴포넌트입니다.

```tsx
import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />
```

**속성:**
- `packageName` - 설치할 npm 패키지 이름
- `title` - 탭 위에 표시할 제목(선택 사항)
- `description` - 탭 위에 표시할 텍스트(선택 사항)
- `children` - 탭 아래에 표시할 콘텐츠(선택 사항)

### Button

기본 버튼 스타일을 적용한 둥근 링크입니다. 스타일은 하나뿐입니다.

```tsx
import { Button } from "onedocs";

<Button href="/docs">Get Started</Button>
```

**속성:**
- `href` - 링크 대상
- `children` - 버튼 텍스트
- `className` - 추가 클래스(선택 사항)

### Logo

밝은 이미지와 어두운 이미지를 렌더링하고 현재 테마에 맞는 이미지를 표시합니다. `DocsLayout`와 `HomePage`에서 밝은 버전과 어두운 버전이 있는 `logo`에 사용합니다.

```tsx
import { Logo } from "onedocs";

<Logo light="/logo-light.svg" dark="/logo-dark.svg" alt="My Project" className="h-6" />
```

**속성:**
- `light` - 라이트 모드 이미지 경로
- `dark` - 다크 모드 이미지 경로
- `alt` - 대체 텍스트(기본값: `"Logo"`)
- `className` - 두 이미지에 적용할 클래스(선택 사항)

### CTASection

홈페이지의 행동 유도 섹션입니다.

```tsx
import { CTASection } from "onedocs";

<CTASection
  title="Ready to get started?"
  description="Optional description text"
  cta={{ label: "Get Started", href: "/docs" }}
/>
```

**Props:**
- `title` - 섹션 제목
- `description` - 제목 아래 텍스트(선택 사항)
- `cta` - `label` 및 `href`가 포함된 버튼 설정
- `children` - 버튼 아래 콘텐츠(선택 사항)

### FontHead

Inter Variable 글꼴을 미리 로드하고 `@font-face`을 선언한 뒤 페이지 글꼴로 설정합니다. 루트 레이아웃의 `<head>`에 추가하세요.

```tsx
import { FontHead } from "onedocs";

<html>
  <head>
    <FontHead />
  </head>
  <body>{children}</body>
</html>
```

Onedocs은 글꼴 파일을 포함하지 않습니다. 기본적으로 `FontHead`은 `/fonts/InterVariable.woff2`을 로드하므로 파일을 `public/fonts/`에 넣거나 `fontPath`와 함께 다른 URL를 전달하세요:

```tsx
<FontHead fontPath="/assets/Inter.woff2" />
```

### GitHubIcon

GitHub 아이콘 컴포넌트(내부적으로 탐색에 사용됨).

```tsx
import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />
```

### CodeBlock

Shiki부터 Fumadocs까지를 사용해 서버에서 구문 강조를 적용한 코드 블록입니다. 비동기 서버 컴포넌트입니다.

```tsx
import { CodeBlock } from "onedocs";

<CodeBlock lang="tsx" code="const x = 1;" />
```

## 구성

### defineConfig

타입 안전 구성 헬퍼.

```tsx
import { defineConfig } from "onedocs/config";

export default defineConfig({
  title: "My Docs",
  // ... other options
});
```

### OnedocsConfig

구성용 TypeScript 타입.

```tsx
import type { OnedocsConfig } from "onedocs/config";

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

모든 옵션은 [구성](https://onedocs.inline0.dev/ko/docs/configuration)을 참조하세요.

## 소스 유틸리티

### loader

콘텐츠 소스를 만들기 위한 `fumadocs-core/source` 로더의 재내보내기입니다.

```tsx
import { loader } from "onedocs/source";

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

### createSource

콘텐츠 소스를 만드는 헬퍼입니다(로더를 감싼 래퍼). 기본 URL은 `/docs`입니다.

```tsx
import { createSource } from "onedocs/source";
import { docs } from "../../.source/server";

export const source = createSource(docs);
// export const source = createSource(docs, { baseUrl: "/guide" });
```

0.1.27에서 `createSource`은 타입이 지정되지 않은 소스를 반환하므로, TypeScript는 `page.data`([#4](https://github.com/inline0/onedocs/issues/4))을 읽을 때 `Property 'data' does not exist on type 'unknown'`와 같은 오류를 보고합니다. 이 문제가 해결될 때까지 위에 나온 대로 `loader`을 사용하세요.

## 메타데이터

### createMetadata

루트 레이아웃의 Next.js 메타데이터를 생성합니다.

```tsx
import { createMetadata } from "onedocs/metadata";

export const metadata = createMetadata(config, {
  baseUrl: "https://example.com",
});
```

**옵션:**
- `baseUrl` - 사이트의 기본 URL(선택 사항)
- `additional` - 추가 `Metadata` 필드(마지막에 병합, 선택 사항)

**반환값:** Next.js `Metadata` 객체에 다음이 포함됩니다:
- 제목(`config.title`) 및 제목 템플릿(`%s | Site Name`)
- 설명
- 설정된 경우 `config.icon`의 파비콘
- `baseUrl`이 설정된 경우: `metadataBase`, OpenGraph 메타데이터 및 Twitter `summary_large_image` 카드

### createDocsPageMetadata

문서 페이지의 제목 및 설명 메타데이터를 생성합니다. `title`과 선택 사항인 `description`이 포함된 객체 하나를 받습니다.

```tsx
import { createDocsPageMetadata } from "onedocs/metadata";
import { notFound } from "next/navigation";

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

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

페이지별 Open Graph 이미지가 필요하면 [동적 OG 이미지](#dynamic-og-images)를 참조하세요.

## OpenGraph 이미지

### createRootOGImage

홈페이지용 OG 이미지를 만듭니다. 검은 배경 중앙에 로고가 배치됩니다.

```tsx
// src/app/opengraph-image.tsx
import {
  createRootOGImage,
  loadPublicFile,
  ogImageSize,
  ogImageContentType,
  type OGImageLogo,
} from "onedocs/og";

export const size = ogImageSize;
export const contentType = ogImageContentType;

export default async function Image() {
  const logo = await loadPublicFile("logo-dark.svg");
  return createRootOGImage(logo as OGImageLogo);
}
```

### createDocsOGImage

문서 페이지용 OG 이미지를 만듭니다. 왼쪽 위에 로고가, 검은 배경에 흰색 제목이 표시됩니다. 글꼴 인수는 선택 사항이며, 지정하지 않으면 제목에 시스템 글꼴이 사용됩니다.

```tsx
// src/app/docs/opengraph-image.tsx
import {
  createDocsOGImage,
  loadPublicFile,
  loadInterFont,
  ogImageSize,
  ogImageContentType,
  type OGImageLogo,
} from "onedocs/og";

export const size = ogImageSize;
export const contentType = ogImageContentType;

export default async function Image() {
  const [logo, font] = await Promise.all([
    loadPublicFile("logo-dark.svg"),
    loadInterFont(),
  ]);
  return createDocsOGImage("Documentation", logo as OGImageLogo, font);
}
```

### 동적 OG 이미지

페이지별 OG 이미지를 사용하려면 라우트에서 이미지를 제공합니다. 페이지가 이 라우트를 자동으로 가리키지는 않으므로, 예를 들어 `createDocsPageMetadata`의 필드 옆에 `openGraph: { images: "/docs/og/getting-started" }`을 추가해 각 페이지의 메타데이터에 직접 지정하세요.

```tsx
// src/app/docs/og/[...slug]/route.tsx
import {
  createDocsOGImage,
  loadPublicFile,
  loadInterFont,
  type OGImageLogo,
} from "onedocs/og";
import { source } from "@/lib/source";

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ slug: string[] }> }
) {
  const { slug } = await params;
  const page = source.getPage(slug);
  const title = page?.data.title ?? "Documentation";

  const [logo, font] = await Promise.all([
    loadPublicFile("logo-dark.svg"),
    loadInterFont(),
  ]);

  return createDocsOGImage(title, logo as OGImageLogo, font);
}
```

### 헬퍼 함수

| 함수 | 설명 |
|----------|-------------|
| `loadPublicFile(path)` | `public/`의 파일을 데이터 URL 및 버퍼로 로드합니다. SVG의 경우 `width` 및 `height` 속성도 읽습니다. |
| `loadInterFont(path?)` | OG 이미지용 글꼴을 `public/`에서 로드합니다. 기본값은 `fonts/Inter-Medium.ttf`입니다. |
| `ogImageSize` | 표준 OG 이미지 크기 `{ width: 1200, height: 630 }` |
| `ogImageContentType` | MIME 타입 `"image/png"` |

**필수 파일:**
- `public/logo-dark.svg` - OG 이미지용 로고입니다. OG 헬퍼는 `width` 및 `height` 속성을 기준으로 크기를 정하므로 `<svg>` 태그에 일반 숫자로 두 속성을 모두 지정해야 합니다.
- `public/fonts/Inter-Medium.ttf` - 제목용 글꼴입니다. Onedocs에는 포함되지 않습니다.

## LLMs.txt

AI 어시스턴트용 LLMs.txt 파일을 생성합니다.

### generateLLMsText

간결한 LLMs.txt 콘텐츠를 생성합니다. `createLLMsSource` 및 `{ title, description? }`로 감싼 소스를 받아 Promise를 반환합니다.

```tsx
// src/app/llms.txt/route.ts
import { createLLMsSource, generateLLMsText } from "onedocs/llms";
import { source } from "@/lib/source";

export async function GET() {
  const content = await generateLLMsText(createLLMsSource(source), {
    title: "My Project",
    description: "Project description",
  });

  return new Response(content, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}
```

페이지 URL은 도메인 없이 `/docs/getting-started`처럼 소스에 적힌 형태로 작성됩니다.

### generateLLMsFullText

전체 페이지 콘텐츠를 포함한 완전한 LLMs.txt을 생성합니다. 래핑된 소스만 받아 Promise를 반환합니다.

```tsx
// src/app/llms-full.txt/route.ts
import { createLLMsSource, generateLLMsFullText } from "onedocs/llms";
import { source } from "@/lib/source";

export async function GET() {
  const content = await generateLLMsFullText(createLLMsSource(source));

  return new Response(content, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}
```

페이지 본문은 Fumadocs MDX의 `includeProcessedMarkdown`이 켜져 있을 때만 포함됩니다. [SEO 및 검색](https://onedocs.inline0.dev/ko/docs/seo-search#full-content-version)을 참조하세요.

### createLLMsSource

Fumadocs 소스(`loader()` 또는 `createSource()` 결과)를 위 두 함수가 읽는 형태로 감쌉니다. 각 페이지에는 URL, 제목, 설명 및 텍스트 로더가 포함됩니다.

## SEO

### generateSitemap

문서 사이트의 사이트맵을 생성합니다. 객체 하나를 받습니다. `pages` 목록(보통 `meta.json`에서 가져옴)인 `baseUrl`과 선택 사항인 `docsPath`(기본값 `/docs`)이 포함됩니다.

```tsx
// src/app/sitemap.ts
import { generateSitemap } from "onedocs/seo";
import meta from "../../content/docs/meta.json";

export default function sitemap() {
  return generateSitemap({
    baseUrl: "https://example.com",
    pages: meta.pages ?? [],
  });
}
```

항목이 URL로 변환되는 방식은 [SEO 및 검색](https://onedocs.inline0.dev/ko/docs/seo-search#sitemap)을 참조하세요.

### generateRobots

robots.txt 콘텐츠를 생성합니다. 모든 항목과 `Host` 및 `Sitemap` 줄을 허용합니다. `sitemapPath`의 기본값은 `/sitemap.xml`입니다.

```tsx
// src/app/robots.ts
import { generateRobots } from "onedocs/seo";

export default function robots() {
  return generateRobots({
    baseUrl: "https://example.com",
  });
}
```

## CSS 프리셋

CSS 프리셋을 `globals.css`에서 가져오세요:

```css
@import "onedocs/css/preset.css";

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

`@source` 경로는 `src/app/globals.css`을 기준으로 합니다.

프리셋에는 다음이 포함됩니다:
- Tailwind CSS v4(`tailwindcss` 및 `@tailwindcss/postcss`은 직접 설치)
- Fumadocs 중립 테마
- Fumadocs 프리셋 스타일
- `FontHead`에서 정의하는 `--font-inter` 변수로 설정된 `--font-sans`
- 본문 텍스트 및 제목용 Inter OpenType 기능
- 전체 높이 레이아웃 스타일 및 Onedocs 레이아웃 조정

## MDX 컴포넌트

`mdxComponents` 내보내기는 Fumadocs UI 기본 MDX 컴포넌트를 펼치고 아래 컴포넌트를 추가합니다:

```tsx
import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />
```

**포함된 컴포넌트:**
- Fumadocs UI 기본 컴포넌트: `pre`(코드 블록), `a`, `img`, `h1`에서 `h6`(앵커가 있는 제목), `table`, `CodeBlockTab`, `CodeBlockTabs`, `CodeBlockTabsList`, `CodeBlockTabsTrigger`, `CalloutContainer`, `CalloutTitle`, `CalloutDescription`
- `Callout` - 정보/경고/오류 안내 상자
- `Card`, `Cards` - 카드 레이아웃
- `Tab`, `Tabs` - 탭 콘텐츠
- `Step`, `Steps` - 번호가 매겨진 단계
- `Accordion`, `Accordions` - 접을 수 있는 섹션
- `File`, `Folder`, `Files` - 파일 트리
- `ImageZoom` - 확대 가능한 이미지
- `TypeTable` - 타입 문서 표

`InstallBlock` 및 `CodeBlock`은 포함되지 않습니다. [컴포넌트](https://onedocs.inline0.dev/ko/docs/components#more-components)에 나온 대로 직접 추가하세요.

사용 예시는 [컴포넌트](https://onedocs.inline0.dev/ko/docs/components)를 참조하세요.