API-Referenz

Vollständige Referenz zu allen Exporten des Pakets onedocs.

Einstiegspunkte

Layouts

DocsLayout

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

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.

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.

import { DocsBody } from "onedocs";

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

HomePage

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

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 und Footer erfährst du, was die Konfiguration steuert.

HomeLayout

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

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.

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.

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.

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.

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.

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.

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:

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

GitHubIcon

GitHub-Symbolkomponente (intern in der Navigation verwendet).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

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

import { CodeBlock } from "onedocs";

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

Konfiguration

defineConfig

Typsichere Konfigurations-Hilfsfunktion.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

TypeScript-Typ für die Konfiguration.

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

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

Unter Konfiguration findest du alle Optionen.

Quell-Hilfsfunktionen

loader

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

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.

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). Verwende bis zur Behebung loader wie oben gezeigt.

Metadaten

createMetadata

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

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.

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 beschrieben.

OpenGraph-Bilder

createRootOGImage

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

// 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.

// 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.

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

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.

// 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.

// 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.

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).

// 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 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.

// 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:

@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:

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 gezeigt selbst hinzu.

Nutzungsbeispiele findest du unter Komponenten.