# API — dokumentacja referencyjna

Kompletna dokumentacja wszystkich eksportów z pakietu `onedocs`.

## Punkty wejścia

| Import | Opis |
|--------|-------------|
| `onedocs` | Główne wejście — układy, komponenty, `mdxComponents`, `defineConfig`, pomocnicze funkcje źródłowe |
| `onedocs/components` | Komponenty Fumadocs UI oraz `InstallBlock`, `CodeBlock`, `Button` i `Logo` |
| `onedocs/config` | Pomocnicze funkcje konfiguracji |
| `onedocs/source` | Narzędzia źródeł treści |
| `onedocs/metadata` | Generowanie metadanych |
| `onedocs/og` | Generowanie obrazów OpenGraph |
| `onedocs/llms` | Generowanie LLMs.txt |
| `onedocs/seo` | Mapa witryny i robots.txt |
| `onedocs/css/preset.css` | Ustawienie Tailwind CSS |

## Układy

### DocsLayout

Główny komponent układu stron dokumentacji. Zapewnia nawigację boczną, wyszukiwanie i przełączanie motywu.

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

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

**Właściwości:**
- `config` — obiekt `OnedocsConfig`
- `pageTree` — drzewo stron ze źródła (np. e.g, `source.pageTree`)
- `children` — treść strony

### DocsPage

Opakowanie dla poszczególnych stron dokumentacji. Opakowuje Fumadocs UI `DocsPage` i umieszcza treść w `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>
  );
}
```

**Właściwości:**
- `toc` — spis treści z danych strony
- `children` — treść MDX
- Każda inna właściwość Fumadocs UI `DocsPage`, na przykład `full`

### DocsBody

Wewnętrzne opakowanie treści dokumentacji. Używane wewnętrznie przez `DocsPage`.

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

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

### HomePage

Kompletny komponent strony docelowej z sekcją główną, funkcjami i stopką.

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

**Właściwości:**
- `config` — obiekt `OnedocsConfig`
- `packageName` — nazwa pakietu w bloku instalacji (opcjonalnie)
- `children` — treść między sekcją funkcji a stopką (opcjonalnie)

Zobacz stronę główną [homepage](https://onedocs.inline0.dev/pl/docs/configuration#homepage) i stopkę [footer](https://onedocs.inline0.dev/pl/docs/configuration#footer), aby dowiedzieć się, na co wpływa konfiguracja.

### HomeLayout

Podstawowy układ strony głównej (używany wewnętrznie przez `HomePage`).

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

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

### createBaseOptions

Tworzy opcje układu Fumadocs UI (tytuł lub logo paska nawigacyjnego, `nav.links` i link GitHub) na podstawie konfiguracji. Korzystają z niego `DocsLayout` i `HomeLayout`; wywołaj go samodzielnie, gdy bezpośrednio renderujesz układ Fumadocs UI.

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

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

## Komponenty

### InstallBlock

Karty menedżerów pakietów z poleceniami instalacji dla npm, yarn, pnpm i bun (`npm i`, `yarn add`, `pnpm add`, `bun add`). To asynchroniczny komponent serwerowy.

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

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

**Właściwości:**
- `packageName` — nazwa pakietu npm do zainstalowania
- `title` — nagłówek nad kartami (opcjonalnie)
- `description` — tekst nad kartami (opcjonalnie)
- `children` — treść pod kartami (opcjonalnie)

### Button

Zaokrąglony link w stylu głównego przycisku. Dostępny w jednym stylu.

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

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

**Właściwości:**
- `href` — docelowy adres linku
- `children` — tekst przycisku
- `className` — dodatkowe klasy (opcjonalnie)

### Logo

Renderuje jasny i ciemny obraz, a następnie wyświetla ten pasujący do bieżącego motywu. `DocsLayout` i `HomePage` używają go dla `logo` z wariantami jasnym i ciemnym.

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

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

**Właściwości:**
- `light` — ścieżka obrazu dla trybu jasnego
- `dark` — ścieżka obrazu dla trybu ciemnego
- `alt` — tekst alternatywny (domyślnie: `"Logo"`)
- `className` — klasy dla obu obrazów (opcjonalnie)

### CTASection

Sekcja wezwania do działania na stronie głównej.

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

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

**Właściwości:**
- `title` — nagłówek sekcji
- `description` — tekst pod nagłówkiem (opcjonalnie)
- `cta` — konfiguracja przycisku z `label` i `href`
- `children` — treść pod przyciskiem (opcjonalnie)

### FontHead

Wstępnie ładuje zmienną czcionkę Inter, deklaruje jej `@font-face` i ustawia ją jako czcionkę strony. Dodaj do `<head>` układu głównego.

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

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

Onedocs nie zawiera czcionki. Domyślnie `FontHead` ładuje `/fonts/InterVariable.woff2`, dlatego umieść plik w `public/fonts/` albo przekaż inny URL za pomocą `fontPath`:

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

### GitHubIcon

Komponent ikony GitHub (używany wewnętrznie w nawigacji).

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

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

### CodeBlock

Blok kodu z podświetlaną składnią, podświetlany po stronie serwera za pomocą Shiki przez Fumadocs. To asynchroniczny komponent serwerowy.

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

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

## Konfiguracja

### defineConfig

Pomocnicza funkcja do konfiguracji z kontrolą typów.

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

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

### OnedocsConfig

Typ TypeScript dla konfiguracji.

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

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

Wszystkie opcje znajdziesz w sekcji [Configuration](https://onedocs.inline0.dev/pl/docs/configuration).

## Narzędzia źródeł

### loader

Ponowny eksport loadera `fumadocs-core/source` do tworzenia źródeł treści.

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

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

### createSource

Funkcja pomocnicza do tworzenia źródła treści (opakowanie wokół loadera). Domyślną wartością bazową URL jest `/docs`.

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

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

W 0.1.27 `createSource` zwraca źródło bez określonego typu, więc TypeScript zgłasza błędy, takie jak `Property 'data' does not exist on type 'unknown'`, gdy odczytujesz `page.data` ([#4](https://github.com/inline0/onedocs/issues/4)). Używaj `loader`, jak pokazano wyżej, dopóki nie zostanie to naprawione.

## Metadane

### createMetadata

Generuje metadane Next.js dla głównego układu strony.

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

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

**Opcje:**
- `baseUrl` - Podstawowy URL witryny (opcjonalnie)
- `additional` - Dodatkowe pola `Metadata`, scalane na końcu (opcjonalnie)

**Zwraca:** obiekt Next.js `Metadata` zawierający:
- Tytuł (`config.title`) i szablon tytułu (`%s | Site Name`)
- Opis
- Ikonę favicon z `config.icon`, jeśli ją ustawiono
- Gdy ustawiono `baseUrl`: `metadataBase`, metadane OpenGraph i kartę Twitter `summary_large_image`

### createDocsPageMetadata

Generuje metadane tytułu i opisu strony dokumentacji. Przyjmuje jeden obiekt z `title` i opcjonalnym `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,
  });
}
```

Obraz Open Graph dla pojedynczej strony opisano w sekcji [Dynamiczne obrazy OG](#dynamic-og-images).

## Obrazy OpenGraph

### createRootOGImage

Tworzy obraz OG strony głównej: logo wyśrodkowane na czarnym tle.

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

Tworzy obraz OG dla stron dokumentacji: logo w lewym górnym rogu, a tytuł biały na czarnym tle. Argument fontu jest opcjonalny; bez niego tytuł używa czcionki systemowej.

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

### Dynamiczne obrazy OG

Aby uzyskać obrazy OG dla poszczególnych stron, udostępnij je przez trasę. Strony nie są automatycznie kierowane do tej trasy: dodaj ją samodzielnie do metadanych każdej strony, na przykład za pomocą `openGraph: { images: "/docs/og/getting-started" }` obok pól 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);
}
```

### Funkcje pomocnicze

| Funkcja | Opis |
|----------|-------------|
| `loadPublicFile(path)` | Ładuje plik z `public/` jako dane URL i bufor; w przypadku SVG odczytuje także atrybuty `width` i `height` |
| `loadInterFont(path?)` | Ładuje czcionkę z `public/` dla obrazów OG, domyślnie `fonts/Inter-Medium.ttf` |
| `ogImageSize` | Standardowe wymiary obrazu OG `{ width: 1200, height: 630 }` |
| `ogImageContentType` | Typ MIME `"image/png"` |

**Wymagane pliki:**
- `public/logo-dark.svg` - Logo do obrazów OG. Funkcje pomocnicze OG określają jego rozmiar na podstawie atrybutów `width` i `height`, dlatego tag `<svg>` musi zawierać obie wartości jako zwykłe liczby.
- `public/fonts/Inter-Medium.ttf` - Czcionka tytułów. Onedocs nie zawiera tego pliku.

## LLMs.txt

Generuje pliki LLMs.txt dla asystentów AI.

### generateLLMsText

Generuje zwięzłą treść LLMs.txt. Przyjmuje źródło ujęte w `createLLMsSource` i `{ title, description? }`, a następnie zwraca 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" },
  });
}
```

Adresy URL stron są zapisywane w postaci pobranej ze źródła, na przykład `/docs/getting-started`, bez domeny.

### generateLLMsFullText

Generuje pełne LLMs.txt z kompletną treścią stron. Przyjmuje wyłącznie ujęte źródło i zwraca 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" },
  });
}
```

Treści stron są dołączane tylko wtedy, gdy Fumadocs MDX `includeProcessedMarkdown` jest włączona; zobacz [SEO i wyszukiwanie](https://onedocs.inline0.dev/pl/docs/seo-search#full-content-version).

### createLLMsSource

Opakowuje źródło Fumadocs (wynik `loader()` lub `createSource()`) w strukturę odczytywaną przez dwie funkcje powyżej: dla każdej strony jej URL, tytuł, opis oraz moduły ładujące tekst.

## SEO

### generateSitemap

Generuje mapę witryny dla dokumentacji. Przyjmuje jeden obiekt: `baseUrl`, listę `pages` (zwykle z `meta.json`) oraz opcjonalne `docsPath` (domyślnie `/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 ?? [],
  });
}
```

Informacje o tym, jak wpisy stają się adresami URL, znajdziesz w sekcji [SEO i wyszukiwanie](https://onedocs.inline0.dev/pl/docs/seo-search#sitemap).

### generateRobots

Generuje treść robots.txt: zezwala na wszystko, a także na linie `Host` i `Sitemap`. Domyślna wartość `sitemapPath` to `/sitemap.xml`.

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

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

## Ustawienie wstępne CSS

Zaimportuj ustawienie wstępne CSS w pliku `globals.css`:

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

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

Ścieżki w ustawieniu wstępnym `@source` są względne względem `src/app/globals.css`.

Ustawienie wstępne zawiera:
- Tailwind CSS v4 (zainstaluj samodzielnie `tailwindcss` i `@tailwindcss/postcss`)
- neutralny motyw Fumadocs
- style ustawienia wstępnego Fumadocs
- `--font-sans` ustawione na zmienną `--font-inter` definiowaną przez `FontHead`
- Funkcje OpenType fontu Inter dla tekstu głównego i nagłówków
- Style układu o pełnej wysokości oraz poprawki układu Onedocs

## Komponenty MDX

Eksport `mdxComponents` rozszerza domyślne komponenty Fumadocs UI MDX i dodaje poniższe komponenty:

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

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

**Dołączone komponenty:**
- Domyślne komponenty Fumadocs UI: `pre` (bloki kodu), `a`, `img`, `h1`–`h6` (nagłówki z kotwicami), `table`, `CodeBlockTab`, `CodeBlockTabs`, `CodeBlockTabsList`, `CodeBlockTabsTrigger`, `CalloutContainer`, `CalloutTitle`, `CalloutDescription`
- `Callout` - Komunikaty informacyjne, ostrzegawcze i o błędach
- `Card`, `Cards` - Układy kart
- `Tab`, `Tabs` - Treści z kartami
- `Step`, `Steps` - Numerowane kroki
- `Accordion`, `Accordions` - Zwijane sekcje
- `File`, `Folder`, `Files` - Drzewa plików
- `ImageZoom` - Powiększane obrazy
- `TypeTable` - Tabele dokumentujące typy

`InstallBlock` i `CodeBlock` nie są dołączone; dodaj je samodzielnie, jak pokazano w sekcji [Komponenty](https://onedocs.inline0.dev/pl/docs/components#more-components).

Przykłady użycia znajdziesz w sekcji [Komponenty](https://onedocs.inline0.dev/pl/docs/components).