مرجع 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

غلاف لصفحات التوثيق الفردية. يغلّف UI DocsPage من Fumadocs ويضع المحتوى داخل 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
• أي خاصية أخرى في UI DocsPage من Fumadocs، مثل 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

ينشئ خيارات تخطيط UI في Fumadocs (عنوان شريط التنقل أو الشعار، وnav.links ورابط GitHub) من إعداداتك. يستخدمه DocsLayout وHomeLayout؛ واستدعِه بنفسك عند عرض تخطيط UI من Fumadocs مباشرةً.

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 مسبقًا، ويعلن @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

مساعد لإنشاء مصدر محتوى (غلاف حول loader). القيمة الأساسية لـ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? }، ويُرجع وعدًا.

// 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 في MDX الخاص بـFumadocs؛ راجع 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؛ أضفهما بنفسك كما هو موضح في المكونات.

راجع المكونات للاطلاع على أمثلة الاستخدام.