# Referencia API

Kompletná referencia všetkých exportov z balíka `onedocs`.

## Vstupné body

| Import | Opis |
|--------|-------------|
| `onedocs` | Hlavný vstup – rozloženia, komponenty, `mdxComponents`, `defineConfig`, pomocné funkcie zdrojov |
| `onedocs/components` | Komponenty Fumadocs UI a tiež `InstallBlock`, `CodeBlock`, `Button` a `Logo` |
| `onedocs/config` | Pomocné funkcie konfigurácie |
| `onedocs/source` | Pomocné nástroje pre zdroje obsahu |
| `onedocs/metadata` | Generovanie metadát |
| `onedocs/og` | Generovanie obrázkov OpenGraph |
| `onedocs/llms` | Generovanie LLMs.txt |
| `onedocs/seo` | Mapa webu a robots.txt |
| `onedocs/css/preset.css` | Predvoľba Tailwind CSS |

## Rozloženia

### DocsLayout

Hlavný obal rozloženia stránok dokumentácie. Poskytuje navigáciu v bočnom paneli, vyhľadávanie a prepínanie témy.

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

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

**Vlastnosti:**
- `config` – váš objekt `OnedocsConfig`
- `pageTree` – strom stránok z vášho zdroja (napr. e.g, `source.pageTree`)
- `children` – obsah stránky

### DocsPage

Obal pre jednotlivé stránky dokumentácie. Obalí Fumadocs UI `DocsPage` a vloží obsah do `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>
  );
}
```

**Vlastnosti:**
- `toc` – obsah z údajov stránky
- `children` – obsah MDX
- Akákoľvek ďalšia vlastnosť Fumadocs UI `DocsPage`, napríklad `full`

### DocsBody

Vnútorný obal obsahu dokumentácie. Používa ho interne `DocsPage`.

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

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

### HomePage

Kompletný komponent úvodnej stránky s hlavnou sekciou, funkciami a pätou.

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

**Vlastnosti:**
- `config` – váš objekt `OnedocsConfig`
- `packageName` – názov balíka pre blok inštalácie (voliteľné)
- `children` – obsah medzi funkciami a pätou (voliteľné)

Pozrite si [domovskú stránku](https://onedocs.inline0.dev/sk/docs/configuration#homepage) a [pätu](https://onedocs.inline0.dev/sk/docs/configuration#footer), kde nájdete informácie o tom, čo konfigurácia ovláda.

### HomeLayout

Základné rozloženie domovskej stránky (interne ho používa `HomePage`).

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

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

### createBaseOptions

Vytvára možnosti rozloženia Fumadocs UI (názov alebo logo navigačného panela, `nav.links` a odkaz GitHub) z vašej konfigurácie. Používajú ho `DocsLayout` a `HomeLayout`; zavolajte ho sami, keď vykresľujete rozloženie Fumadocs UI priamo.

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

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

## Komponenty

### InstallBlock

Karty správcu balíkov zobrazujúce príkazy na inštaláciu pre npm, yarn, pnpm a bun (`npm i`, `yarn add`, `pnpm add`, `bun add`). Ide o asynchrónny serverový komponent.

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

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

**Vlastnosti:**
- `packageName` – názov balíka npm na inštaláciu
- `title` – nadpis nad kartami (voliteľné)
- `description` – text nad kartami (voliteľné)
- `children` – obsah pod kartami (voliteľné)

### Button

Zaoblený odkaz so štýlom primárneho tlačidla. Má jeden štýl.

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

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

**Vlastnosti:**
- `href` – cieľ odkazu
- `children` – text tlačidla
- `className` – ďalšie triedy (voliteľné)

### Logo

Vykreslí svetlý aj tmavý obrázok a zobrazí ten, ktorý zodpovedá aktuálnej téme. `DocsLayout` a `HomePage` ho používajú pre `logo` so svetlými a tmavými variantmi.

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

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

**Vlastnosti:**
- `light` – cesta k obrázku pre svetlý režim
- `dark` – cesta k obrázku pre tmavý režim
- `alt` – alternatívny text (predvolené: `"Logo"`)
- `className` – triedy pre oba obrázky (voliteľné)

### CTASection

Sekcia výzvy na akciu pre domovskú stránku.

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

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

**Vlastnosti:**
- `title` – nadpis sekcie
- `description` – text pod nadpisom (voliteľné)
- `cta` – konfigurácia tlačidla s `label` a `href`
- `children` – obsah pod tlačidlom (voliteľné)

### FontHead

Prednačíta variabilné písmo Inter, deklaruje jeho `@font-face` a nastaví ho ako písmo stránky. Pridajte ho do `<head>` koreňového rozloženia.

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

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

Onedocs nedodáva písmo. Predvolene `FontHead` načítava `/fonts/InterVariable.woff2`, preto súbor umiestnite do `public/fonts/` alebo odovzdajte iné URL s `fontPath`:

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

### GitHubIcon

Ikonový komponent GitHub (interne používaný v navigácii).

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

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

### CodeBlock

Blok kódu so zvýraznenou syntaxou, ktorú na serveri zvýrazňuje Shiki prostredníctvom Fumadocs. Ide o asynchrónny serverový komponent.

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

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

## Konfigurácia

### defineConfig

Pomocná funkcia pre typovo bezpečnú konfiguráciu.

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

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

### OnedocsConfig

Typ TypeScript pre konfiguráciu.

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

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

Všetky možnosti nájdete v časti [Konfigurácia](https://onedocs.inline0.dev/sk/docs/configuration).

## Pomocné nástroje zdroja

### loader

Opätovne exportovaný načítavač `fumadocs-core/source` na vytváranie zdrojov obsahu.

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

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

### createSource

Pomocná funkcia na vytvorenie zdroja obsahu (obal okolo načítavača). Základné URL má predvolenú hodnotu `/docs`.

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

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

V 0.1.27 `createSource` vracia netypovaný zdroj, takže TypeScript hlási chyby, napríklad `Property 'data' does not exist on type 'unknown'`, keď čítate `page.data` ([#4](https://github.com/inline0/onedocs/issues/4)). Kým sa to neopraví, použite `loader` podľa príkladu vyššie.

## Metadáta

### createMetadata

Generuje metadáta Next.js pre koreňové rozloženie.

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

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

**Možnosti:**
- `baseUrl` – základná URL vašej stránky (voliteľné)
- `additional` – ďalšie polia `Metadata`, zlúčené ako posledné (voliteľné)

**Vráti:** objekt Next.js `Metadata` s týmito položkami:
- Názov (`config.title`) a šablóna názvu (`%s | Site Name`)
- Opis
- Ikona stránky z `config.icon`, ak je nastavená
- Ak je nastavené `baseUrl`: `metadataBase`, metadáta OpenGraph a karta Twitter `summary_large_image`

### createDocsPageMetadata

Generuje metadáta názvu a opisu pre stránku dokumentácie. Prijíma jeden objekt s `title` a voliteľným `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,
  });
}
```

Obrázok Open Graph pre konkrétnu stránku nájdete v časti [Dynamické obrázky OG](#dynamic-og-images).

## Obrázky OpenGraph

### createRootOGImage

Vytvorí obrázok OG pre domovskú stránku: vaše logo vycentrované na čiernom pozadí.

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

Vytvorí obrázok OG pre stránky dokumentácie: logo vľavo hore a názov bielou farbou na čiernom pozadí. Argument písma je voliteľný; ak ho vynecháte, názov použije systémové písmo.

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

### Dynamické obrázky OG

Ak chcete obrázky OG pre jednotlivé stránky, poskytujte ich cez trasu. Stránky na túto trasu nič automaticky neodkazuje: pridajte ju sami do metadát každej stránky, napríklad pomocou `openGraph: { images: "/docs/og/getting-started" }` vedľa polí z `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);
}
```

### Pomocné funkcie

| Funkcia | Opis |
|----------|-------------|
| `loadPublicFile(path)` | Načíta súbor z `public/` ako dátové URL a vyrovnávaciu pamäť; pri SVG načíta aj atribúty `width` a `height` |
| `loadInterFont(path?)` | Načíta písmo z `public/` pre obrázky OG, predvolene `fonts/Inter-Medium.ttf` |
| `ogImageSize` | Štandardné rozmery obrázka OG `{ width: 1200, height: 630 }` |
| `ogImageContentType` | Typ MIME `"image/png"` |

**Požadované súbory:**
- `public/logo-dark.svg` – logo pre obrázky OG. Pomocné funkcie OG určia jeho veľkosť podľa atribútov `width` a `height`, preto značka `<svg>` musí obsahovať obe hodnoty ako obyčajné čísla.
- `public/fonts/Inter-Medium.ttf` – písmo pre názvy. Onedocs ho nedodáva.

## LLMs.txt

Generuje súbory LLMs.txt pre asistentov umelej inteligencie.

### generateLLMsText

Generuje stručný obsah LLMs.txt. Prijíma zdroj obalený pomocou `createLLMsSource` a `{ title, description? }` a vracia prísľub.

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

Adresy URL stránok sa zapisujú tak, ako pochádzajú zo zdroja, napríklad `/docs/getting-started`, bez domény.

### generateLLMsFullText

Generuje úplný LLMs.txt s kompletným obsahom stránky. Prijíma iba obalený zdroj a vracia prísľub.

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

Texty stránok sa zahrnú iba vtedy, keď je zapnutá možnosť `includeProcessedMarkdown` v Fumadocs MDX; pozrite si [SEO a vyhľadávanie](https://onedocs.inline0.dev/sk/docs/seo-search#full-content-version).

### createLLMsSource

Obalí zdroj Fumadocs (výsledok `loader()` alebo `createSource()`) do tvaru, ktorý čítajú dve funkcie vyššie: URL každej stránky, načítavače názvu, opisu a textu.

## SEO

### generateSitemap

Generuje mapu webu pre vašu dokumentáciu. Prijíma jeden objekt: `baseUrl`, zoznam `pages` (zvyčajne z `meta.json`) a voliteľné `docsPath` (predvolené `/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 ?? [],
  });
}
```

Informácie o tom, ako sa položky menia na adresy URL, nájdete v časti [SEO a vyhľadávanie](https://onedocs.inline0.dev/sk/docs/seo-search#sitemap).

### generateRobots

Generuje obsah robots.txt: povoľuje všetko a pridáva riadky `Host` a `Sitemap`. Predvolená hodnota `sitemapPath` je `/sitemap.xml`.

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

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

## Predvoľba CSS

Importujte predvoľbu CSS do svojho `globals.css`:

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

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

Cesty `@source` sú relatívne vzhľadom na `src/app/globals.css`.

Predvoľba obsahuje:
- Tailwind CSS v4 (nainštalujte si sami `tailwindcss` a `@tailwindcss/postcss`)
- Neutrálnu tému Fumadocs
- Štýly predvoľby Fumadocs
- `--font-sans` nastavené na premennú `--font-inter`, ktorú definuje `FontHead`
- Funkcie písma Inter OpenType pre základný text a nadpisy
- Štýly rozloženia na celú výšku a úpravy rozloženia Onedocs

## Komponenty MDX

Export `mdxComponents` rozširuje predvolené komponenty Fumadocs UI MDX a pridáva nižšie uvedené komponenty:

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

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

**Zahrnuté komponenty:**
- Predvolené komponenty Fumadocs UI: `pre` (bloky kódu), `a`, `img`, `h1` až `h6` (nadpisy s kotvami), `table`, `CodeBlockTab`, `CodeBlockTabs`, `CodeBlockTabsList`, `CodeBlockTabsTrigger`, `CalloutContainer`, `CalloutTitle`, `CalloutDescription`
- `Callout` – informačné, varovné a chybové upozornenia
- `Card`, `Cards` – rozloženia kariet
- `Tab`, `Tabs` – obsah s kartami
- `Step`, `Steps` – očíslované kroky
- `Accordion`, `Accordions` – rozbaľovacie sekcie
- `File`, `Folder`, `Files` – stromové zobrazenia súborov
- `ImageZoom` – obrázky s priblížením
- `TypeTable` – tabuľky typov v dokumentácii

`InstallBlock` a `CodeBlock` nie sú zahrnuté; pridajte ich sami podľa pokynov v časti [Komponenty](https://onedocs.inline0.dev/sk/docs/components#more-components).

Príklady použitia nájdete v časti [Komponenty](https://onedocs.inline0.dev/sk/docs/components).