Referenca za API

Popoln referenčni priročnik za vse izvoze iz paketa onedocs.

Vstopne točke

Postavitve

DocsLayout

Glavni ovoj postavitve za strani dokumentacije. Omogoča stransko navigacijo, iskanje in preklop teme.

import { DocsLayout } from "onedocs";

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

Lastnosti:

• config – vaš objekt OnedocsConfig
• pageTree – drevo strani iz vašega vira (e.g., source.pageTree)
• children – vsebina strani

DocsPage

Ovoj za posamezne strani dokumentacije. Ovije Fumadocs UI DocsPage in vsebino vstavi v 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>
  );
}

Lastnosti:

• toc – kazalo vsebine iz podatkov strani
• children – vsebina MDX
• katera koli druga lastnost za Fumadocs UI DocsPage, na primer full

DocsBody

Notranji ovoj telesa za vsebino dokumentacije. Interno ga uporablja DocsPage.

import { DocsBody } from "onedocs";

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

HomePage

Komponenta celotne ciljne strani z uvodnim pasom, funkcijami in nogo.

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

Lastnosti:

• config – vaš objekt OnedocsConfig
• packageName – ime paketa za blok za namestitev (izbirno)
• children – vsebina med funkcijami in nogo (izbirno)

Oglejte si domačo stran in nogo, da izveste, kaj upravlja konfiguracija.

HomeLayout

Osnovna postavitev domače strani (interno jo uporablja HomePage).

import { HomeLayout } from "onedocs";

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

createBaseOptions

Iz konfiguracije sestavi možnosti postavitve Fumadocs UI (naslov navigacijske vrstice ali logotip, nav.links in povezavo GitHub). Uporabljata jo DocsLayout in HomeLayout; sami jo pokličite, kadar neposredno izrišete postavitev Fumadocs UI.

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

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

Komponente

InstallBlock

Zavihki upravljalnikov paketov s prikazom ukazov za namestitev npm, yarn, pnpm in bun (npm i, yarn add, pnpm add, bun add). Gre za asinhrono strežniško komponento.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Lastnosti:

• packageName – ime paketa npm za namestitev
• title – naslov nad zavihki (izbirno)
• description – besedilo nad zavihki (izbirno)
• children – vsebina pod zavihki (izbirno)

Button

Zaobljena povezava v slogu primarnega gumba. Na voljo je en slog.

import { Button } from "onedocs";

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

Lastnosti:

• href – cilj povezave
• children – besedilo gumba
• className – dodatni razredi (izbirno)

Logo

Izriše svetlo in temno sliko ter prikaže tisto, ki ustreza trenutni temi. DocsLayout in HomePage jo uporabljata za logo s svetlimi in temnimi različicami.

import { Logo } from "onedocs";

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

Lastnosti:

• light – pot do slike za svetli način
• dark – pot do slike za temni način
• alt – nadomestno besedilo (privzeto: "Logo")
• className – razredi za obe sliki (izbirno)

CTASection

Razdelek s pozivom k dejanju na domači strani.

import { CTASection } from "onedocs";

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

Lastnosti:

• title – naslov razdelka
• description – besedilo pod naslovom (izbirno)
• cta – konfiguracija gumba z label in href
• children – vsebina pod gumbom (izbirno)

FontHead

Vnaprej naloži pisavo Inter Variable, določi njen @font-face in jo nastavi kot pisavo strani. Dodajte jo v <head> korenske postavitve.

import { FontHead } from "onedocs";

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

Onedocs ne vključuje pisave. Privzeto FontHead naloži /fonts/InterVariable.woff2, zato datoteko shranite v public/fonts/ ali podajte drug URL z fontPath:

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

GitHubIcon

Komponenta ikone GitHub (interno se uporablja v navigaciji).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Blok kode s poudarjeno sintakso, ki jo na strežniku poudari Shiki prek Fumadocs. Gre za asinhrono strežniško komponento.

import { CodeBlock } from "onedocs";

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

Konfiguracija

defineConfig

Pomožna funkcija za konfiguracijo s preverjanjem tipov.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

Tip TypeScript za konfiguracijo.

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

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

Vse možnosti najdete v razdelku Konfiguracija.

Pomožne funkcije za vire

loader

Ponovni izvoz nalagalnika fumadocs-core/source za ustvarjanje virov vsebine.

import { loader } from "onedocs/source";

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

createSource

Pomožna funkcija za ustvarjanje vira vsebine (ovoj okoli nalagalnika). Osnovni URL je privzeto nastavljen na /docs.

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

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

V 0.1.27 createSource vrne netipiziran vir, zato TypeScript javi napake, kot je Property 'data' does not exist on type 'unknown', ko berete page.data (#4). Do odprave napake uporabite loader, kot je prikazano zgoraj.

Metapodatki

createMetadata

Ustvari metapodatke Next.js za vašo korensko postavitev.

import { createMetadata } from "onedocs/metadata";

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

Možnosti:

• baseUrl – osnovni URL vašega spletnega mesta (izbirno)
• additional – dodatna polja Metadata, združena na koncu (izbirno)

Vrne: objekt Next.js Metadata z naslednjim:

• Naslov (config.title) in predloga naslova (%s | Site Name)
• Opis
• Ikona zaznamka iz config.icon, če je nastavljena
• Če je nastavljen baseUrl: metadataBase, metapodatki OpenGraph in kartica Twitter summary_large_image

createDocsPageMetadata

Ustvari metapodatke naslova in opisa za stran z dokumentacijo. Sprejme en objekt z title in izbirnim 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,
  });
}

Za sliko Open Graph posamezne strani glejte Dinamične slike OG.

Slike OpenGraph

createRootOGImage

Ustvari sliko OG za domačo stran: logotip na sredini črnega ozadja.

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

Ustvari sliko OG za strani z dokumentacijo: logotip zgoraj levo in naslov v beli barvi na črnem ozadju. Argument za pisavo je izbiren; če ga ne podate, se za naslov uporabi sistemska pisava.

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

Dinamične slike OG

Slike OG za posamezne strani ponudite prek poti. Na to pot ni samodejno usmerjena nobena stran: dodajte jo v metapodatke vsake strani sami, na primer z openGraph: { images: "/docs/og/getting-started" } ob poljih iz 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);
}

Pomožne funkcije

Zahtevane datoteke:

• public/logo-dark.svg – logotip za slike OG. Pomožne funkcije OG določijo njegovo velikost na podlagi atributov width in height, zato morata biti v oznaki <svg> navedeni obe vrednosti kot navadni števili.
• public/fonts/Inter-Medium.ttf – pisava za naslove. Onedocs je ne vključuje.

LLMs.txt

Ustvari datoteke LLMs.txt za pomočnike z umetno inteligenco.

generateLLMsText

Ustvari jedrnato vsebino LLMs.txt. Sprejme vir, ovit z createLLMsSource in { title, description? }, ter vrne obljubo.

// 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-ji strani so zapisani tako, kot jih vrne vir, na primer /docs/getting-started, brez domene.

generateLLMsFullText

Ustvari celoten LLMs.txt s popolno vsebino strani. Sprejme samo oviti vir in vrne obljubo.

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

Telesa strani so vključena samo, kadar je vklopljen includeProcessedMarkdown za Fumadocs MDX; glejte SEO in iskanje.

createLLMsSource

Vir Fumadocs (rezultat loader() ali createSource()) ovije v obliko, ki jo bereta zgornji funkciji: nalagalniki za URL vsake strani, naslov, opis in besedilo.

SEO

generateSitemap

Ustvari zemljevid mesta za vašo dokumentacijo. Sprejme en objekt: baseUrl, seznam pages (običajno iz meta.json) in izbirni docsPath (privzeto /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 ?? [],
  });
}

Kako vnosi postanejo URL-ji, si oglejte v razdelku SEO in iskanje.

generateRobots

Ustvari vsebino robots.txt: dovoli vse, poleg tega pa še vrstice Host in Sitemap. sitemapPath je privzeto nastavljen na /sitemap.xml.

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

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

Prednastavitev CSS

Uvozite prednastavitev CSS v svoj globals.css:

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

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

Poti @source so relativne glede na src/app/globals.css.

Prednastavitev vključuje:

• Tailwind CSS v4 (tailwindcss in @tailwindcss/postcss namestite sami)
• nevtralno temo Fumadocs
• sloge prednastavitve Fumadocs
• --font-sans nastavljen na spremenljivko --font-inter, ki jo določa FontHead
• funkcije Inter OpenType za osnovno besedilo in naslove
• sloge za postavitev čez celotno višino ter prilagoditve postavitve Onedocs

Komponente MDX

Izvoz mdxComponents razširi privzete komponente Fumadocs UI in doda spodaj navedene komponente MDX:

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Vključene komponente:

• Privzete komponente Fumadocs UI: pre (bloki kode), a, img, h1 do h6 (naslovi s sidri), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout – okvirji z informacijami, opozorili ali napakami
• Card, Cards – postavitve kartic
• Tab, Tabs – vsebina z zavihki
• Step, Steps – oštevilčeni koraki
• Accordion, Accordions – zložljivi razdelki
• File, Folder, Files – drevesa datotek
• ImageZoom – slike s povečavo
• TypeTable – tabele dokumentacije tipov

InstallBlock in CodeBlock nista vključena; dodajte ju sami, kot je prikazano v razdelku Komponente.

Primere uporabe najdete v razdelku Komponente.