API referencia

Az onedocs csomagból származó összes export teljes referenciája.

Belépési pontok

Elrendezések

DocsLayout

Dokumentációs oldalak fő elrendezését biztosító burkoló. Oldalsávos navigációt, keresést és témaváltót nyújt.

import { DocsLayout } from "onedocs";

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

Tulajdonságok:

• config – Az Ön OnedocsConfig objektuma
• pageTree – Oldalfastruktúra a forrásból (e.g., source.pageTree)
• children – Oldaltartalom

DocsPage

Egyedi dokumentációs oldalak burkolója. Körbeveszi a Fumadocs UI DocsPage elemet, és a tartalmat DocsBody-be helyezi.

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

Tulajdonságok:

• toc – Tartalomjegyzék az oldal adataiból
• children – MDX tartalom
• A Fumadocs UI DocsPage bármely más tulajdonsága, például a full

DocsBody

A dokumentáció tartalmának belső törzselemeit burkolja. Belső használatra a DocsPage használja.

import { DocsBody } from "onedocs";

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

HomePage

Teljes kezdőoldal-komponens nyitó résszel, funkciókkal és lábléccel.

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

Tulajdonságok:

• config – Az Ön OnedocsConfig objektuma
• packageName – Csomagnév a telepítési blokkhoz (nem kötelező)
• children – Tartalom a funkciók és a lábléc között (nem kötelező)

Nézze meg a kezdőlap és a lábléc részt arról, hogy mit szabályoz a konfiguráció.

HomeLayout

A kezdőoldal alapszintű elrendezése (belső használatra a HomePage használja).

import { HomeLayout } from "onedocs";

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

createBaseOptions

A konfigurációból állítja össze a Fumadocs UI elrendezési beállításait (navigációs sáv címe vagy logója, nav.links és az GitHub hivatkozás). Ezt használja a DocsLayout és a HomeLayout; hívja meg közvetlenül, ha önállóan jelenít meg egy Fumadocs UI elrendezést.

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

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

Komponensek

InstallBlock

Csomagkezelő-fülek, amelyek a npm, yarn, pnpm és bun telepítési parancsait jelenítik meg (npm i, yarn add, pnpm add, bun add). Aszinkron szerverkomponens.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Tulajdonságok:

• packageName – A telepítendő npm csomag neve
• title – A fülek feletti címsor (nem kötelező)
• description – A fülek feletti szöveg (nem kötelező)
• children – A fülek alatti tartalom (nem kötelező)

Button

Elsődleges gombként stílusozott, lekerekített hivatkozás. Egyetlen stílusváltozata van.

import { Button } from "onedocs";

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

Tulajdonságok:

• href – Hivatkozás célja
• children – Gombfelirat
• className – További osztályok (nem kötelező)

Logo

Megjelenít egy világos és egy sötét képet, és az aktuális témának megfelelőt mutatja. A DocsLayout és a HomePage használja világos és sötét változattal rendelkező logo esetén.

import { Logo } from "onedocs";

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

Tulajdonságok:

• light – A világos mód képének elérési útja
• dark – A sötét mód képének elérési útja
• alt – Helyettesítő szöveg (alapértelmezett: "Logo")
• className – Mindkét kép osztályai (nem kötelező)

CTASection

Cselekvésre ösztönző szakasz a kezdőoldalon.

import { CTASection } from "onedocs";

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

Tulajdonságok:

• title – Szakaszcím
• description – A cím alatti szöveg (nem kötelező)
• cta – Gombkonfiguráció label és href mezővel
• children – Tartalom a gomb alatt (nem kötelező)

FontHead

Előtölti az Inter Variable betűtípust, megadja a @font-face értékét, és beállítja az oldal betűtípusaként. Adja hozzá a gyökér-elrendezés <head> eleméhez.

import { FontHead } from "onedocs";

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

A Onedocs nem tartalmazza a betűtípust. Alapértelmezés szerint a FontHead tölti be a /fonts/InterVariable.woff2 elemet, ezért helyezze a fájlt a public/fonts/ helyre, vagy adjon át egy másik URL értéket a következővel: fontPath:

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

GitHubIcon

GitHub ikonkomponens (belső használatra a navigációban).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Szintaxiskiemelt kódblokk, amelyet a szerver emel ki a Shiki és a Fumadocs segítségével. Aszinkron szerverkomponens.

import { CodeBlock } from "onedocs";

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

Konfiguráció

defineConfig

Típusbiztos konfigurációs segédfüggvény.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

A konfiguráció TypeScript típusa.

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

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

Az összes beállítást a Konfiguráció oldalon találja.

Forrássegédek

loader

A tartalomforrások létrehozásához használt fumadocs-core/source betöltő újraexportja.

import { loader } from "onedocs/source";

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

createSource

Tartalomforrás létrehozására szolgáló segédfüggvény (a betöltő burkolója). Az alapértelmezett URL értéke /docs.

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

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

A 0.1.27 createSource környezetben az eredmény típus nélküli forrás, ezért a TypeScript olyan hibákat jelez, mint a Property 'data' does not exist on type 'unknown', amikor a page.data értéket olvassa (#4). A javításig használja a fent bemutatott loader megoldást.

Metaadatok

createMetadata

Next.js metaadatokat generál a gyökér-elrendezéshez.

import { createMetadata } from "onedocs/metadata";

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

Beállítások:

• baseUrl – A webhely alap-URL értéke (nem kötelező)
• additional – További Metadata mezők, utolsóként egyesítve (nem kötelező)

Visszatérési érték: Next.js Metadata objektum, amely a következőket tartalmazza:

• Cím (config.title) és címmező-sablon (%s | Site Name)
• Leírás
• A favicon forrása config.icon, ha be van állítva
• Ha baseUrl be van állítva: metadataBase, OpenGraph-metaadatok és egy Twitter summary_large_image kártya

createDocsPageMetadata

Metaadatként generálja a cím és a leírás értékét egy dokumentációs oldalhoz. Egyetlen objektumot fogad title mezővel és opcionális description mezővel.

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

Oldalankénti Open Graph-képhez lásd a Dinamikus OG-képek oldalt.

OpenGraph-képek

createRootOGImage

Kezdőoldali OG-képet készít: a logó fekete háttér közepén jelenik meg.

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

Dokumentációs oldalakhoz készít OG-képet: a logó bal felül, a cím pedig fehérrel, fekete háttéren jelenik meg. A betűtípus argumentum nem kötelező; ha nincs megadva, a cím a rendszer betűtípusát használja.

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

Dinamikus OG-képek

Oldalankénti OG-képekhez szolgálja ki őket egy útvonalról. A rendszer nem irányítja automatikusan az oldalakat erre az útvonalra: adja meg azt minden oldal metaadataiban, például a createDocsPageMetadata mezőiből származó mezők mellé a openGraph: { images: "/docs/og/getting-started" } értéket.

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

Segédfüggvények

Szükséges fájlok:

• public/logo-dark.svg – Logó az OG-képekhez. Az OG-segédfüggvények az width és height attribútumok alapján méretezik, ezért a <svg> címkének mindkettőt egyszerű számként kell megadnia.
• public/fonts/Inter-Medium.ttf – Betűtípus a címekhez. A Onedocs nem tartalmazza.

LLMs.txt

LLMs.txt fájlokat generál AI-asszisztensek számára.

generateLLMsText

Tömör LLMs.txt-tartalmat generál. A createLLMsSource és { title, description? } burkolókkal ellátott forrást fogad, és egy ígéretet ad vissza.

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

Az oldal-URL-ek a forrásban szereplő alakjukban jelennek meg, például /docs/getting-started, tartománynév nélkül.

generateLLMsFullText

Teljes LLMs.txt-tartalmat generál, az oldalak teljes szövegével. Csak a burkolóval ellátott forrást fogadja, és egy ígéretet ad vissza.

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

Az oldalak törzsszövege csak akkor kerül bele, ha a Fumadocs MDX includeProcessedMarkdown beállítása be van kapcsolva; lásd: SEO és keresés.

createLLMsSource

Fumadocs forrást (loader() vagy createSource() eredményt) a fenti két függvény által olvasható formára alakít: minden oldalhoz URL, cím, leírás és szövegbetöltők tartoznak.

SEO

generateSitemap

Webhelytérképet generál a dokumentációhoz. Egy objektumot fogad: baseUrl, a pages listát (általában a meta.json forrásból), valamint az opcionális docsPath értéket (alapértelmezés: /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 ?? [],
  });
}

A bejegyzések URL-ekké alakításáról lásd a SEO és keresés oldalt.

generateRobots

robots.txt-tartalmat generál: mindent engedélyez, továbbá hozzáadja a Host és Sitemap sorokat. A sitemapPath alapértelmezése /sitemap.xml.

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

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

CSS-előbeállítás

Importálja a CSS-előbeállítást a globals.css fájlba:

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

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

A @source útvonalai a src/app/globals.css elemhez képest relatívak.

Az előbeállítás a következőket tartalmazza:

• Tailwind CSS v4 (az tailwindcss és az @tailwindcss/postcss telepítéséről Önnek kell gondoskodnia)
• Fumadocs semleges téma
• Fumadocs előbeállítási stílusok
• --font-sans értéke az FontHead által definiált --font-inter változó
• Inter OpenType-funkciók törzsszöveghez és címsorokhoz
• Teljes magasságú elrendezési stílusok és az Onedocs elrendezési finomításai

MDX-komponensek

A mdxComponents export kiterjeszti a Fumadocs UI alapértelmezett MDX komponenseit, és hozzáadja az alábbiakat:

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Tartalmazott komponensek:

• Fumadocs UI alapértelmezései: pre (kódblokkok), a, img, h1–h6 (horgonyhivatkozásos címsorok), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout – Tájékoztató/figyelmeztető/hibaüzenet-dobozok
• Card, Cards – Kártyaelrendezések
• Tab, Tabs – Füles tartalom
• Step, Steps – Számozott lépések
• Accordion, Accordions – Összecsukható szakaszok
• File, Folder, Files – Fastruktúrák
• ImageZoom – Nagyítható képek
• TypeTable – Típustáblázatok dokumentáláshoz

A InstallBlock és a CodeBlock nem része a csomagnak; adja hozzá őket az Komponensek oldalon bemutatott módon.

Használati példákért lásd a Komponensek oldalt.