# Referenca za API

Popoln referenčni priročnik za vse izvoze iz paketa `onedocs`.

## Vstopne točke

| Uvoz | Opis |
|--------|-------------|
| `onedocs` | Glavna vstopna točka – postavitve, komponente, `mdxComponents`, `defineConfig`, pomožne funkcije za vire |
| `onedocs/components` | Komponente Fumadocs UI ter `InstallBlock`, `CodeBlock`, `Button` in `Logo` |
| `onedocs/config` | Pomožne funkcije za konfiguracijo |
| `onedocs/source` | Orodja za vire vsebine |
| `onedocs/metadata` | Ustvarjanje metapodatkov |
| `onedocs/og` | Ustvarjanje slik OpenGraph |
| `onedocs/llms` | Ustvarjanje LLMs.txt |
| `onedocs/seo` | Zemljevid spletnega mesta in robots.txt |
| `onedocs/css/preset.css` | Prednastavitev Tailwind CSS |

## Postavitve

### DocsLayout

Glavni ovoj postavitve za strani dokumentacije. Omogoča stransko navigacijo, iskanje in preklop teme.

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

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

**Lastnosti:**
- `config` – vaš objekt `OnedocsConfig`
- `pageTree` – drevo strani iz vašega vira (e.g., `source.pageTree`)
- `children` – vsebina strani

### DocsPage

Ovoj za posamezne strani dokumentacije. Ovije Fumadocs UI `DocsPage` in vsebino vstavi v `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>
  );
}
```

**Lastnosti:**
- `toc` – kazalo vsebine iz podatkov strani
- `children` – vsebina MDX
- katera koli druga lastnost za Fumadocs UI `DocsPage`, na primer `full`

### DocsBody

Notranji ovoj telesa za vsebino dokumentacije. Interno ga uporablja `DocsPage`.

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

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

### HomePage

Komponenta celotne ciljne strani z uvodnim pasom, funkcijami in nogo.

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

**Lastnosti:**
- `config` – vaš objekt `OnedocsConfig`
- `packageName` – ime paketa za blok za namestitev (izbirno)
- `children` – vsebina med funkcijami in nogo (izbirno)

Oglejte si [domačo stran](https://onedocs.inline0.dev/sl/docs/configuration#homepage) in [nogo](https://onedocs.inline0.dev/sl/docs/configuration#footer), da izveste, kaj upravlja konfiguracija.

### HomeLayout

Osnovna postavitev domače strani (interno jo uporablja `HomePage`).

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

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

### createBaseOptions

Iz konfiguracije sestavi možnosti postavitve Fumadocs UI (naslov navigacijske vrstice ali logotip, `nav.links` in povezavo GitHub). Uporabljata jo `DocsLayout` in `HomeLayout`; sami jo pokličite, kadar neposredno izrišete postavitev Fumadocs UI.

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

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

## Komponente

### InstallBlock

Zavihki upravljalnikov paketov s prikazom ukazov za namestitev npm, yarn, pnpm in bun (`npm i`, `yarn add`, `pnpm add`, `bun add`). Gre za asinhrono strežniško komponento.

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

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

**Lastnosti:**
- `packageName` – ime paketa npm za namestitev
- `title` – naslov nad zavihki (izbirno)
- `description` – besedilo nad zavihki (izbirno)
- `children` – vsebina pod zavihki (izbirno)

### Button

Zaobljena povezava v slogu primarnega gumba. Na voljo je en slog.

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

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

**Lastnosti:**
- `href` – cilj povezave
- `children` – besedilo gumba
- `className` – dodatni razredi (izbirno)

### Logo

Izriše svetlo in temno sliko ter prikaže tisto, ki ustreza trenutni temi. `DocsLayout` in `HomePage` jo uporabljata za `logo` s svetlimi in temnimi različicami.

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

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

**Lastnosti:**
- `light` – pot do slike za svetli način
- `dark` – pot do slike za temni način
- `alt` – nadomestno besedilo (privzeto: `"Logo"`)
- `className` – razredi za obe sliki (izbirno)

### CTASection

Razdelek s pozivom k dejanju na domači strani.

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

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

**Lastnosti:**
- `title` – naslov razdelka
- `description` – besedilo pod naslovom (izbirno)
- `cta` – konfiguracija gumba z `label` in `href`
- `children` – vsebina pod gumbom (izbirno)

### FontHead

Vnaprej naloži pisavo Inter Variable, določi njen `@font-face` in jo nastavi kot pisavo strani. Dodajte jo v `<head>` korenske postavitve.

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

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

Onedocs ne vključuje pisave. Privzeto `FontHead` naloži `/fonts/InterVariable.woff2`, zato datoteko shranite v `public/fonts/` ali podajte drug URL z `fontPath`:

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

### GitHubIcon

Komponenta ikone GitHub (interno se uporablja v navigaciji).

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

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

### CodeBlock

Blok kode s poudarjeno sintakso, ki jo na strežniku poudari Shiki prek Fumadocs. Gre za asinhrono strežniško komponento.

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

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

## Konfiguracija

### defineConfig

Pomožna funkcija za konfiguracijo s preverjanjem tipov.

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

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

### OnedocsConfig

Tip TypeScript za konfiguracijo.

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

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

Vse možnosti najdete v razdelku [Konfiguracija](https://onedocs.inline0.dev/sl/docs/configuration).

## Pomožne funkcije za vire

### loader

Ponovni izvoz nalagalnika `fumadocs-core/source` za ustvarjanje virov vsebine.

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

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

### createSource

Pomožna funkcija za ustvarjanje vira vsebine (ovoj okoli nalagalnika). Osnovni URL je privzeto nastavljen na `/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` vrne netipiziran vir, zato TypeScript javi napake, kot je `Property 'data' does not exist on type 'unknown'`, ko berete `page.data` ([#4](https://github.com/inline0/onedocs/issues/4)). Do odprave napake uporabite `loader`, kot je prikazano zgoraj.

## Metapodatki

### createMetadata

Ustvari metapodatke Next.js za vašo korensko postavitev.

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

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

**Možnosti:**
- `baseUrl` – osnovni URL vašega spletnega mesta (izbirno)
- `additional` – dodatna polja `Metadata`, združena na koncu (izbirno)

**Vrne:** objekt Next.js `Metadata` z naslednjim:
- Naslov (`config.title`) in predloga naslova (`%s | Site Name`)
- Opis
- Ikona zaznamka iz `config.icon`, če je nastavljena
- Če je nastavljen `baseUrl`: `metadataBase`, metapodatki OpenGraph in kartica Twitter `summary_large_image`

### createDocsPageMetadata

Ustvari metapodatke naslova in opisa za stran z dokumentacijo. Sprejme en objekt z `title` in izbirnim `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,
  });
}
```

Za sliko Open Graph posamezne strani glejte [Dinamične slike OG](#dynamic-og-images).

## Slike OpenGraph

### createRootOGImage

Ustvari sliko OG za domačo stran: logotip na sredini črnega ozadja.

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

Ustvari sliko OG za strani z dokumentacijo: logotip zgoraj levo in naslov v beli barvi na črnem ozadju. Argument za pisavo je izbiren; če ga ne podate, se za naslov uporabi sistemska pisava.

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

### Dinamične slike OG

Slike OG za posamezne strani ponudite prek poti. Na to pot ni samodejno usmerjena nobena stran: dodajte jo v metapodatke vsake strani sami, na primer z `openGraph: { images: "/docs/og/getting-started" }` ob poljih iz `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);
}
```

### Pomožne funkcije

| Funkcija | Opis |
|----------|-------------|
| `loadPublicFile(path)` | Naloži datoteko iz `public/` kot podatkovni URL in medpomnilnik; pri datotekah SVG prebere tudi atributa `width` in `height` |
| `loadInterFont(path?)` | Naloži pisavo iz `public/` za slike OG, privzeto `fonts/Inter-Medium.ttf` |
| `ogImageSize` | Standardne mere slik OG `{ width: 1200, height: 630 }` |
| `ogImageContentType` | Tip MIME `"image/png"` |

**Zahtevane datoteke:**
- `public/logo-dark.svg` – logotip za slike OG. Pomožne funkcije OG določijo njegovo velikost na podlagi atributov `width` in `height`, zato morata biti v oznaki `<svg>` navedeni obe vrednosti kot navadni števili.
- `public/fonts/Inter-Medium.ttf` – pisava za naslove. Onedocs je ne vključuje.

## LLMs.txt

Ustvari datoteke LLMs.txt za pomočnike z umetno inteligenco.

### generateLLMsText

Ustvari jedrnato vsebino LLMs.txt. Sprejme vir, ovit z `createLLMsSource` in `{ title, description? }`, ter vrne obljubo.

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

URL-ji strani so zapisani tako, kot jih vrne vir, na primer `/docs/getting-started`, brez domene.

### generateLLMsFullText

Ustvari celoten LLMs.txt s popolno vsebino strani. Sprejme samo oviti vir in vrne obljubo.

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

Telesa strani so vključena samo, kadar je vklopljen `includeProcessedMarkdown` za Fumadocs MDX; glejte [SEO in iskanje](https://onedocs.inline0.dev/sl/docs/seo-search#full-content-version).

### createLLMsSource

Vir Fumadocs (rezultat `loader()` ali `createSource()`) ovije v obliko, ki jo bereta zgornji funkciji: nalagalniki za URL vsake strani, naslov, opis in besedilo.

## SEO

### generateSitemap

Ustvari zemljevid mesta za vašo dokumentacijo. Sprejme en objekt: `baseUrl`, seznam `pages` (običajno iz `meta.json`) in izbirni `docsPath` (privzeto `/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 ?? [],
  });
}
```

Kako vnosi postanejo URL-ji, si oglejte v razdelku [SEO in iskanje](https://onedocs.inline0.dev/sl/docs/seo-search#sitemap).

### generateRobots

Ustvari vsebino robots.txt: dovoli vse, poleg tega pa še vrstice `Host` in `Sitemap`. `sitemapPath` je privzeto nastavljen na `/sitemap.xml`.

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

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

## Prednastavitev CSS

Uvozite prednastavitev CSS v svoj `globals.css`:

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

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

Poti `@source` so relativne glede na `src/app/globals.css`.

Prednastavitev vključuje:
- Tailwind CSS v4 (`tailwindcss` in `@tailwindcss/postcss` namestite sami)
- nevtralno temo Fumadocs
- sloge prednastavitve Fumadocs
- `--font-sans` nastavljen na spremenljivko `--font-inter`, ki jo določa `FontHead`
- funkcije Inter OpenType za osnovno besedilo in naslove
- sloge za postavitev čez celotno višino ter prilagoditve postavitve Onedocs

## Komponente MDX

Izvoz `mdxComponents` razširi privzete komponente Fumadocs UI in doda spodaj navedene komponente MDX:

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

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

**Vključene komponente:**
- Privzete komponente Fumadocs UI: `pre` (bloki kode), `a`, `img`, `h1` do `h6` (naslovi s sidri), `table`, `CodeBlockTab`, `CodeBlockTabs`, `CodeBlockTabsList`, `CodeBlockTabsTrigger`, `CalloutContainer`, `CalloutTitle`, `CalloutDescription`
- `Callout` – okvirji z informacijami, opozorili ali napakami
- `Card`, `Cards` – postavitve kartic
- `Tab`, `Tabs` – vsebina z zavihki
- `Step`, `Steps` – oštevilčeni koraki
- `Accordion`, `Accordions` – zložljivi razdelki
- `File`, `Folder`, `Files` – drevesa datotek
- `ImageZoom` – slike s povečavo
- `TypeTable` – tabele dokumentacije tipov

`InstallBlock` in `CodeBlock` nista vključena; dodajte ju sami, kot je prikazano v razdelku [Komponente](https://onedocs.inline0.dev/sl/docs/components#more-components).

Primere uporabe najdete v razdelku [Komponente](https://onedocs.inline0.dev/sl/docs/components).