# Справочник 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/ru/docs/configuration#homepage) и [нижний колонтитул](https://onedocs.inline0.dev/ru/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/ru/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`)
- Описание
- Значок сайта из `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/` как строку data 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? }`, и возвращает 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" },
  });
}
```

Текст страниц включается, только если параметр `includeProcessedMarkdown` у Fumadocs MDX включен; см. раздел [SEO и поиск](https://onedocs.inline0.dev/ru/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 ?? [],
  });
}
```

О том, как записи преобразуются в URL, см. раздел [SEO и поиск](https://onedocs.inline0.dev/ru/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
- `--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/ru/docs/components#more-components).

Примеры использования см. в разделе [Компоненты](https://onedocs.inline0.dev/ru/docs/components).