# مرجع API

مرجع كامل لجميع الصادرات من حزمة `onedocs`.

## نقاط الدخول

| الاستيراد | الوصف |
|--------|-------------|
| `onedocs` | نقطة الدخول الرئيسية - التخطيطات والمكونات و`mdxComponents` و`defineConfig` ومساعدات المصدر |
| `onedocs/components` | مكونات Fumadocs UI بالإضافة إلى `InstallBlock` و`CodeBlock` و`Button` و`Logo` |
| `onedocs/config` | مساعدات الإعداد |
| `onedocs/source` | أدوات مساعدة لمصادر المحتوى |
| `onedocs/metadata` | إنشاء البيانات الوصفية |
| `onedocs/og` | إنشاء صور OpenGraph |
| `onedocs/llms` | إنشاء LLMs.txt |
| `onedocs/seo` | خريطة الموقع وrobots.txt |
| `onedocs/css/preset.css` | إعداد مسبق لـTailwind CSS |

## التخطيطات

### DocsLayout

غلاف التخطيط الرئيسي لصفحات التوثيق. يوفر تنقلًا جانبيًا وبحثًا ومفتاحًا للسمة.

```tsx
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`.

```tsx
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`.

```tsx
import { DocsBody } from "onedocs";

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

### HomePage

مكوّن صفحة هبوط كاملة يضم القسم الرئيسي والميزات والتذييل.

```tsx
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` - المحتوى بين الميزات والتذييل (اختياري)

راجع [الصفحة الرئيسية](https://onedocs.inline0.dev/ar/docs/configuration#homepage) و[التذييل](https://onedocs.inline0.dev/ar/docs/configuration#footer) لمعرفة ما يتحكم فيه الإعداد.

### HomeLayout

التخطيط الأساسي للصفحة الرئيسية (يُستخدم داخليًا بواسطة `HomePage`).

```tsx
import { HomeLayout } from "onedocs";

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

### createBaseOptions

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

```tsx
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`). وهو مكوّن خادم غير متزامن.

```tsx
import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />
```

**الخصائص:**
- `packageName` - اسم حزمة npm المطلوب تثبيتها
- `title` - العنوان فوق علامات التبويب (اختياري)
- `description` - النص فوق علامات التبويب (اختياري)
- `children` - المحتوى أسفل علامات التبويب (اختياري)

### Button

رابط مستدير بتنسيق زر أساسي. له نمط واحد.

```tsx
import { Button } from "onedocs";

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

**الخصائص:**
- `href` - وجهة الرابط
- `children` - نص الزر
- `className` - فئات إضافية (اختياري)

### Logo

يعرض صورة فاتحة وأخرى داكنة، ويُظهر الصورة المطابقة للسمة الحالية. يستخدمه `DocsLayout` و`HomePage` لعرض `logo` بنسختين فاتحة وداكنة.

```tsx
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

قسم الحث على اتخاذ إجراء للصفحة الرئيسية.

```tsx
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>` في التخطيط الجذر.

```tsx
import { FontHead } from "onedocs";

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

لا تتضمن Onedocs الخط. افتراضيًا، يحمّل `FontHead` الملف `/fonts/InterVariable.woff2`، لذا ضعه في `public/fonts/` أو مرّر URL آخر مع `fontPath`:

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

### GitHubIcon

مكوّن أيقونة GitHub (يُستخدم داخليًا في التنقل).

```tsx
import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />
```

### CodeBlock

كتلة أكواد مميّزة نحويًا على الخادم باستخدام Shiki عبر Fumadocs. وهي مكوّن خادم غير متزامن.

```tsx
import { CodeBlock } from "onedocs";

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

## الإعداد

### defineConfig

مساعد إعداد يضمن سلامة الأنواع.

```tsx
import { defineConfig } from "onedocs/config";

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

### OnedocsConfig

نوع TypeScript للإعداد.

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

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

راجع [الإعداد](https://onedocs.inline0.dev/ar/docs/configuration) للاطلاع على جميع الخيارات.

## أدوات مساعدة للمصدر

### loader

إعادة تصدير لمحمّل `fumadocs-core/source` لإنشاء مصادر المحتوى.

```tsx
import { loader } from "onedocs/source";

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

### createSource

مساعد لإنشاء مصدر محتوى (غلاف حول loader). القيمة الأساسية لـURL هي `/docs` افتراضيًا.

```tsx
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](https://github.com/inline0/onedocs/issues/4)). استخدم `loader` كما هو موضح أعلاه إلى أن يُصلح ذلك.

## البيانات الوصفية

### createMetadata

ينشئ بيانات Next.js الوصفية للتخطيط الجذر.

```tsx
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` اختياري.

```tsx
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 الديناميكية](#dynamic-og-images).

## صور OpenGraph

### createRootOGImage

ينشئ صورة OG للصفحة الرئيسية: شعارك في الوسط على خلفية سوداء.

```tsx
// 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 لصفحات التوثيق: الشعار في أعلى اليسار والعنوان باللون الأبيض على خلفية سوداء. وسيطة الخط اختيارية؛ ومن دونها يستخدم العنوان خط النظام.

```tsx
// 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`.

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

### الدوال المساعدة

| الدالة | الوصف |
|----------|-------------|
| `loadPublicFile(path)` | يحمّل ملفًا من `public/` كبيانات URL ومخزن مؤقت؛ ويقرأ أيضًا سمتي `width` و`height` لملفات SVG |
| `loadInterFont(path?)` | يحمّل خطًا من `public/` لصور OG، و`fonts/Inter-Medium.ttf` افتراضيًا |
| `ogImageSize` | أبعاد صورة OG القياسية `{ width: 1200, height: 630 }` |
| `ogImageContentType` | نوع MIME `"image/png"` |

**الملفات المطلوبة:**
- `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? }`، ويُرجع وعدًا.

```tsx
// 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 كاملًا بمحتوى الصفحات كاملًا. يتلقى المصدر المغلف وحده ويُرجع وعدًا.

```tsx
// 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 والبحث](https://onedocs.inline0.dev/ar/docs/seo-search#full-content-version).

### createLLMsSource

يغلّف مصدر Fumadocs (نتيجة `loader()` أو `createSource()`) بالهيئة التي تقرؤها الدالتان أعلاه: URL كل صفحة، وعنوانها ووصفها ومحمّلات النص.

## SEO

### generateSitemap

ينشئ خريطة موقع للتوثيق. يتلقى كائنًا واحدًا: `baseUrl`، قائمة `pages` (عادةً من `meta.json`)، و`docsPath` اختياري (القيمة الافتراضية `/docs`).

```tsx
// 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 والبحث](https://onedocs.inline0.dev/ar/docs/seo-search#sitemap) لمعرفة كيفية تحويل الإدخالات إلى عناوين URL.

### generateRobots

ينشئ محتوى robots.txt: السماح للجميع، بالإضافة إلى سطري `Host` و`Sitemap`. القيمة الافتراضية لـ`sitemapPath` هي `/sitemap.xml`.

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

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

## إعداد CSS المسبق

استورد الإعداد المسبق CSS في `globals.css`:

```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، ويضيف المكونات التالية:

```tsx
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`؛ أضفهما بنفسك كما هو موضح في [المكونات](https://onedocs.inline0.dev/ar/docs/components#more-components).

راجع [المكونات](https://onedocs.inline0.dev/ar/docs/components) للاطلاع على أمثلة الاستخدام.