# API-Referenz

Vollständige Referenz zu allen Exporten des Pakets `onedocs`.

## Einstiegspunkte

| Import | Beschreibung |
|--------|-------------|
| `onedocs` | Haupteinstieg – Layouts, Komponenten, `mdxComponents`, `defineConfig`, Quell-Hilfsfunktionen |
| `onedocs/components` | Fumadocs UI-Komponenten sowie `InstallBlock`, `CodeBlock`, `Button` und `Logo` |
| `onedocs/config` | Konfigurationshilfen |
| `onedocs/source` | Hilfsfunktionen für Inhaltsquellen |
| `onedocs/metadata` | Metadatengenerierung |
| `onedocs/og` | OpenGraph-Bilderzeugung |
| `onedocs/llms` | Erzeugung von LLMs.txt |
| `onedocs/seo` | Sitemap und robots.txt |
| `onedocs/css/preset.css` | Tailwind CSS-Voreinstellung |

## Layouts

### DocsLayout

Hauptlayout für Dokumentationsseiten. Bietet Seitenleistennavigation, Suche und einen Theme-Umschalter.

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

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

**Props:**
- `config` – Dein `OnedocsConfig`-Objekt
- `pageTree` – Seitenbaum aus deiner Quelle (e.g, `source.pageTree`)
- `children` – Seiteninhalt

### DocsPage

Wrapper für einzelne Dokumentationsseiten. Umschließt das Fumadocs-UI-`DocsPage` und fügt den Inhalt in `DocsBody` ein.

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

**Props:**
- `toc` – Inhaltsverzeichnis aus den Seitendaten
- `children` – MDX-Inhalt
- Alle weiteren Props von Fumadocs UI `DocsPage`, etwa `full`

### DocsBody

Innerer Wrapper für Dokumentationsinhalte. Wird intern von `DocsPage` verwendet.

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

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

### HomePage

Vollständige Landingpage-Komponente mit Hero-Bereich, Features und Footer.

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

**Props:**
- `config` – Dein `OnedocsConfig`-Objekt
- `packageName` – Paketname für den Installationsblock (optional)
- `children` – Inhalt zwischen Features und Footer (optional)

Unter [Startseite](https://onedocs.inline0.dev/de/docs/configuration#homepage) und [Footer](https://onedocs.inline0.dev/de/docs/configuration#footer) erfährst du, was die Konfiguration steuert.

### HomeLayout

Basislayout für die Startseite (intern von `HomePage` verwendet).

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

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

### createBaseOptions

Erstellt anhand deiner Konfiguration die Fumadocs-UI-Layoutoptionen (Navbar-Titel oder Logo, `nav.links` und den GitHub-Link). `DocsLayout` und `HomeLayout` verwenden diese Funktion. Rufe sie selbst auf, wenn du direkt ein Fumadocs-UI-Layout renderst.

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

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

## Komponenten

### InstallBlock

Tabs für Paketmanager mit Installationsbefehlen für npm, yarn, pnpm und bun (`npm i`, `yarn add`, `pnpm add`, `bun add`). Dies ist eine asynchrone Serverkomponente.

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

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

**Props:**
- `packageName` – Der zu installierende Paketname npm
- `title` – Überschrift über den Tabs (optional)
- `description` – Text über den Tabs (optional)
- `children` – Inhalt unter den Tabs (optional)

### Button

Abgerundeter Link im Stil einer primären Schaltfläche. Es gibt einen Stil.

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

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

**Props:**
- `href` – Linkziel
- `children` – Schaltflächentext
- `className` – Zusätzliche Klassen (optional)

### Logo

Rendert ein helles und ein dunkles Bild und zeigt das zum aktuellen Theme passende an. `DocsLayout` und `HomePage` verwenden es für ein `logo` mit heller und dunkler Variante.

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

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

**Props:**
- `light` – Bildpfad für den hellen Modus
- `dark` – Bildpfad für den dunklen Modus
- `alt` – Alternativtext (Standard: `"Logo"`)
- `className` – Klassen für beide Bilder (optional)

### CTASection

Handlungsaufforderungsbereich für die Startseite.

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

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

**Props:**
- `title` – Abschnittsüberschrift
- `description` – Text unter der Überschrift (optional)
- `cta` – Schaltflächenkonfiguration mit `label` und `href`
- `children` – Inhalt unter der Schaltfläche (optional)

### FontHead

Lädt die Inter Variable-Schriftart vor, deklariert ihr `@font-face` und legt sie als Schriftart der Seite fest. Füge die Komponente zum `<head>` deines Root-Layouts hinzu.

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

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

Onedocs enthält die Schriftart nicht. Standardmäßig lädt `FontHead` `/fonts/InterVariable.woff2`. Lege die Datei daher unter `public/fonts/` ab oder übergib mit `fontPath` eine andere URL:

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

### GitHubIcon

GitHub-Symbolkomponente (intern in der Navigation verwendet).

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

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

### CodeBlock

Syntaxhervorgehobener Codeblock, der serverseitig mit Shiki über Fumadocs hervorgehoben wird. Dies ist eine asynchrone Serverkomponente.

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

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

## Konfiguration

### defineConfig

Typsichere Konfigurations-Hilfsfunktion.

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

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

### OnedocsConfig

TypeScript-Typ für die Konfiguration.

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

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

Unter [Konfiguration](https://onedocs.inline0.dev/de/docs/configuration) findest du alle Optionen.

## Quell-Hilfsfunktionen

### loader

Re-Export des `fumadocs-core/source`-Loaders zum Erstellen von Inhaltsquellen.

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

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

### createSource

Hilfsfunktion zum Erstellen einer Inhaltsquelle (Wrapper um loader). Die Basis-URL ist standardmäßig `/docs`.

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

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

In 0.1.27 gibt `createSource` eine nicht typisierte Quelle zurück, sodass TypeScript beim Lesen von `page.data` Fehler wie `Property 'data' does not exist on type 'unknown'` meldet ([#4](https://github.com/inline0/onedocs/issues/4)). Verwende bis zur Behebung `loader` wie oben gezeigt.

## Metadaten

### createMetadata

Erstellt Next.js-Metadaten für dein Root-Layout.

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

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

**Optionen:**
- `baseUrl` – Die Basis-URL deiner Website (optional)
- `additional` – Zusätzliche `Metadata`-Felder, die zuletzt zusammengeführt werden (optional)

**Rückgabe:** Ein Next.js-Objekt `Metadata` mit:
- Titel (`config.title`) und Titelvorlage (`%s | Site Name`)
- Beschreibung
- Favicon aus `config.icon`, falls festgelegt
- Falls `baseUrl` festgelegt ist: `metadataBase`, OpenGraph-Metadaten und eine Twitter-`summary_large_image`-Karte

### createDocsPageMetadata

Erstellt Titel- und Beschreibungsmetadaten für eine Dokumentationsseite. Die Funktion erwartet ein Objekt mit `title` und optional `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,
  });
}
```

Ein Open Graph-Bild pro Seite wird unter [Dynamische OG-Bilder](#dynamic-og-images) beschrieben.

## OpenGraph-Bilder

### createRootOGImage

Erstellt ein OG-Bild für die Startseite: dein Logo mittig auf schwarzem Hintergrund.

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

Erstellt ein OG-Bild für Dokumentationsseiten: das Logo oben links, der Titel weiß auf schwarzem Hintergrund. Das Schriftart-Argument ist optional. Ohne Angabe wird für den Titel die Systemschriftart verwendet.

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

### Dynamische OG-Bilder

Stelle seitenbezogene OG-Bilder über eine Route bereit. Keine Seite verweist automatisch auf diese Route: Füge sie selbst zu den Metadaten jeder Seite hinzu, zum Beispiel mit `openGraph: { images: "/docs/og/getting-started" }` neben den Feldern aus `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);
}
```

### Hilfsfunktionen

| Funktion | Beschreibung |
|----------|-------------|
| `loadPublicFile(path)` | Lädt eine Datei aus `public/` als Daten-URL und Puffer; bei SVGs werden auch die Attribute `width` und `height` ausgelesen |
| `loadInterFont(path?)` | Lädt eine Schriftart aus `public/` für OG-Bilder, standardmäßig `fonts/Inter-Medium.ttf` |
| `ogImageSize` | Standardabmessungen für OG-Bilder `{ width: 1200, height: 630 }` |
| `ogImageContentType` | MIME-Typ `"image/png"` |

**Erforderliche Dateien:**
- `public/logo-dark.svg` – Logo für OG-Bilder. Die OG-Hilfsfunktionen bestimmen seine Größe anhand der Attribute `width` und `height`. Daher müssen beide im `<svg>`-Tag als einfache Zahlen angegeben sein.
- `public/fonts/Inter-Medium.ttf` – Schriftart für Titel. Onedocs enthält sie nicht.

## LLMs.txt

Erstelle LLMs.txt-Dateien für KI-Assistenten.

### generateLLMsText

Erstellt kompakte LLMs.txt-Inhalte. Die Funktion erwartet eine mit `createLLMsSource` und `{ title, description? }` umschlossene Quelle und gibt ein Promise zurück.

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

Seiten-URLs werden so übernommen, wie sie aus der Quelle kommen, zum Beispiel `/docs/getting-started`, ohne Domain.

### generateLLMsFullText

Erstellt vollständiges LLMs.txt mit sämtlichen Seiteninhalten. Die Funktion erwartet nur die umschlossene Quelle und gibt ein Promise zurück.

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

Seiteninhalte werden nur aufgenommen, wenn in Fumadocs MDX die Option `includeProcessedMarkdown` aktiviert ist. Siehe [SEO und Suche](https://onedocs.inline0.dev/de/docs/seo-search#full-content-version).

### createLLMsSource

Umschließt eine Fumadocs-Quelle (Ergebnis von `loader()` oder `createSource()`) in der Form, die die beiden obigen Funktionen erwarten: URL, Titel, Beschreibung und Text-Loader jeder Seite.

## SEO

### generateSitemap

Erstellt eine Sitemap für deine Dokumentation. Die Funktion erwartet ein Objekt: `baseUrl`, die `pages`-Liste (üblicherweise aus `meta.json`) und optional `docsPath` (Standard: `/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 ?? [],
  });
}
```

Unter [SEO und Suche](https://onedocs.inline0.dev/de/docs/seo-search#sitemap) erfährst du, wie Einträge zu URLs werden.

### generateRobots

Erstellt robots.txt-Inhalte: alles erlauben sowie Zeilen für `Host` und `Sitemap`. `sitemapPath` ist standardmäßig `/sitemap.xml`.

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

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

## CSS-Voreinstellung

Importiere die CSS-Voreinstellung in deine `globals.css`:

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

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

Die Pfade in `@source` sind relativ zu `src/app/globals.css`.

Die Voreinstellung enthält:
- Tailwind CSS v4 (installiere `tailwindcss` und `@tailwindcss/postcss` selbst)
- Fumadocs-Neutral-Theme
- Voreingestellte Fumadocs-Stile
- `--font-sans` auf die `--font-inter`-Variable gesetzt, die `FontHead` definiert
- Inter-OpenType-Funktionen für Fließtext und Überschriften
- Stile für Layouts mit voller Höhe und Onedocs-Layoutanpassungen

## MDX-Komponenten

Der `mdxComponents`-Export übernimmt die Standardkomponenten von Fumadocs UI MDX und ergänzt die folgenden Komponenten:

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

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

**Enthaltene Komponenten:**
- Fumadocs-UI-Standards: `pre` (Codeblöcke), `a`, `img`, `h1` bis `h6` (Überschriften mit Ankern), `table`, `CodeBlockTab`, `CodeBlockTabs`, `CodeBlockTabsList`, `CodeBlockTabsTrigger`, `CalloutContainer`, `CalloutTitle`, `CalloutDescription`
- `Callout` – Info-, Warn- und Fehlermeldungen
- `Card`, `Cards` – Kartenlayouts
- `Tab`, `Tabs` – Inhalte mit Tabs
- `Step`, `Steps` – Nummerierte Schritte
- `Accordion`, `Accordions` – Aufklappbare Abschnitte
- `File`, `Folder`, `Files` – Dateibäume
- `ImageZoom` – Zoombare Bilder
- `TypeTable` – Typdokumentationstabellen

`InstallBlock` und `CodeBlock` sind nicht enthalten. Füge sie wie unter [Komponenten](https://onedocs.inline0.dev/de/docs/components#more-components) gezeigt selbst hinzu.

Nutzungsbeispiele findest du unter [Komponenten](https://onedocs.inline0.dev/de/docs/components).