# Справочник за 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/bg/docs/configuration#homepage) и [долен колонтитул](https://onedocs.inline0.dev/bg/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/bg/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/` като данни 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 за AI асистенти.

### 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/bg/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/bg/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/bg/docs/components#more-components).

Вижте [Компоненти](https://onedocs.inline0.dev/bg/docs/components) за примери за употреба.