API atsauce

Pilnīga atsauce par visiem eksportiem no onedocs pakotnes.

Ieejas punkti

Izkārtojumi

DocsLayout

Galvenais izkārtojuma konteiners dokumentācijas lapām. Nodrošina sānjoslas navigāciju, meklēšanu un motīva pārslēgšanu.

import { DocsLayout } from "onedocs";

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

Rekvizīti:

• config — jūsu OnedocsConfig objekts
• pageTree — lapu koks no jūsu avota (piem., e.g., source.pageTree)
• children — lapas saturs

DocsPage

Konteiners atsevišķām dokumentācijas lapām. Ietver Fumadocs UI DocsPage un ievieto saturu 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>
  );
}

Rekvizīti:

• toc — satura rādītājs no lapas datiem
• children — MDX saturs
• Jebkura cita Fumadocs UI DocsPage rekvizīta vērtība, piemēram, full

DocsBody

Iekšējais satura konteiners dokumentācijai. To iekšēji izmanto DocsPage.

import { DocsBody } from "onedocs";

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

HomePage

Pilna sākumlapas komponente ar galveno sadaļu, funkcijām un kājeni.

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

Rekvizīti:

• config — jūsu OnedocsConfig objekts
• packageName — pakotnes nosaukums instalēšanas blokam (neobligāts)
• children — saturs starp funkcijām un kājeni (neobligāts)

Skatiet sākumlapu un kājeni, lai uzzinātu, ko kontrolē konfigurācija.

HomeLayout

Sākumlapas pamata izkārtojums (iekšēji izmantots komponentē HomePage).

import { HomeLayout } from "onedocs";

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

createBaseOptions

No konfigurācijas izveido Fumadocs UI izkārtojuma opcijas (navigācijas joslas nosaukumu vai logotipu, nav.links un GitHub saiti). To izmanto DocsLayout un HomeLayout; izsauciet to paši, ja tieši attēlojat Fumadocs UI izkārtojumu.

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

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

Komponenti

InstallBlock

Pakotņu pārvaldnieku cilnes, kurās redzamas instalēšanas komandas npm, yarn, pnpm un bun (npm i, yarn add, pnpm add, bun add). Tā ir asinhrona servera komponente.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Rekvizīti:

• packageName — instalējamās pakotnes npm nosaukums
• title — virsraksts virs cilnēm (neobligāts)
• description — teksts virs cilnēm (neobligāts)
• children — saturs zem cilnēm (neobligāts)

Button

Noapaļota saite, kas noformēta kā primārā poga. Ir pieejams viens stils.

import { Button } from "onedocs";

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

Rekvizīti:

• href — saites galamērķis
• children — pogas teksts
• className — papildu klases (neobligātas)

Logo

Attēlo gaišu un tumšu attēlu un parāda to, kas atbilst pašreizējam motīvam. DocsLayout un HomePage to izmanto logo ar gaišo un tumšo variantu attēlošanai.

import { Logo } from "onedocs";

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

Rekvizīti:

• light — attēla ceļš gaišajam režīmam
• dark — attēla ceļš tumšajam režīmam
• alt — alternatīvais teksts (pēc noklusējuma: "Logo")
• className — klases abiem attēliem (neobligātas)

CTASection

Sākumlapas aicinājuma uz darbību sadaļa.

import { CTASection } from "onedocs";

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

Rekvizīti:

• title — sadaļas virsraksts
• description — teksts zem virsraksta (neobligāts)
• cta — pogas konfigurācija ar label un href
• children — saturs zem pogas (neobligāts)

FontHead

Iepriekšielādē Inter Variable fontu, deklarē tā @font-face un iestata to kā lapas fontu. Pievienojiet to saknes izkārtojuma <head>.

import { FontHead } from "onedocs";

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

Onedocs neiekļauj fonta failu. Pēc noklusējuma FontHead ielādē /fonts/InterVariable.woff2, tāpēc ievietojiet failu mapē public/fonts/ vai norādiet citu URL ar fontPath:

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

GitHubIcon

GitHub ikonas komponente (iekšēji izmantota navigācijā).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Sintakses izcelts koda bloks, ko serverī izceļ ar Shiki, izmantojot Fumadocs. Tā ir asinhrona servera komponente.

import { CodeBlock } from "onedocs";

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

Konfigurācija

defineConfig

Tipdrošs konfigurācijas palīgrīks.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

TypeScript konfigurācijas tips.

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

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

Visas opcijas skatiet sadaļā Konfigurācija.

Avota utilītas

loader

fumadocs-core/source ielādētāja atkārtots eksports satura avotu izveidei.

import { loader } from "onedocs/source";

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

createSource

Palīgfunkcija satura avota izveidei (apvalks ap ielādētāju). Pamata URL pēc noklusējuma ir /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 gadījumā createSource atgriež netipizētu avotu, tāpēc TypeScript uzrāda kļūdas, piemēram, Property 'data' does not exist on type 'unknown', lasot page.data (#4). Kamēr tas nav novērsts, izmantojiet loader, kā parādīts iepriekš.

Metadati

createMetadata

Ģenerē Next.js metadatus saknes izkārtojumam.

import { createMetadata } from "onedocs/metadata";

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

Opcijas:

• baseUrl — jūsu vietnes pamata URL (neobligāts)
• additional — papildu Metadata lauki, kas tiek pievienoti pēdējie (neobligāti)

Atgriež: Next.js Metadata objektu ar:

• nosaukumu (config.title) un nosaukuma veidni (%s | Site Name)
• aprakstu
• favicon no config.icon, ja tas ir iestatīts
• ja ir iestatīts baseUrl: metadataBase, OpenGraph metadatus un Twitter summary_large_image kartīti

createDocsPageMetadata

Ģenerē dokumentācijas lapas nosaukuma un apraksta metadatus. Pieņem vienu objektu ar title un neobligātu 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,
  });
}

Lapas Open Graph attēlam skatiet sadaļu Dinamiskie OG attēli.

OpenGraph attēli

createRootOGImage

Izveido sākumlapas OG attēlu: logotips centrēts uz melna fona.

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

Izveido dokumentācijas lapu OG attēlu: logotips augšējā kreisajā stūrī un balts virsraksts uz melna fona. Fonta arguments nav obligāts; ja tas nav norādīts, virsrakstam izmanto sistēmas fontu.

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

Dinamiskie OG attēli

Lapas OG attēliem nodrošiniet tos maršrutā. Lapas uz šo maršrutu netiek novirzītas automātiski: pievienojiet to katras lapas metadatiem paši, piemēram, ar openGraph: { images: "/docs/og/getting-started" } līdzās laukiem no 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);
}

Palīgfunkcijas

Nepieciešamie faili:

• public/logo-dark.svg — logotips OG attēliem. OG palīgfunkcijas nosaka tā izmēru pēc width un height atribūtiem, tāpēc <svg> tagā abiem jābūt vienkāršiem skaitļiem.
• public/fonts/Inter-Medium.ttf — fonta fails virsrakstiem. Onedocs to neiekļauj.

LLMs.txt

Ģenerējiet LLMs.txt failus AI asistentiem.

generateLLMsText

Ģenerē īsu LLMs.txt saturu. Pieņem avotu, kas ietverts ar createLLMsSource un { title, description? }, un atgriež solījumu.

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

Lapu URL tiek rakstīti tādi, kādi tie nāk no avota, piemēram, /docs/getting-started, bez domēna.

generateLLMsFullText

Ģenerē pilnu LLMs.txt saturu ar visu lapas tekstu. Pieņem tikai ietverto avotu un atgriež solījumu.

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

Lapu saturs tiek iekļauts tikai tad, ja Fumadocs MDX ir ieslēgts includeProcessedMarkdown; skatiet SEO un meklēšana.

createLLMsSource

Ietver Fumadocs avotu (rezultātu loader() vai createSource()) formā, ko nolasa abas iepriekš minētās funkcijas: katras lapas URL, nosaukuma, apraksta un teksta ielādētājus.

SEO

generateSitemap

Ģenerē dokumentācijas vietnes karti. Pieņem vienu objektu: baseUrl, pages sarakstu (parasti no meta.json) un neobligātu docsPath (pēc noklusējuma /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 ?? [],
  });
}

Kā ieraksti kļūst par URL, skatiet SEO un meklēšana.

generateRobots

Ģenerē robots.txt saturu: atļauj visu, kā arī Host un Sitemap rindas. sitemapPath pēc noklusējuma ir /sitemap.xml.

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

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

CSS sākotne

Importējiet CSS sākotni savā globals.css:

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

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

@source ceļi ir relatīvi pret src/app/globals.css.

Sākotnē ir iekļauts:

• Tailwind CSS v4 (instalējiet tailwindcss un @tailwindcss/postcss paši)
• Fumadocs neitrāls motīvs
• Fumadocs sākotnes stili
• --font-sans iestatīts uz mainīgo --font-inter, ko definē FontHead
• Inter OpenType funkcijas pamattekstam un virsrakstiem
• pilna augstuma izkārtojuma stili un Onedocs izkārtojuma pielāgojumi

MDX komponenti

Eksports mdxComponents izplata Fumadocs UI noklusējuma MDX komponentes un pievieno tālāk norādītās komponentes:

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Iekļautie komponenti:

• Fumadocs UI noklusējuma komponenti: pre (koda bloki), a, img, h1 līdz h6 (virsraksti ar enkuriem), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout — informācijas, brīdinājumu un kļūdu paziņojumi
• Card, Cards — kartīšu izkārtojumi
• Tab, Tabs — saturs ar cilnēm
• Step, Steps — numurētas darbības
• Accordion, Accordions — sakļaujamas sadaļas
• File, Folder, Files — failu koki
• ImageZoom — tuvināmi attēli
• TypeTable — tipu dokumentācijas tabulas

InstallBlock un CodeBlock nav iekļauti; pievienojiet tos paši, kā parādīts sadaļā Komponenti.

Lietošanas piemērus skatiet sadaļā Komponenti.