API teatmik

Täielik teatmik kõigi onedocs paketi eksporditavate üksuste kohta.

Sisendpunktid

Paigutused

DocsLayout

Dokumentatsioonilehtede põhipaigutuse ümbris. Pakub külgriba navigeerimist, otsingut ja kujunduse lülitit.

import { DocsLayout } from "onedocs";

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

Rekvisiidid:

• config – teie OnedocsConfig objekt
• pageTree – lähteandmete lehtede puu (nt e.g, source.pageTree)
• children – lehe sisu

DocsPage

Ümbris üksikute dokumentatsioonilehtede jaoks. Ümbritseb Fumadocs UI DocsPage ja paigutab sisu elementi 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>
  );
}

Rekvisiidid:

• toc – lehe andmetest saadud sisukord
• children – MDX sisu
• Kõik muud Fumadocs UI DocsPage rekvisiidid, näiteks full

DocsBody

Dokumentatsiooni sisu sisemine ümbris. Kasutab sisemiselt DocsPage.

import { DocsBody } from "onedocs";

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

HomePage

Terviklik avalehe komponent tunnuslause, funktsioonide ja jalusega.

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

Rekvisiidid:

• config – teie OnedocsConfig objekt
• packageName – paigaldusploki paketi nimi (valikuline)
• children – sisu funktsioonide ja jaluse vahel (valikuline)

Vaadake linke avaleht ja jalus, et näha, mida seadistus juhib.

HomeLayout

Avalehe põhipaigutus (kasutab sisemiselt HomePage).

import { HomeLayout } from "onedocs";

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

createBaseOptions

Koostab teie seadistuse põhjal Fumadocs UI paigutusvalikud (navigeerimisriba pealkiri või logo, nav.links ja link GitHub). DocsLayout ja HomeLayout kasutavad seda; kui renderdate otse paigutuse Fumadocs UI, kutsuge see ise välja.

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

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

Komponendid

InstallBlock

Paketihalduri vahekaardid, kus kuvatakse paigalduskäsud pakettidele npm, yarn, pnpm ja bun (npm i, yarn add, pnpm add, bun add). See on asünkroonne serverikomponent.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Rekvisiidid:

• packageName – installitava npm paketi nimi
• title – vahekaartide kohal olev pealkiri (valikuline)
• description – vahekaartide kohal olev tekst (valikuline)
• children – vahekaartide all olev sisu (valikuline)

Button

Ümar link, mis on kujundatud peamise nupuna. Saadaval on üks stiil.

import { Button } from "onedocs";

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

Rekvisiidid:

• href – lingi sihtkoht
• children – nupu tekst
• className – lisaklassid (valikuline)

Logo

Kuvab heleda ja tumeda pildi ning näitab parajasti valitud kujundusele vastavat pilti. DocsLayout ja HomePage kasutavad seda pildi logo jaoks, millel on heledad ja tumedad variandid.

import { Logo } from "onedocs";

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

Rekvisiidid:

• light – heleda režiimi pildi tee
• dark – tumeda režiimi pildi tee
• alt – alternatiivtekst (vaikimisi: "Logo")
• className – mõlema pildi klassid (valikuline)

CTASection

Avalehe tegevusele kutsuv jaotis.

import { CTASection } from "onedocs";

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

Rekvisiidid:

• title – jaotise pealkiri
• description – pealkirja all olev tekst (valikuline)
• cta – nupu seadistus koos väärtustega label ja href
• children – nupu all olev sisu (valikuline)

FontHead

Laadib eellaadimisega Inter Variable'i fondi, määrab selle @font-face ja seab selle lehe fondiks. Lisage see juurpaigutuse <head>-isse.

import { FontHead } from "onedocs";

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

Onedocs ei sisalda fonti. Vaikimisi laadib FontHead /fonts/InterVariable.woff2, seega paigutage fail asukohta public/fonts/ või andke atribuudiga fontPath ette mõni muu URL:

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

GitHubIcon

GitHub ikoonikomponent (kasutatakse navigeerimises sisemiselt).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Süntaksi esiletõstuga koodiplokk, mille süntaksi esiletõst tehakse serveris Shiki abil Fumadocs kaudu. See on asünkroonne serverikomponent.

import { CodeBlock } from "onedocs";

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

Konfiguratsioon

defineConfig

Tüübikindel seadistuse abifunktsioon.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

Seadistuse tüüp TypeScript jaoks.

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

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

Kõigi valikute kohta vaadake lehte Seadistus.

Lähteandmete utiliidid

loader

Sisuallikate loomiseks mõeldud fumadocs-core/source laaduri taaseksport.

import { loader } from "onedocs/source";

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

createSource

Sisuallika loomise abifunktsioon (laaduri ümbris). Baasi URL vaikeväärtus on /docs.

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

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

0.1.27-s tagastab createSource tüübita allika, mistõttu TypeScript annab page.data lugemisel teada vigadest, näiteks Property 'data' does not exist on type 'unknown' (#4). Kuni see on parandatud, kasutage eespool näidatud viisil loader.

Metaandmed

createMetadata

Genereerib juurpaigutuse Next.js metaandmed.

import { createMetadata } from "onedocs/metadata";

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

Valikud:

• baseUrl – sinu saidi põhi-URL (valikuline)
• additional – täiendavad Metadata väljad, liidetakse viimasena (valikuline)

Tagastab: Next.js Metadata objekti, mis sisaldab:

• Pealkirja (config.title) ja pealkirjamalli (%s | Site Name)
• Kirjeldust
• config.icon pärit lemmikut, kui see on määratud
• Kui baseUrl on määratud: metadataBase, OpenGraphi metaandmeid ja Twitter summary_large_image kaarti

createDocsPageMetadata

Genereerib dokumentatsioonilehe pealkirja ja kirjelduse metaandmed. Võtab ühe objekti, milles on title ja valikuline 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,
  });
}

Lehepõhise Open Graph pildi kohta vaata Dünaamilised OG-pildid.

OpenGraphi pildid

createRootOGImage

Loob avalehele OG-pildi: logo mustal taustal keskel.

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

Loob dokumentatsioonilehtedele OG-pildi: logo vasakus ülanurgas ja pealkiri valgena mustal taustal. Fondiargument on valikuline; ilma selleta kasutatakse pealkirjas süsteemi fonti.

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

Dünaamilised OG-pildid

Lehepõhiste OG-piltide jaoks paku neid marsruudilt. Lehti sellele marsruudile automaatselt ei suunata: lisa see ise iga lehe metaandmetesse, näiteks createDocsPageMetadata väljade kõrvale openGraph: { images: "/docs/og/getting-started" } abil.

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

Abifunktsioonid

Nõutavad failid:

• public/logo-dark.svg – OG-piltide logo. OG-abifunktsioonid määravad selle suuruse atribuutide width ja height põhjal, seega peavad <svg> sildis olema mõlemad tavaliste arvudena.
• public/fonts/Inter-Medium.ttf – pealkirjade font. Onedocs seda kaasa ei paki.

LLMs.txt

Loo tehisintellekti assistentidele LLMs.txt failid.

generateLLMsText

Genereerib lühikese LLMs.txt sisu. Võtab allika, mis on mähitud createLLMsSource ja { title, description? } vahele, ning tagastab lubaduse.

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

Lehe URL-id kirjutatakse nii, nagu need allikas esinevad, näiteks /docs/getting-started, ilma domeenita.

generateLLMsFullText

Genereerib täieliku LLMs.txt kogu lehe sisuga. Võtab ainult mähitud allika ja tagastab lubaduse.

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

Lehe sisu lisatakse ainult siis, kui Fumadocs MDX valik includeProcessedMarkdown on sisse lülitatud; vt SEO ja otsing.

createLLMsSource

Mähistab Fumadocs allika (loader() või createSource() tulemi) kujule, mida kaks ülaltoodud funktsiooni loevad: iga lehe URL, pealkirja, kirjelduse ja teksti laadijad.

SEO

generateSitemap

Genereerib sinu dokumentatsiooni jaoks saidikaardi. Võtab ühe objekti: baseUrl, pages loendi (tavaliselt saadud funktsioonist meta.json) ja valikulise docsPath (vaikimisi /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 ?? [],
  });
}

Vaata jaotisest SEO ja otsing, kuidas kirjetest URL-id moodustuvad.

generateRobots

Genereerib robots.txt sisu: lubab kõik, lisaks Host ja Sitemap read. sitemapPath vaikimisi on /sitemap.xml.

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

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

CSS eelseadistus

Impordi CSS eelseadistus oma globals.css-i:

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

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

@source teed on suhtelised src/app/globals.css suhtes.

Eelseadistus sisaldab:

• Tailwind CSS v4 vaikeväärtusi (paigalda ise tailwindcss ja @tailwindcss/postcss)
• Fumadocs neutraalset kujundust
• Fumadocs eelseadistatud stiile
• --font-sans, mille väärtuseks on FontHead määratud muutuja --font-inter
• Interi OpenType'i funktsioone põhiteksti ja pealkirjade jaoks
• Täiskõrgusega paigutuse stiile ja Onedocs paigutuse kohandusi

MDX komponendid

Eksport mdxComponents laiendab vaikeväärtusi Fumadocs UI komponendiga MDX ning lisab allolevad komponendid:

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Kaasatud komponendid:

• Fumadocs UI vaikeväärtused: pre (koodiplokid), a, img, h1 kuni h6 (ankrutega pealkirjad), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout – teabe-, hoiatus- ja veateated
• Card, Cards – kaardipaigutused
• Tab, Tabs – vahekaartidega sisu
• Step, Steps – nummerdatud sammud
• Accordion, Accordions – ahendatavad jaotised
• File, Folder, Files – failipuud
• ImageZoom – suurendatavad pildid
• TypeTable – tüüpidokumentatsiooni tabelid

InstallBlock ja CodeBlock ei kuulu komplekti; lisa need ise, nagu näidatud jaotises Komponendid.

Kasutusnäiteid vaata jaotisest Komponendid.