Referencia API

Kompletná referencia všetkých exportov z balíka onedocs.

Vstupné body

Rozloženia

DocsLayout

Hlavný obal rozloženia stránok dokumentácie. Poskytuje navigáciu v bočnom paneli, vyhľadávanie a prepínanie témy.

import { DocsLayout } from "onedocs";

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

Vlastnosti:

• config – váš objekt OnedocsConfig
• pageTree – strom stránok z vášho zdroja (napr. e.g, source.pageTree)
• children – obsah stránky

DocsPage

Obal pre jednotlivé stránky dokumentácie. Obalí Fumadocs UI DocsPage a vloží obsah do DocsBody.

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

Vlastnosti:

• toc – obsah z údajov stránky
• children – obsah MDX
• Akákoľvek ďalšia vlastnosť Fumadocs UI DocsPage, napríklad full

DocsBody

Vnútorný obal obsahu dokumentácie. Používa ho interne DocsPage.

import { DocsBody } from "onedocs";

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

HomePage

Kompletný komponent úvodnej stránky s hlavnou sekciou, funkciami a pätou.

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

Vlastnosti:

• config – váš objekt OnedocsConfig
• packageName – názov balíka pre blok inštalácie (voliteľné)
• children – obsah medzi funkciami a pätou (voliteľné)

Pozrite si domovskú stránku a pätu, kde nájdete informácie o tom, čo konfigurácia ovláda.

HomeLayout

Základné rozloženie domovskej stránky (interne ho používa HomePage).

import { HomeLayout } from "onedocs";

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

createBaseOptions

Vytvára možnosti rozloženia Fumadocs UI (názov alebo logo navigačného panela, nav.links a odkaz GitHub) z vašej konfigurácie. Používajú ho DocsLayout a HomeLayout; zavolajte ho sami, keď vykresľujete rozloženie Fumadocs UI priamo.

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

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

Komponenty

InstallBlock

Karty správcu balíkov zobrazujúce príkazy na inštaláciu pre npm, yarn, pnpm a bun (npm i, yarn add, pnpm add, bun add). Ide o asynchrónny serverový komponent.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Vlastnosti:

• packageName – názov balíka npm na inštaláciu
• title – nadpis nad kartami (voliteľné)
• description – text nad kartami (voliteľné)
• children – obsah pod kartami (voliteľné)

Button

Zaoblený odkaz so štýlom primárneho tlačidla. Má jeden štýl.

import { Button } from "onedocs";

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

Vlastnosti:

• href – cieľ odkazu
• children – text tlačidla
• className – ďalšie triedy (voliteľné)

Logo

Vykreslí svetlý aj tmavý obrázok a zobrazí ten, ktorý zodpovedá aktuálnej téme. DocsLayout a HomePage ho používajú pre logo so svetlými a tmavými variantmi.

import { Logo } from "onedocs";

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

Vlastnosti:

• light – cesta k obrázku pre svetlý režim
• dark – cesta k obrázku pre tmavý režim
• alt – alternatívny text (predvolené: "Logo")
• className – triedy pre oba obrázky (voliteľné)

CTASection

Sekcia výzvy na akciu pre domovskú stránku.

import { CTASection } from "onedocs";

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

Vlastnosti:

• title – nadpis sekcie
• description – text pod nadpisom (voliteľné)
• cta – konfigurácia tlačidla s label a href
• children – obsah pod tlačidlom (voliteľné)

FontHead

Prednačíta variabilné písmo Inter, deklaruje jeho @font-face a nastaví ho ako písmo stránky. Pridajte ho do <head> koreňového rozloženia.

import { FontHead } from "onedocs";

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

Onedocs nedodáva písmo. Predvolene FontHead načítava /fonts/InterVariable.woff2, preto súbor umiestnite do public/fonts/ alebo odovzdajte iné URL s fontPath:

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

GitHubIcon

Ikonový komponent GitHub (interne používaný v navigácii).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Blok kódu so zvýraznenou syntaxou, ktorú na serveri zvýrazňuje Shiki prostredníctvom Fumadocs. Ide o asynchrónny serverový komponent.

import { CodeBlock } from "onedocs";

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

Konfigurácia

defineConfig

Pomocná funkcia pre typovo bezpečnú konfiguráciu.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

Typ TypeScript pre konfiguráciu.

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

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

Všetky možnosti nájdete v časti Konfigurácia.

Pomocné nástroje zdroja

loader

Opätovne exportovaný načítavač fumadocs-core/source na vytváranie zdrojov obsahu.

import { loader } from "onedocs/source";

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

createSource

Pomocná funkcia na vytvorenie zdroja obsahu (obal okolo načítavača). Základné URL má predvolenú hodnotu /docs.

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 vracia netypovaný zdroj, takže TypeScript hlási chyby, napríklad Property 'data' does not exist on type 'unknown', keď čítate page.data (#4). Kým sa to neopraví, použite loader podľa príkladu vyššie.

Metadáta

createMetadata

Generuje metadáta Next.js pre koreňové rozloženie.

import { createMetadata } from "onedocs/metadata";

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

Možnosti:

• baseUrl – základná URL vašej stránky (voliteľné)
• additional – ďalšie polia Metadata, zlúčené ako posledné (voliteľné)

Vráti: objekt Next.js Metadata s týmito položkami:

• Názov (config.title) a šablóna názvu (%s | Site Name)
• Opis
• Ikona stránky z config.icon, ak je nastavená
• Ak je nastavené baseUrl: metadataBase, metadáta OpenGraph a karta Twitter summary_large_image

createDocsPageMetadata

Generuje metadáta názvu a opisu pre stránku dokumentácie. Prijíma jeden objekt s title a voliteľným 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,
  });
}

Obrázok Open Graph pre konkrétnu stránku nájdete v časti Dynamické obrázky OG.

Obrázky OpenGraph

createRootOGImage

Vytvorí obrázok OG pre domovskú stránku: vaše logo vycentrované na čiernom pozadí.

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

Vytvorí obrázok OG pre stránky dokumentácie: logo vľavo hore a názov bielou farbou na čiernom pozadí. Argument písma je voliteľný; ak ho vynecháte, názov použije systémové písmo.

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

Dynamické obrázky OG

Ak chcete obrázky OG pre jednotlivé stránky, poskytujte ich cez trasu. Stránky na túto trasu nič automaticky neodkazuje: pridajte ju sami do metadát každej stránky, napríklad pomocou openGraph: { images: "/docs/og/getting-started" } vedľa polí z 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);
}

Pomocné funkcie

Požadované súbory:

• public/logo-dark.svg – logo pre obrázky OG. Pomocné funkcie OG určia jeho veľkosť podľa atribútov width a height, preto značka <svg> musí obsahovať obe hodnoty ako obyčajné čísla.
• public/fonts/Inter-Medium.ttf – písmo pre názvy. Onedocs ho nedodáva.

LLMs.txt

Generuje súbory LLMs.txt pre asistentov umelej inteligencie.

generateLLMsText

Generuje stručný obsah LLMs.txt. Prijíma zdroj obalený pomocou createLLMsSource a { title, description? } a vracia prísľub.

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

Adresy URL stránok sa zapisujú tak, ako pochádzajú zo zdroja, napríklad /docs/getting-started, bez domény.

generateLLMsFullText

Generuje úplný LLMs.txt s kompletným obsahom stránky. Prijíma iba obalený zdroj a vracia prísľub.

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

Texty stránok sa zahrnú iba vtedy, keď je zapnutá možnosť includeProcessedMarkdown v Fumadocs MDX; pozrite si SEO a vyhľadávanie.

createLLMsSource

Obalí zdroj Fumadocs (výsledok loader() alebo createSource()) do tvaru, ktorý čítajú dve funkcie vyššie: URL každej stránky, načítavače názvu, opisu a textu.

SEO

generateSitemap

Generuje mapu webu pre vašu dokumentáciu. Prijíma jeden objekt: baseUrl, zoznam pages (zvyčajne z meta.json) a voliteľné docsPath (predvolené /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 ?? [],
  });
}

Informácie o tom, ako sa položky menia na adresy URL, nájdete v časti SEO a vyhľadávanie.

generateRobots

Generuje obsah robots.txt: povoľuje všetko a pridáva riadky Host a Sitemap. Predvolená hodnota sitemapPath je /sitemap.xml.

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

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

Predvoľba CSS

Importujte predvoľbu CSS do svojho globals.css:

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

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

Cesty @source sú relatívne vzhľadom na src/app/globals.css.

Predvoľba obsahuje:

• Tailwind CSS v4 (nainštalujte si sami tailwindcss a @tailwindcss/postcss)
• Neutrálnu tému Fumadocs
• Štýly predvoľby Fumadocs
• --font-sans nastavené na premennú --font-inter, ktorú definuje FontHead
• Funkcie písma Inter OpenType pre základný text a nadpisy
• Štýly rozloženia na celú výšku a úpravy rozloženia Onedocs

Komponenty MDX

Export mdxComponents rozširuje predvolené komponenty Fumadocs UI MDX a pridáva nižšie uvedené komponenty:

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Zahrnuté komponenty:

• Predvolené komponenty Fumadocs UI: pre (bloky kódu), a, img, h1 až h6 (nadpisy s kotvami), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout – informačné, varovné a chybové upozornenia
• Card, Cards – rozloženia kariet
• Tab, Tabs – obsah s kartami
• Step, Steps – očíslované kroky
• Accordion, Accordions – rozbaľovacie sekcie
• File, Folder, Files – stromové zobrazenia súborov
• ImageZoom – obrázky s priblížením
• TypeTable – tabuľky typov v dokumentácii

InstallBlock a CodeBlock nie sú zahrnuté; pridajte ich sami podľa pokynov v časti Komponenty.

Príklady použitia nájdete v časti Komponenty.