Referință API

Referință completă pentru toate exporturile pachetului onedocs.

Puncte de intrare

Aspecte

DocsLayout

Componentă principală pentru paginile documentației. Oferă navigare laterală, căutare și comutarea temei.

import { DocsLayout } from "onedocs";

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

Proprietăți:

• config - Obiectul dvs. OnedocsConfig
• pageTree - Arborele paginilor din sursa dvs. (de ex., e.g, source.pageTree)
• children - Conținutul paginii

DocsPage

Componentă de încadrare pentru pagini individuale ale documentației. Încadrează Fumadocs UI DocsPage și plasează conținutul în 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>
  );
}

Proprietăți:

• toc - Cuprinsul din datele paginii
• children - Conținutul MDX
• Orice altă proprietate a Fumadocs UI DocsPage, precum full

DocsBody

Componentă interioară de încadrare pentru conținutul documentației. Folosită intern de DocsPage.

import { DocsBody } from "onedocs";

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

HomePage

Componentă completă pentru pagina de destinație, cu secțiune principală, funcționalități și subsol.

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

Proprietăți:

• config - Obiectul dvs. OnedocsConfig
• packageName - Numele pachetului pentru blocul de instalare (opțional)
• children - Conținutul dintre funcționalități și subsol (opțional)

Consultați pagina principală homepage și subsolul footer pentru a vedea ce controlează configurația.

HomeLayout

Aspect de bază pentru pagina principală (folosit intern de HomePage).

import { HomeLayout } from "onedocs";

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

createBaseOptions

Construiește opțiunile de aspect Fumadocs UI (titlul sau sigla barei de navigare, nav.links și linkul GitHub) din configurația dvs. DocsLayout și HomeLayout îl folosesc; apelați-l direct când redați un aspect Fumadocs UI.

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

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

Componente

InstallBlock

Filele managerelor de pachete afișează comenzile de instalare pentru npm, yarn, pnpm și bun (npm i, yarn add, pnpm add, bun add). Este o componentă de server asincronă.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Proprietăți:

• packageName - Numele pachetului npm de instalat
• title - Titlul de deasupra filelor (opțional)
• description - Textul de deasupra filelor (opțional)
• children - Conținutul de sub file (opțional)

Button

Link rotunjit, stilizat ca buton principal. Există un singur stil.

import { Button } from "onedocs";

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

Proprietăți:

• href - Destinația linkului
• children - Textul butonului
• className - Clase suplimentare (opțional)

Logo

Randează o imagine pentru tema luminoasă și una pentru tema întunecată și o afișează pe cea potrivită temei curente. DocsLayout și HomePage o folosesc pentru un logo cu variante pentru tema luminoasă și cea întunecată.

import { Logo } from "onedocs";

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

Proprietăți:

• light - Calea imaginii pentru tema luminoasă
• dark - Calea imaginii pentru tema întunecată
• alt - Text alternativ (implicit: "Logo")
• className - Clase pentru ambele imagini (opțional)

CTASection

Secțiune cu îndemn la acțiune pentru pagina principală.

import { CTASection } from "onedocs";

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

Proprietăți:

• title - Titlul secțiunii
• description - Textul de sub titlu (opțional)
• cta - Configurația butonului cu label și href
• children - Conținutul de sub buton (opțional)

FontHead

Preîncarcă fontul Inter Variable, îi declară @font-face și îl setează ca font al paginii. Adăugați-l la <head> din layoutul rădăcină.

import { FontHead } from "onedocs";

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

Onedocs nu include fontul. În mod implicit, FontHead încarcă /fonts/InterVariable.woff2, așadar plasați fișierul în public/fonts/ sau transmiteți un alt URL cu fontPath:

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

GitHubIcon

Componenta de pictogramă GitHub (folosită intern în navigare).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Bloc de cod cu evidențierea sintaxei, evidențiat pe server cu Shiki până la Fumadocs. Este o componentă de server asincronă.

import { CodeBlock } from "onedocs";

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

Configurare

defineConfig

Funcție ajutătoare pentru configurații sigure din punct de vedere al tipurilor.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

Tipul TypeScript pentru configurație.

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

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

Consultați Configurare pentru toate opțiunile.

Utilitare pentru surse

loader

Reexportă funcția loader fumadocs-core/source pentru crearea surselor de conținut.

import { loader } from "onedocs/source";

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

createSource

Funcție ajutătoare pentru crearea unei surse de conținut (un wrapper peste loader). Baza URL este implicit /docs.

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

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

În 0.1.27, createSource returnează o sursă fără tip, astfel că TypeScript raportează erori precum Property 'data' does not exist on type 'unknown' când citiți page.data (Problema #4). Folosiți loader, așa cum se arată mai sus, până când problema este remediată.

Metadate

createMetadata

Generează metadatele Next.js pentru layoutul rădăcină.

import { createMetadata } from "onedocs/metadata";

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

Opțiuni:

• baseUrl - URL de bază al site-ului (opțional)
• additional - Câmpuri Metadata suplimentare, unite la final (opțional)

Returnează: obiectul Next.js Metadata cu:

• Titlul (config.title) și șablonul titlului (%s | Site Name)
• Descrierea
• Pictograma favicon din config.icon, dacă este setată
• Când baseUrl este setat: metadataBase, metadate OpenGraph și un card Twitter summary_large_image

createDocsPageMetadata

Generează metadatele pentru titlu și descriere ale unei pagini de documentație. Primește un obiect cu title și un description opțional.

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

Pentru o imagine Open Graph specifică unei pagini, consultați Imagini OG dinamice.

Imagini OpenGraph

createRootOGImage

Creează o imagine OG pentru pagina principală: logo-ul centrat pe un fundal negru.

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

Creează o imagine OG pentru paginile de documentație: logo-ul în stânga sus și titlul alb pe fundal negru. Argumentul fontului este opțional; fără acesta, titlul folosește fontul sistemului.

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

Imagini OG dinamice

Pentru imaginile OG specifice fiecărei pagini, serviți-le dintr-o rută. Paginile nu sunt direcționate automat către această rută: adăugați-o manual la metadatele fiecărei pagini, de exemplu cu openGraph: { images: "/docs/og/getting-started" } alături de câmpurile din 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);
}

Funcții ajutătoare

Fișiere necesare:

• public/logo-dark.svg - Logo pentru imaginile OG. Funcțiile ajutătoare OG îi stabilesc dimensiunea pe baza atributelor width și height, așadar eticheta <svg> trebuie să le aibă pe ambele ca numere simple.
• public/fonts/Inter-Medium.ttf - Font pentru titluri. Onedocs nu îl include.

LLMs.txt

Generează fișiere LLMs.txt pentru asistenții AI.

generateLLMsText

Generează conținut LLMs.txt concis. Primește o sursă împachetată cu createLLMsSource și { title, description? } și returnează o promisiune.

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

URL-urile paginilor sunt scrise exact cum provin din sursă, de exemplu /docs/getting-started, fără domeniu.

generateLLMsFullText

Generează LLMs.txt complet, cu tot conținutul paginii. Primește doar sursa împachetată și returnează o promisiune.

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

Corpurile paginilor sunt incluse doar când Fumadocs MDX al lui are includeProcessedMarkdown activat; consultați SEO și căutare.

createLLMsSource

Împachetează o sursă Fumadocs (rezultat loader() sau createSource()) în forma așteptată de cele două funcții de mai sus: URL, titlul, descrierea și încărcătoarele de text ale fiecărei pagini.

SEO

generateSitemap

Generează o hartă a site-ului pentru documentație. Primește un singur obiect: baseUrl, lista pages (de obicei din meta.json) și un docsPath opțional (implicit /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 ?? [],
  });
}

Consultați SEO și căutare pentru a afla cum devin intrările URL-uri.

generateRobots

Generează conținut robots.txt: permite totul, plus liniile Host și Sitemap. sitemapPath are implicit valoarea /sitemap.xml.

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

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

Presetare CSS

Importați presetarea CSS în globals.css:

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

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

Căile @source sunt relative la src/app/globals.css.

Presetarea include:

• Tailwind CSS v4 (instalați voi tailwindcss și @tailwindcss/postcss)
• Temă neutră Fumadocs
• Stiluri de presetare Fumadocs
• --font-sans setat la variabila --font-inter definită de FontHead
• Funcții OpenType Inter pentru textul corpului și titluri
• Stiluri de layout pe toată înălțimea și ajustările de layout Onedocs

Componente MDX

Exportul mdxComponents extinde componentele implicite Fumadocs UI MDX și adaugă componentele de mai jos:

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Componente incluse:

• Componente implicite din Fumadocs UI: pre (blocuri de cod), a, img, h1 la h6 (titluri cu ancore), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout - Casete informative, de avertizare și de eroare
• Card, Cards - Aspecte cu carduri
• Tab, Tabs - Conținut cu file
• Step, Steps - Pași numerotați
• Accordion, Accordions - Secțiuni restrângibile
• File, Folder, Files - Arbori de fișiere
• ImageZoom - Imagini cu zoom
• TypeTable - Tabele de documentare a tipurilor

InstallBlock și CodeBlock nu sunt incluse; adăugați-le conform exemplului din Componente.

Consultați Componente pentru exemple de utilizare.