Справочник за API

Пълен справочник за всички експорти от пакета onedocs.

Входни точки

Оформления

DocsLayout

Основна обвивка на оформлението за документационни страници. Предоставя странична навигация, търсене и превключване на темата.

import { DocsLayout } from "onedocs";

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

Свойства:

• config — вашият обект OnedocsConfig
• pageTree — дърво на страниците от източника ви (e.g., source.pageTree)
• children — съдържание на страницата

DocsPage

Обвивка за отделни документационни страници. Обгръща Fumadocs UI DocsPage и поставя съдържанието в 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>
  );
}

Свойства:

• toc — съдържание от данните на страницата
• children — съдържание MDX
• Всяко друго свойство на Fumadocs UI DocsPage, например full

DocsBody

Вътрешна обвивка за съдържанието на документацията. Използва се вътрешно от DocsPage.

import { DocsBody } from "onedocs";

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

HomePage

Пълен компонент за начална страница с основен банер, функции и долен колонтитул.

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

Свойства:

• config — вашият обект OnedocsConfig
• packageName — име на пакета за блока за инсталиране (незадължително)
• children — съдържание между функциите и долния колонтитул (незадължително)

Вижте начална страница и долен колонтитул, за да разберете какво управлява конфигурацията.

HomeLayout

Основно оформление за началната страница (използва се вътрешно от HomePage).

import { HomeLayout } from "onedocs";

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

createBaseOptions

Изгражда опциите за оформлението на Fumadocs UI (заглавие или лого на навигационната лента, nav.links и връзката GitHub) от конфигурацията ви. DocsLayout и HomeLayout го използват; извикайте го сами, когато визуализирате директно оформление Fumadocs UI.

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

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

Компоненти

InstallBlock

Раздели за мениджъри на пакети, показващи команди за инсталиране на npm, yarn, pnpm и bun (npm i, yarn add, pnpm add, bun add). Това е асинхронен сървърен компонент.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Свойства:

• packageName — името на пакета npm за инсталиране
• title — заглавие над разделите (незадължително)
• description — текст над разделите (незадължително)
• children — съдържание под разделите (незадължително)

Button

Заоблена връзка, оформена като основен бутон. Има един стил.

import { Button } from "onedocs";

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

Свойства:

• href — цел на връзката
• children — текст на бутона
• className — допълнителни класове (незадължително)

Logo

Показва светло и тъмно изображение и избира това, което съответства на текущата тема. DocsLayout и HomePage го използват за logo със светъл и тъмен вариант.

import { Logo } from "onedocs";

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

Свойства:

• light — път до изображението за светъл режим
• dark — път до изображението за тъмен режим
• alt — алтернативен текст (по подразбиране: "Logo")
• className — класове за двете изображения (незадължително)

CTASection

Секция с призив към действие за началната страница.

import { CTASection } from "onedocs";

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

Свойства:

• title — заглавие на секцията
• description — текст под заглавието (незадължително)
• cta — конфигурация на бутона с label и href
• children — съдържание под бутона (незадължително)

FontHead

Предварително зарежда шрифта Inter Variable, задава неговия @font-face и го настройва като шрифт на страницата. Добавете го към <head> на основното оформление.

import { FontHead } from "onedocs";

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

Onedocs не включва шрифта. По подразбиране FontHead зарежда /fonts/InterVariable.woff2, затова поставете файла в public/fonts/ или подайте друг URL с fontPath:

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

GitHubIcon

Компонент за икона GitHub (използва се вътрешно в навигацията).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Блок с код и оцветяване на синтаксиса на сървъра чрез Shiki и Fumadocs. Това е асинхронен сървърен компонент.

import { CodeBlock } from "onedocs";

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

Конфигурация

defineConfig

Помощна функция за конфигурация с проверка на типовете.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

Тип TypeScript за конфигурация.

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

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

Вижте Конфигурация за всички опции.

Помощни функции за източници

loader

Повторно експортиране на зареждащ модул fumadocs-core/source за създаване на източници на съдържание.

import { loader } from "onedocs/source";

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

createSource

Помощна функция за създаване на източник на съдържание (обвивка около зареждащия модул). Основният URL по подразбиране е /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 връща нетипизиран източник, затова TypeScript отчита грешки като Property 'data' does not exist on type 'unknown' при четене на page.data (#4). Използвайте loader, както е показано по-горе, докато това не бъде поправено.

Метаданни

createMetadata

Генерира метаданни Next.js за основното оформление.

import { createMetadata } from "onedocs/metadata";

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

Опции:

• baseUrl — основният URL на сайта ви (незадължително)
• additional — допълнителни полета Metadata, слети накрая (незадължително)

Връща: обект Next.js Metadata със следното:

• Заглавие (config.title) и шаблон за заглавие (%s | Site Name)
• Описание
• Фавикон от config.icon, ако е зададен
• Когато е зададено baseUrl: metadataBase, метаданни OpenGraph и карта Twitter summary_large_image

createDocsPageMetadata

Генерира метаданните за заглавие и описание на документационна страница. Приема един обект с title и незадължителен 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,
  });
}

За изображение Open Graph за отделна страница вижте Динамични OG изображения.

OpenGraph изображения

createRootOGImage

Създава OG изображение за началната страница: логото е центрирано върху черен фон.

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

Създава OG изображение за документационни страници: логото е горе вляво, а заглавието е с бял текст на черен фон. Аргументът за шрифт е незадължителен; без него заглавието използва системния шрифт.

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

Динамични OG изображения

За OG изображения за отделни страници ги предоставяйте чрез маршрут. Страниците не се свързват автоматично с този маршрут: добавете го сами към метаданните на всяка страница, например с openGraph: { images: "/docs/og/getting-started" } до полетата от 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);
}

Помощни функции

Необходими файлове:

• public/logo-dark.svg — лого за OG изображения. Помощните функции за OG определят размера му според атрибутите width и height, затова тагът <svg> трябва да съдържа и двете като обикновени числа.
• public/fonts/Inter-Medium.ttf — шрифт за заглавията. Onedocs не го включва.

LLMs.txt

Генериране на файлове LLMs.txt за AI асистенти.

generateLLMsText

Генерира кратко съдържание LLMs.txt. Приема източник, обвит с createLLMsSource и { title, description? }, и връща обещание.

// 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 адресите на страниците се записват така, както идват от източника, например /docs/getting-started, без домейн.

generateLLMsFullText

Генерира пълно LLMs.txt с цялото съдържание на страниците. Приема само обвития източник и връща обещание.

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

Съдържанието на страниците се включва само когато настройката includeProcessedMarkdown на Fumadocs MDX е включена; вижте SEO и търсене.

createLLMsSource

Обгръща източник Fumadocs (резултат от loader() или createSource()) във формата, която използват двете функции по-горе: всеки елемент на страницата съдържа URL, заглавие, описание и зареждащи функции за текста.

SEO

generateSitemap

Генерира карта на сайта за документацията ви. Приема един обект: baseUrl, списъка pages (обикновено от meta.json) и незадължителен docsPath (по подразбиране /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 ?? [],
  });
}

Вижте SEO и търсене, за да разберете как записите се превръщат в URL адреси.

generateRobots

Генерира съдържание robots.txt: разрешава всичко, както и редовете Host и Sitemap. sitemapPath по подразбиране е /sitemap.xml.

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

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

Предварителна настройка CSS

Импортирайте предварителната настройка CSS във вашия globals.css:

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

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

Пътищата @source в предварителната настройка са относителни спрямо src/app/globals.css.

Предварителната настройка включва:

• Tailwind CSS v4 (инсталирайте сами tailwindcss и @tailwindcss/postcss)
• неутрална тема Fumadocs
• стилове на предварителна настройка Fumadocs
• --font-sans настроен към променливата --font-inter, дефинирана от FontHead
• OpenType функции на Inter за основен текст и заглавия
• стилове за оформление с пълна височина и настройки на оформлението Onedocs

Компоненти MDX

Експортирането на mdxComponents разширява компонентите по подразбиране на Fumadocs UI MDX и добавя компонентите по-долу:

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Включени компоненти:

• Стандартни настройки на Fumadocs UI: pre (блокове с код), a, img, h1 до h6 (заглавия с котви), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout — информационни, предупредителни и аварийни карета
• Card, Cards — оформления с карти
• Tab, Tabs — съдържание с раздели
• Step, Steps — номерирани стъпки
• Accordion, Accordions — разгъващи се секции
• File, Folder, Files — дървета на файлове
• ImageZoom — изображения с мащабиране
• TypeTable — таблици с документация за типове

InstallBlock и CodeBlock не са включени; добавете ги сами, както е показано в Компоненти.

Вижте Компоненти за примери за употреба.