# Довідник 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/uk/docs/configuration#homepage) та [нижній колонтитул](https://onedocs.inline0.dev/uk/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" }}
/>
```

**Властивості:**
- `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/` або передайте інший URL із `fontPath`:

```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/uk/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 повідомляє про помилки, як-от `Property 'data' does not exist on type 'unknown'`, коли ви читаєте `page.data` ([#4](https://github.com/inline0/onedocs/issues/4)). Використовуйте `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`)
- Опис
- Значок favicon із `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 для окремих сторінок, віддавайте їх із маршруту. Сторінки не пов’язуються з цим маршрутом автоматично: додайте його до метаданих кожної сторінки самостійно, наприклад, за допомогою `openGraph: { images: "/docs/og/getting-started" }` поруч із полями з `createDocsPageMetadata`.

```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?)` | Завантажує шрифт із `public/` для зображень OG, за замовчуванням `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

Створює файли LLMs.txt для помічників ШІ.

### generateLLMsText

Створює стислий вміст LLMs.txt. Приймає джерело, обгорнуте в `createLLMsSource` і `{ title, description? }`, і повертає проміс.

```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 з повним вмістом сторінки. Приймає лише обгорнуте джерело й повертає проміс.

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

Тіло сторінок додається, лише коли ввімкнено `includeProcessedMarkdown` у Fumadocs MDX; дивіться [SEO і пошук](https://onedocs.inline0.dev/uk/docs/seo-search#full-content-version).

### createLLMsSource

Обгортає джерело Fumadocs (результат `loader()` або `createSource()`) у формат, який читають дві функції вище: URL кожної сторінки, її заголовок, опис і завантажувачі тексту.

## SEO

### generateSitemap

Створює карту сайту для вашої документації. Приймає один об’єкт: `baseUrl`, список `pages` (зазвичай отриманий із `meta.json`) і необов’язковий `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 ?? [],
  });
}
```

Дивіться розділ [SEO і пошук](https://onedocs.inline0.dev/uk/docs/seo-search#sitemap), щоб дізнатися, як записи стають URL.

### 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
- `--font-sans`, задане змінною `--font-inter`, яку визначає `FontHead`
- Функції OpenType Inter для основного тексту й заголовків
- Стилі макета на всю висоту та налаштування макета 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/uk/docs/components#more-components).

Дивіться розділ [Компоненти](https://onedocs.inline0.dev/uk/docs/components), щоб ознайомитися з прикладами використання.