Справочник 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 для ИИ-ассистентов.

generateLLMsText

Создает краткое содержимое LLMs.txt. Принимает источник, обернутый с помощью createLLMsSource и { title, description? }, и возвращает promise.

// 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 со всем текстом страниц. Принимает только обернутый источник и возвращает promise.

// 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 ?? [],
  });
}

О том, как записи преобразуются в URL, см. раздел SEO и поиск.

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 не включены; добавьте их самостоятельно, как показано в разделе Компоненты.

Примеры использования см. в разделе Компоненты.