API žinynas

Visų eksportų iš onedocs paketo žinynas.

Pradiniai taškai

Maketai

DocsLayout

Pagrindinis dokumentacijos puslapių išdėstymo apvalkalas. Jame pateikiama šoninė navigacija, paieška ir temos perjungimas.

import { DocsLayout } from "onedocs";

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

Savybės:

• config – jūsų OnedocsConfig objektas
• pageTree – puslapių medis iš jūsų šaltinio (e.g, source.pageTree)
• children – puslapio turinys

DocsPage

Atskiriems dokumentacijos puslapiams skirtas apvalkalas. Jis apgaubia Fumadocs UI DocsPage ir įdeda turinį į 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>
  );
}

Savybės:

• toc – turinio lentelė iš puslapio duomenų
• children – MDX turinys
• Bet kuri kita Fumadocs UI DocsPage savybė, pavyzdžiui, full

DocsBody

Vidinis dokumentacijos turinio apvalkalas. Naudojamas viduje DocsPage.

import { DocsBody } from "onedocs";

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

HomePage

Viso pradžios puslapio komponentas su pagrindine sritimi, funkcijomis ir porašte.

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

Savybės:

• config – jūsų OnedocsConfig objektas
• packageName – paketo pavadinimas diegimo bloke (nebūtina)
• children – turinys tarp funkcijų ir poraštės (nebūtina)

Žr. pagrindinį puslapį ir poraštę, kad sužinotumėte, ką valdo konfigūracija.

HomeLayout

Pagrindinis pradžios puslapio išdėstymas (viduje naudojamas HomePage).

import { HomeLayout } from "onedocs";

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

createBaseOptions

Iš jūsų konfigūracijos sudaro Fumadocs UI išdėstymo parinktis (navigacijos juostos pavadinimą arba logotipą, nav.links ir GitHub nuorodą). Jį naudoja DocsLayout ir HomeLayout; iškvieskite jį patys, kai tiesiogiai atvaizduojate Fumadocs UI išdėstymą.

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

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

Komponentai

InstallBlock

Paketų tvarkyklių skirtukai su npm, yarn, pnpm ir bun diegimo komandomis (npm i, yarn add, pnpm add, bun add). Tai asinchroninis serverio komponentas.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Savybės:

• packageName – diegiamo npm paketo pavadinimas
• title – antraštė virš skirtukų (nebūtina)
• description – tekstas virš skirtukų (nebūtina)
• children – turinys po skirtukais (nebūtina)

Button

Suapvalinta nuoroda, stilizuota kaip pagrindinis mygtukas. Yra tik vienas stilius.

import { Button } from "onedocs";

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

Savybės:

• href – nuorodos paskirties vieta
• children – mygtuko tekstas
• className – papildomos klasės (nebūtina)

Logo

Atvaizduoja šviesų ir tamsų vaizdą, o tada parodo tą, kuris atitinka dabartinę temą. DocsLayout ir HomePage jį naudoja logo su šviesiu ir tamsiu variantais.

import { Logo } from "onedocs";

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

Savybės:

• light – vaizdo kelias šviesiajai temai
• dark – vaizdo kelias tamsiajai temai
• alt – alternatyvusis tekstas (numatytoji reikšmė: "Logo")
• className – abiejų vaizdų klasės (nebūtina)

CTASection

Pradžios puslapio raginimo veikti skiltis.

import { CTASection } from "onedocs";

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

Savybės:

• title – skilties antraštė
• description – tekstas po antrašte (nebūtina)
• cta – mygtuko konfigūracija su label ir href
• children – turinys po mygtuku (nebūtina)

FontHead

Iš anksto įkelia Inter Variable šriftą, deklaruoja jo @font-face ir nustato jį kaip puslapio šriftą. Pridėkite prie šakninio išdėstymo <head>.

import { FontHead } from "onedocs";

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

Onedocs šrifto netiekia. Pagal numatytuosius nustatymus FontHead įkelia /fonts/InterVariable.woff2, todėl įdėkite failą į public/fonts/ arba perduokite kitą URL su fontPath:

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

GitHubIcon

GitHub piktogramos komponentas (viduje naudojamas navigacijoje).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Sintaksę paryškinantis kodo blokas, kurį serveryje paryškina Shiki per Fumadocs. Tai asinchroninis serverio komponentas.

import { CodeBlock } from "onedocs";

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

Konfigūracija

defineConfig

Tipų saugi konfigūracijos pagalbinė funkcija.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

TypeScript konfigūracijos tipas.

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

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

Visas parinktis rasite skiltyje Konfigūracija.

Šaltinio įrankiai

loader

Pakartotinis fumadocs-core/source krautuvo eksportas turinio šaltiniams kurti.

import { loader } from "onedocs/source";

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

createSource

Pagalbinė funkcija turinio šaltiniui kurti (krautuvo apvalkalas). Pagrindinė URL reikšmė pagal numatytuosius nustatymus yra /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 createSource grąžina netipuotą šaltinį, todėl TypeScript praneša apie tokias klaidas kaip Property 'data' does not exist on type 'unknown', kai skaitote page.data (#4). Kol tai bus pataisyta, naudokite aukščiau parodytą loader.

Metaduomenys

createMetadata

Generuoja Next.js metaduomenis jūsų šakniniam išdėstymui.

import { createMetadata } from "onedocs/metadata";

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

Parinktys:

• baseUrl – pagrindinis jūsų svetainės URL (nebūtina)
• additional – papildomi Metadata laukai, sujungiami paskiausiai (nebūtina)

Grąžina: Next.js Metadata objektą su:

• Pavadinimu (config.title) ir pavadinimo šablonu (%s | Site Name)
• Aprašu
• Piktograma iš config.icon, jei nustatyta
• Jei nustatyta baseUrl: metadataBase, OpenGraph metaduomenimis ir Twitter summary_large_image kortele

createDocsPageMetadata

Generuoja dokumentacijos puslapio pavadinimo ir aprašo metaduomenis. Priima vieną objektą su title ir pasirinktiniu 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,
  });
}

Puslapiui skirtą Open Graph vaizdą rasite skiltyje Dinaminiai OG vaizdai.

OpenGraph vaizdai

createRootOGImage

Sukuria pradžios puslapio OG vaizdą: logotipas juodo fono centre.

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

Sukuria dokumentacijos puslapių OG vaizdą: logotipas viršuje kairėje, pavadinimas baltai juodame fone. Šrifto argumentas pasirinktinis; jei jo nėra, pavadinimui naudojamas sistemos šriftas.

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

Dinaminiai OG vaizdai

Puslapių OG vaizdus pateikite iš maršruto. Puslapiai automatiškai nebus susieti su šiuo maršrutu: patys įtraukite jį į kiekvieno puslapio metaduomenis, pavyzdžiui, su openGraph: { images: "/docs/og/getting-started" } greta laukų iš 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);
}

Pagalbinės funkcijos

Būtini failai:

• public/logo-dark.svg – OG vaizdų logotipas. OG pagalbinės funkcijos nustato jo dydį pagal atributus width ir height, todėl <svg> žymoje abu turi būti paprasti skaičiai.
• public/fonts/Inter-Medium.ttf – pavadinimų šriftas. Onedocs jo netiekia.

LLMs.txt

Generuokite LLMs.txt failus DI asistentams.

generateLLMsText

Generuoja glaustą LLMs.txt turinį. Priima šaltinį, apgaubtą createLLMsSource ir { title, description? }, ir grąžina pažadą.

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

Puslapių URL įrašomi taip, kaip pateikiami šaltinyje, pavyzdžiui, /docs/getting-started, be domeno.

generateLLMsFullText

Generuoja visą LLMs.txt su visu puslapio turiniu. Priima tik apgaubtą šaltinį ir grąžina pažadą.

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

Puslapių turinys įtraukiamas tik tada, kai įjungta Fumadocs MDX parinktis includeProcessedMarkdown; žr. SEO ir paieška.

createLLMsSource

Apgaubia Fumadocs šaltinį (loader() arba createSource() rezultatą) forma, kurią nuskaito dvi pirmiau nurodytos funkcijos: kiekvieno puslapio URL, pavadinimą, aprašą ir teksto krautuvus.

SEO

generateSitemap

Generuoja dokumentacijos svetainės svetainės žemėlapį. Priima vieną objektą: baseUrl, pages sąrašą (paprastai iš meta.json) ir pasirinktinį docsPath (numatytoji reikšmė /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 ?? [],
  });
}

Kaip įrašai virsta URL, sužinosite skiltyje SEO ir paieška.

generateRobots

Generuoja robots.txt turinį: leidžia viską ir prideda Host bei Sitemap eilutes. sitemapPath numatytoji reikšmė yra /sitemap.xml.

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

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

CSS išankstinis nustatymas

Importuokite CSS išankstinį nustatymą į savo globals.css:

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

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

@source keliai nurodomi src/app/globals.css atžvilgiu.

Į išankstinį nustatymą įtraukta:

• Tailwind CSS v4 (tailwindcss ir @tailwindcss/postcss įsidiekite patys)
• Fumadocs neutrali tema
• Fumadocs išankstinio nustatymo stiliai
• --font-sans nustatytas į FontHead apibrėžiamą kintamąjį --font-inter
• Inter OpenType funkcijos pagrindiniam tekstui ir antraštėms
• Viso aukščio išdėstymo stiliai ir Onedocs išdėstymo koregavimai

MDX komponentai

mdxComponents eksportas išskleidžia numatytuosius Fumadocs UI komponentus ir prideda toliau pateiktus komponentus: MDX

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Įtraukti komponentai:

• Fumadocs UI numatytieji komponentai: pre (kodo blokai), a, img, h1–h6 (antraštės su inkarais), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout – informaciniai, įspėjamieji ir klaidų pranešimai
• Card, Cards – kortelių išdėstymai
• Tab, Tabs – turinys su skirtukais
• Step, Steps – sunumeruoti veiksmai
• Accordion, Accordions – sutraukiamos skiltys
• File, Folder, Files – failų medžiai
• ImageZoom – priartinami vaizdai
• TypeTable – tipų dokumentacijos lentelės

InstallBlock ir CodeBlock neįtraukti; pridėkite juos patys, kaip parodyta skiltyje Komponentai.

Naudojimo pavyzdžių rasite skiltyje Komponentai.