# API teatmik

Täielik teatmik kõigi `onedocs` paketi eksporditavate üksuste kohta.

## Sisendpunktid

| Import | Kirjeldus |
|--------|-------------|
| `onedocs` | Peamine sisend: paigutused, komponendid, `mdxComponents`, `defineConfig`, lähtekoodi abifunktsioonid |
| `onedocs/components` | Fumadocs UI komponendid ning `InstallBlock`, `CodeBlock`, `Button` ja `Logo` |
| `onedocs/config` | Seadistuse abifunktsioonid |
| `onedocs/source` | Sisuallika utiliidid |
| `onedocs/metadata` | Metaandmete genereerimine |
| `onedocs/og` | OpenGraphi piltide genereerimine |
| `onedocs/llms` | LLMs.txt genereerimine |
| `onedocs/seo` | Saidikaart ja robots.txt |
| `onedocs/css/preset.css` | Tailwind CSS eelseadistus |

## Paigutused

### DocsLayout

Dokumentatsioonilehtede põhipaigutuse ümbris. Pakub külgriba navigeerimist, otsingut ja kujunduse lülitit.

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

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

**Rekvisiidid:**
- `config` – teie `OnedocsConfig` objekt
- `pageTree` – lähteandmete lehtede puu (nt e.g, `source.pageTree`)
- `children` – lehe sisu

### DocsPage

Ümbris üksikute dokumentatsioonilehtede jaoks. Ümbritseb Fumadocs UI `DocsPage` ja paigutab sisu elementi `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>
  );
}
```

**Rekvisiidid:**
- `toc` – lehe andmetest saadud sisukord
- `children` – MDX sisu
- Kõik muud Fumadocs UI `DocsPage` rekvisiidid, näiteks `full`

### DocsBody

Dokumentatsiooni sisu sisemine ümbris. Kasutab sisemiselt `DocsPage`.

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

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

### HomePage

Terviklik avalehe komponent tunnuslause, funktsioonide ja jalusega.

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

**Rekvisiidid:**
- `config` – teie `OnedocsConfig` objekt
- `packageName` – paigaldusploki paketi nimi (valikuline)
- `children` – sisu funktsioonide ja jaluse vahel (valikuline)

Vaadake linke [avaleht](https://onedocs.inline0.dev/et/docs/configuration#homepage) ja [jalus](https://onedocs.inline0.dev/et/docs/configuration#footer), et näha, mida seadistus juhib.

### HomeLayout

Avalehe põhipaigutus (kasutab sisemiselt `HomePage`).

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

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

### createBaseOptions

Koostab teie seadistuse põhjal Fumadocs UI paigutusvalikud (navigeerimisriba pealkiri või logo, `nav.links` ja link GitHub). `DocsLayout` ja `HomeLayout` kasutavad seda; kui renderdate otse paigutuse Fumadocs UI, kutsuge see ise välja.

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

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

## Komponendid

### InstallBlock

Paketihalduri vahekaardid, kus kuvatakse paigalduskäsud pakettidele npm, yarn, pnpm ja bun (`npm i`, `yarn add`, `pnpm add`, `bun add`). See on asünkroonne serverikomponent.

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

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

**Rekvisiidid:**
- `packageName` – installitava npm paketi nimi
- `title` – vahekaartide kohal olev pealkiri (valikuline)
- `description` – vahekaartide kohal olev tekst (valikuline)
- `children` – vahekaartide all olev sisu (valikuline)

### Button

Ümar link, mis on kujundatud peamise nupuna. Saadaval on üks stiil.

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

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

**Rekvisiidid:**
- `href` – lingi sihtkoht
- `children` – nupu tekst
- `className` – lisaklassid (valikuline)

### Logo

Kuvab heleda ja tumeda pildi ning näitab parajasti valitud kujundusele vastavat pilti. `DocsLayout` ja `HomePage` kasutavad seda pildi `logo` jaoks, millel on heledad ja tumedad variandid.

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

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

**Rekvisiidid:**
- `light` – heleda režiimi pildi tee
- `dark` – tumeda režiimi pildi tee
- `alt` – alternatiivtekst (vaikimisi: `"Logo"`)
- `className` – mõlema pildi klassid (valikuline)

### CTASection

Avalehe tegevusele kutsuv jaotis.

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

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

**Rekvisiidid:**
- `title` – jaotise pealkiri
- `description` – pealkirja all olev tekst (valikuline)
- `cta` – nupu seadistus koos väärtustega `label` ja `href`
- `children` – nupu all olev sisu (valikuline)

### FontHead

Laadib eellaadimisega Inter Variable'i fondi, määrab selle `@font-face` ja seab selle lehe fondiks. Lisage see juurpaigutuse `<head>`-isse.

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

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

Onedocs ei sisalda fonti. Vaikimisi laadib `FontHead` `/fonts/InterVariable.woff2`, seega paigutage fail asukohta `public/fonts/` või andke atribuudiga `fontPath` ette mõni muu URL:

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

### GitHubIcon

GitHub ikoonikomponent (kasutatakse navigeerimises sisemiselt).

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

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

### CodeBlock

Süntaksi esiletõstuga koodiplokk, mille süntaksi esiletõst tehakse serveris Shiki abil Fumadocs kaudu. See on asünkroonne serverikomponent.

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

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

## Konfiguratsioon

### defineConfig

Tüübikindel seadistuse abifunktsioon.

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

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

### OnedocsConfig

Seadistuse tüüp TypeScript jaoks.

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

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

Kõigi valikute kohta vaadake lehte [Seadistus](https://onedocs.inline0.dev/et/docs/configuration).

## Lähteandmete utiliidid

### loader

Sisuallikate loomiseks mõeldud `fumadocs-core/source` laaduri taaseksport.

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

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

### createSource

Sisuallika loomise abifunktsioon (laaduri ümbris). Baasi URL vaikeväärtus on `/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-s tagastab `createSource` tüübita allika, mistõttu TypeScript annab `page.data` lugemisel teada vigadest, näiteks `Property 'data' does not exist on type 'unknown'` ([#4](https://github.com/inline0/onedocs/issues/4)). Kuni see on parandatud, kasutage eespool näidatud viisil `loader`.

## Metaandmed

### createMetadata

Genereerib juurpaigutuse Next.js metaandmed.

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

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

**Valikud:**
- `baseUrl` – sinu saidi põhi-URL (valikuline)
- `additional` – täiendavad `Metadata` väljad, liidetakse viimasena (valikuline)

**Tagastab:** Next.js `Metadata` objekti, mis sisaldab:
- Pealkirja (`config.title`) ja pealkirjamalli (`%s | Site Name`)
- Kirjeldust
- `config.icon` pärit lemmikut, kui see on määratud
- Kui `baseUrl` on määratud: `metadataBase`, OpenGraphi metaandmeid ja Twitter `summary_large_image` kaarti

### createDocsPageMetadata

Genereerib dokumentatsioonilehe pealkirja ja kirjelduse metaandmed. Võtab ühe objekti, milles on `title` ja valikuline `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,
  });
}
```

Lehepõhise Open Graph pildi kohta vaata [Dünaamilised OG-pildid](#dynamic-og-images).

## OpenGraphi pildid

### createRootOGImage

Loob avalehele OG-pildi: logo mustal taustal keskel.

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

Loob dokumentatsioonilehtedele OG-pildi: logo vasakus ülanurgas ja pealkiri valgena mustal taustal. Fondiargument on valikuline; ilma selleta kasutatakse pealkirjas süsteemi fonti.

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

### Dünaamilised OG-pildid

Lehepõhiste OG-piltide jaoks paku neid marsruudilt. Lehti sellele marsruudile automaatselt ei suunata: lisa see ise iga lehe metaandmetesse, näiteks `createDocsPageMetadata` väljade kõrvale `openGraph: { images: "/docs/og/getting-started" }` abil.

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

### Abifunktsioonid

| Funktsioon | Kirjeldus |
|----------|-------------|
| `loadPublicFile(path)` | Laadib faili asukohast `public/` andme-URL ja puhvrina; SVG-de puhul loeb ka atribuudid `width` ja `height` |
| `loadInterFont(path?)` | Laadib OG-piltide jaoks fondi asukohast `public/`, vaikimisi `fonts/Inter-Medium.ttf` |
| `ogImageSize` | OG-pildi standardsed mõõtmed `{ width: 1200, height: 630 }` |
| `ogImageContentType` | MIME tüüpi `"image/png"` |

**Nõutavad failid:**
- `public/logo-dark.svg` – OG-piltide logo. OG-abifunktsioonid määravad selle suuruse atribuutide `width` ja `height` põhjal, seega peavad `<svg>` sildis olema mõlemad tavaliste arvudena.
- `public/fonts/Inter-Medium.ttf` – pealkirjade font. Onedocs seda kaasa ei paki.

## LLMs.txt

Loo tehisintellekti assistentidele LLMs.txt failid.

### generateLLMsText

Genereerib lühikese LLMs.txt sisu. Võtab allika, mis on mähitud `createLLMsSource` ja `{ title, description? }` vahele, ning tagastab lubaduse.

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

Lehe URL-id kirjutatakse nii, nagu need allikas esinevad, näiteks `/docs/getting-started`, ilma domeenita.

### generateLLMsFullText

Genereerib täieliku LLMs.txt kogu lehe sisuga. Võtab ainult mähitud allika ja tagastab lubaduse.

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

Lehe sisu lisatakse ainult siis, kui Fumadocs MDX valik `includeProcessedMarkdown` on sisse lülitatud; vt [SEO ja otsing](https://onedocs.inline0.dev/et/docs/seo-search#full-content-version).

### createLLMsSource

Mähistab Fumadocs allika (`loader()` või `createSource()` tulemi) kujule, mida kaks ülaltoodud funktsiooni loevad: iga lehe URL, pealkirja, kirjelduse ja teksti laadijad.

## SEO

### generateSitemap

Genereerib sinu dokumentatsiooni jaoks saidikaardi. Võtab ühe objekti: `baseUrl`, `pages` loendi (tavaliselt saadud funktsioonist `meta.json`) ja valikulise `docsPath` (vaikimisi `/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 ?? [],
  });
}
```

Vaata jaotisest [SEO ja otsing](https://onedocs.inline0.dev/et/docs/seo-search#sitemap), kuidas kirjetest URL-id moodustuvad.

### generateRobots

Genereerib robots.txt sisu: lubab kõik, lisaks `Host` ja `Sitemap` read. `sitemapPath` vaikimisi on `/sitemap.xml`.

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

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

## CSS eelseadistus

Impordi CSS eelseadistus oma `globals.css`-i:

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

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

`@source` teed on suhtelised `src/app/globals.css` suhtes.

Eelseadistus sisaldab:
- Tailwind CSS v4 vaikeväärtusi (paigalda ise `tailwindcss` ja `@tailwindcss/postcss`)
- Fumadocs neutraalset kujundust
- Fumadocs eelseadistatud stiile
- `--font-sans`, mille väärtuseks on `FontHead` määratud muutuja `--font-inter`
- Interi OpenType'i funktsioone põhiteksti ja pealkirjade jaoks
- Täiskõrgusega paigutuse stiile ja Onedocs paigutuse kohandusi

## MDX komponendid

Eksport `mdxComponents` laiendab vaikeväärtusi Fumadocs UI komponendiga MDX ning lisab allolevad komponendid:

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

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

**Kaasatud komponendid:**
- Fumadocs UI vaikeväärtused: `pre` (koodiplokid), `a`, `img`, `h1` kuni `h6` (ankrutega pealkirjad), `table`, `CodeBlockTab`, `CodeBlockTabs`, `CodeBlockTabsList`, `CodeBlockTabsTrigger`, `CalloutContainer`, `CalloutTitle`, `CalloutDescription`
- `Callout` – teabe-, hoiatus- ja veateated
- `Card`, `Cards` – kaardipaigutused
- `Tab`, `Tabs` – vahekaartidega sisu
- `Step`, `Steps` – nummerdatud sammud
- `Accordion`, `Accordions` – ahendatavad jaotised
- `File`, `Folder`, `Files` – failipuud
- `ImageZoom` – suurendatavad pildid
- `TypeTable` – tüüpidokumentatsiooni tabelid

`InstallBlock` ja `CodeBlock` ei kuulu komplekti; lisa need ise, nagu näidatud jaotises [Komponendid](https://onedocs.inline0.dev/et/docs/components#more-components).

Kasutusnäiteid vaata jaotisest [Komponendid](https://onedocs.inline0.dev/et/docs/components).