# API-viiteopas

Kattava opas kaikista `onedocs`-paketin viennistä.

## Aloituskohdat

| Tuonti | Kuvaus |
|--------|-------------|
| `onedocs` | Pääsisäänkäynti – asettelut, komponentit, `mdxComponents`, `defineConfig` ja lähdeapufunktiot |
| `onedocs/components` | Fumadocs UI -komponentit sekä `InstallBlock`, `CodeBlock`, `Button` ja `Logo` |
| `onedocs/config` | Asetusten apufunktiot |
| `onedocs/source` | Sisältölähteen apuohjelmat |
| `onedocs/metadata` | Metatietojen luonti |
| `onedocs/og` | OpenGraph-kuvan luonti |
| `onedocs/llms` | LLMs.txt-luonti |
| `onedocs/seo` | Sivustokartta ja robots.txt |
| `onedocs/css/preset.css` | Tailwind CSS-esiasetus |

## Asetteluja

### DocsLayout

Dokumentaatiosivujen asettelun pääkääre. Tarjoaa sivupalkin navigoinnin, haun ja teeman vaihdon.

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

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

**Ominaisuudet:**
- `config` – `OnedocsConfig`-objektisi
- `pageTree` – sivupuu lähteestäsi (e.g, `source.pageTree`)
- `children` – sivun sisältö

### DocsPage

Yksittäisten dokumentaatiosivujen kääre. Käärii Fumadocs UI `DocsPage` ja sijoittaa sisällön kohteeseen `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>
  );
}
```

**Ominaisuudet:**
- `toc` – sivun tiedoista saatu sisällysluettelo
- `children` – MDX-sisältö
- Kaikki muut Fumadocs UI `DocsPage`-komponentin ominaisuudet, kuten `full`

### DocsBody

Dokumentaatiosisällön sisempi kääre. Käytössä sisäisesti kohteessa `DocsPage`.

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

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

### HomePage

Koko etusivun komponentti, jossa on hero-osio, ominaisuudet ja alatunniste.

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

**Ominaisuudet:**
- `config` – `OnedocsConfig`-objektisi
- `packageName` – asennuslohkon paketin nimi (valinnainen)
- `children` – ominaisuuksien ja alatunnisteen välinen sisältö (valinnainen)

Katso, mitä asetukset määrittävät: [etusivu](https://onedocs.inline0.dev/fi/docs/configuration#homepage) ja [alatunniste](https://onedocs.inline0.dev/fi/docs/configuration#footer).

### HomeLayout

Etusivun perusasettelu (käytössä sisäisesti kohteessa `HomePage`).

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

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

### createBaseOptions

Luo asetuksistasi Fumadocs UI-asetteluvaihtoehdot (navigointipalkin otsikko tai logo, `nav.links` ja GitHub-linkki). `DocsLayout` ja `HomeLayout` käyttävät sitä; kutsu sitä itse, kun renderöit suoraan Fumadocs UI-asettelun.

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

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

## Komponentit

### InstallBlock

Pakettienhallinnan välilehdet, jotka näyttävät asennuskomennot paketeille npm, yarn, pnpm ja bun (`npm i`, `yarn add`, `pnpm add`, `bun add`). Tämä on asynkroninen palvelinkomponentti.

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

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

**Ominaisuudet:**
- `packageName` – asennettavan npm-paketin nimi
- `title` – välilehtien yläpuolella oleva otsikko (valinnainen)
- `description` – välilehtien yläpuolella oleva teksti (valinnainen)
- `children` – välilehtien alla oleva sisältö (valinnainen)

### Button

Pyöristetty linkki, joka on muotoiltu ensisijaiseksi painikkeeksi. Käytössä on yksi tyyli.

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

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

**Ominaisuudet:**
- `href` – linkin kohde
- `children` – painikkeen teksti
- `className` – lisäluokat (valinnainen)

### Logo

Näyttää vaalean ja tumman kuvan ja valitsee niistä nykyiseen teemaan sopivan. `DocsLayout` ja `HomePage` käyttävät sitä kohteen `logo` kanssa, jolle on vaalea ja tumma versio.

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

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

**Ominaisuudet:**
- `light` – kuvan polku vaaleassa tilassa
- `dark` – kuvan polku tummassa tilassa
- `alt` – vaihtoehtoinen teksti (oletus: `"Logo"`)
- `className` – molempien kuvien luokat (valinnainen)

### CTASection

Etusivun toimintakehotusosio.

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

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

**Ominaisuudet:**
- `title` – osion otsikko
- `description` – otsikon alla oleva teksti (valinnainen)
- `cta` – painikkeen asetukset, joissa ovat `label` ja `href`
- `children` – painikkeen alla oleva sisältö (valinnainen)

### FontHead

Esilataa Inter Variable -fontin, määrittää sen `@font-face`-arvon ja asettaa sen sivun fontiksi. Lisää se juuriasettelusi kohteeseen `<head>`.

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

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

Onedocs ei sisällä fonttia. Oletusarvoisesti `FontHead` lataa `/fonts/InterVariable.woff2`, joten sijoita tiedosto kohteeseen `public/fonts/` tai välitä toinen URL kohteen `fontPath` kanssa:

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

### GitHubIcon

GitHub-kuvakekomponentti (käytössä sisäisesti navigoinnissa).

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

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

### CodeBlock

Syntaksikorostettu koodilohko, jonka korostus tehdään palvelimella käyttäen Shiki- ja Fumadocs-arvoja. Tämä on asynkroninen palvelinkomponentti.

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

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

## Määritykset

### defineConfig

Tyyppiturvallinen asetusten apufunktio.

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

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

### OnedocsConfig

TypeScript-tyyppi asetuksille.

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

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

Katso kaikki vaihtoehdot kohdasta [Asetukset](https://onedocs.inline0.dev/fi/docs/configuration).

## Lähdeapuohjelmat

### loader

`fumadocs-core/source`-lataajan uudelleenvienti sisältölähteiden luomiseen.

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

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

### createSource

Apufunktio sisältölähteen luomiseen (lataajan kääre). Perus-URL-arvona on oletuksena `/docs`.

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

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

Kohteessa 0.1.27 `createSource` palauttaa tyypittämättömän lähteen, joten TypeScript ilmoittaa virheistä, kuten `Property 'data' does not exist on type 'unknown'`, kun luet kohdetta `page.data` ([#4](https://github.com/inline0/onedocs/issues/4)). Käytä yllä kuvattua `loader`, kunnes ongelma on korjattu.

## Metatiedot

### createMetadata

Luo juuriasettelullesi Next.js-metatiedot.

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

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

**Asetukset:**
- `baseUrl` – sivustosi perus-URL (valinnainen)
- `additional` – ylimääräiset `Metadata`-kentät, jotka yhdistetään viimeiseksi (valinnainen)

**Palauttaa:** Next.js `Metadata`-objektin, jossa ovat:
- Otsikko (`config.title`) ja otsikkomalli (`%s | Site Name`)
- Kuvaus
- Suosikkikuvake kohteesta `config.icon`, jos asetettu
- Jos `baseUrl` on asetettu: `metadataBase`, OpenGraph-metatiedot ja Twitter `summary_large_image`-kortti

### createDocsPageMetadata

Luo dokumentaatiosivun otsikon ja kuvauksen metatiedot. Saa yhden objektin, jossa on `title` ja valinnainen `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,
  });
}
```

Katso sivukohtaiset Open Graph-kuvat kohdasta [Dynaamiset OG-kuvat](#dynamic-og-images).

## OpenGraph-kuvat

### createRootOGImage

Luo etusivulle OG-kuvan, jossa logo on keskellä mustaa taustaa.

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

Luo dokumentaatiosivuille OG-kuvan, jossa logo on vasemmassa yläkulmassa ja otsikko valkoisena mustalla taustalla. Fonttiargumentti on valinnainen; ilman sitä otsikossa käytetään järjestelmäfonttia.

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

### Dynaamiset OG-kuvat

Tarjoa sivukohtaiset OG-kuvat reitiltä. Sivut eivät viittaa tähän reittiin automaattisesti: lisää se kunkin sivun metatietoihin itse, esimerkiksi kohteen `createDocsPageMetadata` kenttien viereen muodossa `openGraph: { images: "/docs/og/getting-started" }`.

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

### Apuohjelmat

| Funktio | Kuvaus |
|----------|-------------|
| `loadPublicFile(path)` | Lataa tiedoston kohteesta `public/` datana URL ja puskurina; SVG-tiedostoista se lukee myös `width`- ja `height`-attribuutit |
| `loadInterFont(path?)` | Lataa OG-kuvien fontin kohteesta `public/`; oletuksena `fonts/Inter-Medium.ttf` |
| `ogImageSize` | OG-kuvan vakiomitat `{ width: 1200, height: 630 }` |
| `ogImageContentType` | MIME-tyypin `"image/png"` |

**Vaaditut tiedostot:**
- `public/logo-dark.svg` – OG-kuvien logo. OG-apuohjelmat määrittävät sen koon `width`- ja `height`-attribuuttien perusteella, joten `<svg>`-tunnisteessa molempien on oltava tavallisia numeroita.
- `public/fonts/Inter-Medium.ttf` – otsikoiden fontti. Onedocs ei sisällä sitä.

## LLMs.txt

Luo LLMs.txt-tiedostoja tekoälyavustajille.

### generateLLMsText

Luo ytimekästä LLMs.txt-sisältöä. Saa lähteen, joka on kääritty kohteilla `createLLMsSource` ja `{ title, description? }`, ja palauttaa lupauksen.

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

Sivujen URL-osoitteet kirjoitetaan lähteen mukaisina, esimerkiksi `/docs/getting-started`, ilman verkkotunnusta.

### generateLLMsFullText

Luo täydellisen LLMs.txt-sisällön kaikkine sivujen sisältöineen. Saa vain käärityn lähteen ja palauttaa lupauksen.

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

Sivujen rungot sisällytetään vain, kun Fumadocs MDXn `includeProcessedMarkdown` on käytössä; katso [SEO ja haku](https://onedocs.inline0.dev/fi/docs/seo-search#full-content-version).

### createLLMsSource

Käärii Fumadocs-lähteen (`loader()`- tai `createSource()`-tuloksen) muotoon, jota yllä olevat kaksi funktiota käyttävät: kunkin sivun URL sekä otsikko, kuvaus ja tekstilataajat.

## SEO

### generateSitemap

Luo dokumentaatiollesi sivustokartan. Saa yhden objektin: `baseUrl`, `pages`-luettelon (yleensä kohteesta `meta.json`) sekä valinnaisen `docsPath`-arvon (oletus `/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 ?? [],
  });
}
```

Katso kohdasta [SEO ja haku](https://onedocs.inline0.dev/fi/docs/seo-search#sitemap), miten merkinnät muuttuvat URL-osoitteiksi.

### generateRobots

Luo robots.txt-sisältöä: salli kaikki sekä `Host`- ja `Sitemap`-rivit. `sitemapPath`-arvon oletus on `/sitemap.xml`.

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

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

## CSS-esiasetus

Tuo CSS-esiasetus kohteeseen `globals.css`:

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

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

`@source`-polut ovat suhteessa kohteeseen `src/app/globals.css`.

Esiasetus sisältää:
- Tailwind CSS v4 (asenna `tailwindcss` ja `@tailwindcss/postcss` itse)
- Fumadocs-neutraalin teeman
- Fumadocs-esiasetuksen tyylit
- `--font-sans` asetettuna kohteen `FontHead` määrittämään `--font-inter`-muuttujaan
- Inter OpenType -ominaisuudet leipätekstille ja otsikoille
- Korkean asettelun tyylit ja kohteen Onedocs asettelun hienosäädöt

## MDX-komponentit

`mdxComponents`-vienti levittää kohteen Fumadocs UI oletus-MDX-komponentit ja lisää alla luetellut komponentit:

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

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

**Sisältyvät komponentit:**
- Fumadocs UI oletukset: `pre` (koodilohkot), `a`, `img`, `h1` – `h6` (ankkurilinkilliset otsikot), `table`, `CodeBlockTab`, `CodeBlockTabs`, `CodeBlockTabsList`, `CodeBlockTabsTrigger`, `CalloutContainer`, `CalloutTitle`, `CalloutDescription`
- `Callout` – tieto-, varoitus- ja virheilmoitukset
- `Card`, `Cards` – korttiasettelut
- `Tab`, `Tabs` – välilehdillä jaettu sisältö
- `Step`, `Steps` – numeroidut vaiheet
- `Accordion`, `Accordions` – kokoon taitettavat osiot
- `File`, `Folder`, `Files` – tiedostopuut
- `ImageZoom` – suurennettavat kuvat
- `TypeTable` – tyyppien dokumentaatiotaulukot

`InstallBlock` ja `CodeBlock` eivät sisälly pakettiin; lisää ne itse [Components](https://onedocs.inline0.dev/fi/docs/components#more-components)-sivulla kuvatulla tavalla.

Katso käyttöesimerkkejä [Components](https://onedocs.inline0.dev/fi/docs/components)-sivulta.