Довідник 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)
• Опис
• Значок favicon із 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 для помічників ШІ.

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 не входять до комплекту; додайте їх самостійно, як показано в розділі Компоненти.

Дивіться розділ Компоненти, щоб ознайомитися з прикладами використання.