# API žinynas

Visų eksportų iš `onedocs` paketo žinynas.

## Pradiniai taškai

| Importas | Aprašymas |
|--------|-------------|
| `onedocs` | Pagrindinis įėjimo taškas – išdėstymai, komponentai, `mdxComponents`, `defineConfig`, šaltinio pagalbinės funkcijos |
| `onedocs/components` | Fumadocs UI komponentai ir `InstallBlock`, `CodeBlock`, `Button` bei `Logo` |
| `onedocs/config` | Konfigūracijos pagalbinės funkcijos |
| `onedocs/source` | Turinio šaltinio įrankiai |
| `onedocs/metadata` | Metaduomenų generavimas |
| `onedocs/og` | OpenGraph vaizdų generavimas |
| `onedocs/llms` | LLMs.txt generavimas |
| `onedocs/seo` | Svetainės žemėlapis ir robots.txt |
| `onedocs/css/preset.css` | Tailwind CSS išankstinis nustatymas |

## Maketai

### DocsLayout

Pagrindinis dokumentacijos puslapių išdėstymo apvalkalas. Jame pateikiama šoninė navigacija, paieška ir temos perjungimas.

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

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

**Savybės:**
- `config` – jūsų `OnedocsConfig` objektas
- `pageTree` – puslapių medis iš jūsų šaltinio (e.g, `source.pageTree`)
- `children` – puslapio turinys

### DocsPage

Atskiriems dokumentacijos puslapiams skirtas apvalkalas. Jis apgaubia Fumadocs UI `DocsPage` ir įdeda turinį į `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>
  );
}
```

**Savybės:**
- `toc` – turinio lentelė iš puslapio duomenų
- `children` – MDX turinys
- Bet kuri kita Fumadocs UI `DocsPage` savybė, pavyzdžiui, `full`

### DocsBody

Vidinis dokumentacijos turinio apvalkalas. Naudojamas viduje `DocsPage`.

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

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

### HomePage

Viso pradžios puslapio komponentas su pagrindine sritimi, funkcijomis ir porašte.

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

**Savybės:**
- `config` – jūsų `OnedocsConfig` objektas
- `packageName` – paketo pavadinimas diegimo bloke (nebūtina)
- `children` – turinys tarp funkcijų ir poraštės (nebūtina)

Žr. [pagrindinį puslapį](https://onedocs.inline0.dev/lt/docs/configuration#homepage) ir [poraštę](https://onedocs.inline0.dev/lt/docs/configuration#footer), kad sužinotumėte, ką valdo konfigūracija.

### HomeLayout

Pagrindinis pradžios puslapio išdėstymas (viduje naudojamas `HomePage`).

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

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

### createBaseOptions

Iš jūsų konfigūracijos sudaro Fumadocs UI išdėstymo parinktis (navigacijos juostos pavadinimą arba logotipą, `nav.links` ir GitHub nuorodą). Jį naudoja `DocsLayout` ir `HomeLayout`; iškvieskite jį patys, kai tiesiogiai atvaizduojate Fumadocs UI išdėstymą.

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

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

## Komponentai

### InstallBlock

Paketų tvarkyklių skirtukai su npm, yarn, pnpm ir bun diegimo komandomis (`npm i`, `yarn add`, `pnpm add`, `bun add`). Tai asinchroninis serverio komponentas.

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

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

**Savybės:**
- `packageName` – diegiamo npm paketo pavadinimas
- `title` – antraštė virš skirtukų (nebūtina)
- `description` – tekstas virš skirtukų (nebūtina)
- `children` – turinys po skirtukais (nebūtina)

### Button

Suapvalinta nuoroda, stilizuota kaip pagrindinis mygtukas. Yra tik vienas stilius.

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

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

**Savybės:**
- `href` – nuorodos paskirties vieta
- `children` – mygtuko tekstas
- `className` – papildomos klasės (nebūtina)

### Logo

Atvaizduoja šviesų ir tamsų vaizdą, o tada parodo tą, kuris atitinka dabartinę temą. `DocsLayout` ir `HomePage` jį naudoja `logo` su šviesiu ir tamsiu variantais.

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

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

**Savybės:**
- `light` – vaizdo kelias šviesiajai temai
- `dark` – vaizdo kelias tamsiajai temai
- `alt` – alternatyvusis tekstas (numatytoji reikšmė: `"Logo"`)
- `className` – abiejų vaizdų klasės (nebūtina)

### CTASection

Pradžios puslapio raginimo veikti skiltis.

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

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

**Savybės:**
- `title` – skilties antraštė
- `description` – tekstas po antrašte (nebūtina)
- `cta` – mygtuko konfigūracija su `label` ir `href`
- `children` – turinys po mygtuku (nebūtina)

### FontHead

Iš anksto įkelia Inter Variable šriftą, deklaruoja jo `@font-face` ir nustato jį kaip puslapio šriftą. Pridėkite prie šakninio išdėstymo `<head>`.

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

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

Onedocs šrifto netiekia. Pagal numatytuosius nustatymus `FontHead` įkelia `/fonts/InterVariable.woff2`, todėl įdėkite failą į `public/fonts/` arba perduokite kitą URL su `fontPath`:

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

### GitHubIcon

GitHub piktogramos komponentas (viduje naudojamas navigacijoje).

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

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

### CodeBlock

Sintaksę paryškinantis kodo blokas, kurį serveryje paryškina Shiki per Fumadocs. Tai asinchroninis serverio komponentas.

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

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

## Konfigūracija

### defineConfig

Tipų saugi konfigūracijos pagalbinė funkcija.

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

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

### OnedocsConfig

TypeScript konfigūracijos tipas.

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

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

Visas parinktis rasite skiltyje [Konfigūracija](https://onedocs.inline0.dev/lt/docs/configuration).

## Šaltinio įrankiai

### loader

Pakartotinis `fumadocs-core/source` krautuvo eksportas turinio šaltiniams kurti.

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

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

### createSource

Pagalbinė funkcija turinio šaltiniui kurti (krautuvo apvalkalas). Pagrindinė URL reikšmė pagal numatytuosius nustatymus yra `/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` grąžina netipuotą šaltinį, todėl TypeScript praneša apie tokias klaidas kaip `Property 'data' does not exist on type 'unknown'`, kai skaitote `page.data` ([#4](https://github.com/inline0/onedocs/issues/4)). Kol tai bus pataisyta, naudokite aukščiau parodytą `loader`.

## Metaduomenys

### createMetadata

Generuoja Next.js metaduomenis jūsų šakniniam išdėstymui.

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

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

**Parinktys:**
- `baseUrl` – pagrindinis jūsų svetainės URL (nebūtina)
- `additional` – papildomi `Metadata` laukai, sujungiami paskiausiai (nebūtina)

**Grąžina:** Next.js `Metadata` objektą su:
- Pavadinimu (`config.title`) ir pavadinimo šablonu (`%s | Site Name`)
- Aprašu
- Piktograma iš `config.icon`, jei nustatyta
- Jei nustatyta `baseUrl`: `metadataBase`, OpenGraph metaduomenimis ir Twitter `summary_large_image` kortele

### createDocsPageMetadata

Generuoja dokumentacijos puslapio pavadinimo ir aprašo metaduomenis. Priima vieną objektą su `title` ir pasirinktiniu `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,
  });
}
```

Puslapiui skirtą Open Graph vaizdą rasite skiltyje [Dinaminiai OG vaizdai](#dynamic-og-images).

## OpenGraph vaizdai

### createRootOGImage

Sukuria pradžios puslapio OG vaizdą: logotipas juodo fono centre.

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

Sukuria dokumentacijos puslapių OG vaizdą: logotipas viršuje kairėje, pavadinimas baltai juodame fone. Šrifto argumentas pasirinktinis; jei jo nėra, pavadinimui naudojamas sistemos šriftas.

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

### Dinaminiai OG vaizdai

Puslapių OG vaizdus pateikite iš maršruto. Puslapiai automatiškai nebus susieti su šiuo maršrutu: patys įtraukite jį į kiekvieno puslapio metaduomenis, pavyzdžiui, su `openGraph: { images: "/docs/og/getting-started" }` greta laukų iš `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);
}
```

### Pagalbinės funkcijos

| Funkcija | Aprašymas |
|----------|-------------|
| `loadPublicFile(path)` | Įkelia failą iš `public/` kaip duomenų URL ir buferį; SVG failams taip pat nuskaito atributus `width` ir `height` |
| `loadInterFont(path?)` | Įkelia OG vaizdų šriftą iš `public/`; pagal numatytuosius nustatymus – `fonts/Inter-Medium.ttf` |
| `ogImageSize` | Standartiniai OG vaizdo matmenys `{ width: 1200, height: 630 }` |
| `ogImageContentType` | MIME tipo `"image/png"` |

**Būtini failai:**
- `public/logo-dark.svg` – OG vaizdų logotipas. OG pagalbinės funkcijos nustato jo dydį pagal atributus `width` ir `height`, todėl `<svg>` žymoje abu turi būti paprasti skaičiai.
- `public/fonts/Inter-Medium.ttf` – pavadinimų šriftas. Onedocs jo netiekia.

## LLMs.txt

Generuokite LLMs.txt failus DI asistentams.

### generateLLMsText

Generuoja glaustą LLMs.txt turinį. Priima šaltinį, apgaubtą `createLLMsSource` ir `{ title, description? }`, ir grąžina pažadą.

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

Puslapių URL įrašomi taip, kaip pateikiami šaltinyje, pavyzdžiui, `/docs/getting-started`, be domeno.

### generateLLMsFullText

Generuoja visą LLMs.txt su visu puslapio turiniu. Priima tik apgaubtą šaltinį ir grąžina pažadą.

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

Puslapių turinys įtraukiamas tik tada, kai įjungta Fumadocs MDX parinktis `includeProcessedMarkdown`; žr. [SEO ir paieška](https://onedocs.inline0.dev/lt/docs/seo-search#full-content-version).

### createLLMsSource

Apgaubia Fumadocs šaltinį (`loader()` arba `createSource()` rezultatą) forma, kurią nuskaito dvi pirmiau nurodytos funkcijos: kiekvieno puslapio URL, pavadinimą, aprašą ir teksto krautuvus.

## SEO

### generateSitemap

Generuoja dokumentacijos svetainės svetainės žemėlapį. Priima vieną objektą: `baseUrl`, `pages` sąrašą (paprastai iš `meta.json`) ir pasirinktinį `docsPath` (numatytoji reikšmė `/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 ?? [],
  });
}
```

Kaip įrašai virsta URL, sužinosite skiltyje [SEO ir paieška](https://onedocs.inline0.dev/lt/docs/seo-search#sitemap).

### generateRobots

Generuoja robots.txt turinį: leidžia viską ir prideda `Host` bei `Sitemap` eilutes. `sitemapPath` numatytoji reikšmė yra `/sitemap.xml`.

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

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

## CSS išankstinis nustatymas

Importuokite CSS išankstinį nustatymą į savo `globals.css`:

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

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

`@source` keliai nurodomi `src/app/globals.css` atžvilgiu.

Į išankstinį nustatymą įtraukta:
- Tailwind CSS v4 (`tailwindcss` ir `@tailwindcss/postcss` įsidiekite patys)
- Fumadocs neutrali tema
- Fumadocs išankstinio nustatymo stiliai
- `--font-sans` nustatytas į `FontHead` apibrėžiamą kintamąjį `--font-inter`
- Inter OpenType funkcijos pagrindiniam tekstui ir antraštėms
- Viso aukščio išdėstymo stiliai ir Onedocs išdėstymo koregavimai

## MDX komponentai

`mdxComponents` eksportas išskleidžia numatytuosius Fumadocs UI komponentus ir prideda toliau pateiktus komponentus:
MDX

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

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

**Įtraukti komponentai:**
- Fumadocs UI numatytieji komponentai: `pre` (kodo blokai), `a`, `img`, `h1`–`h6` (antraštės su inkarais), `table`, `CodeBlockTab`, `CodeBlockTabs`, `CodeBlockTabsList`, `CodeBlockTabsTrigger`, `CalloutContainer`, `CalloutTitle`, `CalloutDescription`
- `Callout` – informaciniai, įspėjamieji ir klaidų pranešimai
- `Card`, `Cards` – kortelių išdėstymai
- `Tab`, `Tabs` – turinys su skirtukais
- `Step`, `Steps` – sunumeruoti veiksmai
- `Accordion`, `Accordions` – sutraukiamos skiltys
- `File`, `Folder`, `Files` – failų medžiai
- `ImageZoom` – priartinami vaizdai
- `TypeTable` – tipų dokumentacijos lentelės

`InstallBlock` ir `CodeBlock` neįtraukti; pridėkite juos patys, kaip parodyta skiltyje [Komponentai](https://onedocs.inline0.dev/lt/docs/components#more-components).

Naudojimo pavyzdžių rasite skiltyje [Komponentai](https://onedocs.inline0.dev/lt/docs/components).