التوثيق هو الواجهة العامة لأي منتج جاد موجه للمطورين. موقع التوثيق الممتاز يحول الزائرين الفضوليين إلى عملاء يدفعون، بينما الموقع البطيء أو المربك يجعلهم يبتعدون بهدوء. في عام 2026، ظهر جيل جديد من أطر التوثيق، وأصبح Fumadocs بسرعة الخيار المفضل للفرق التي تستخدم Next.js. فهو يقدم جمالية بمستوى Mintlify، ودعم MDX عميق، وبحث نصي كامل، وحرية كاملة من قيود البائع — كل ذلك يعمل فوق App Router الذي تعرفه بالفعل.

في هذا الدليل، سنبني موقع توثيق كامل من الصفر باستخدام Fumadocs و Next.js 15. في النهاية، ستحصل على منصة توثيق جاهزة للإنتاج مع دعم الإصدارات والوضع الداكن والبحث الفوري وعلامات تبويب لمجموعات الأكواد والتنبيهات ومكونات MDX مخصصة ومستكشف OpenAPI.

المتطلبات الأساسية

قبل البدء، تأكد من توفر ما يلي:

Node.js 20 أو أحدث مثبت
معرفة عملية بـ React و App Router في Next.js
إلمام بـ TypeScript و MDX
محرر أكواد (يُنصح باستخدام VS Code مع امتداد MDX)
طرفية و Git

يفترض هذا الدليل معرفة متوسطة بـ Next.js 15. إذا كنت جديدًا على App Router، راجع الوثائق الرسمية لـ Next.js أولًا.

ما الذي ستبنيه

سنبني NoqtaDocs، وهو موقع توثيق وهمي لمنصة API داخلية. في النهاية، سيحتوي الموقع على:

صفحة هبوط أنيقة مع قسم رئيسي وبطاقات ميزات
شريط جانبي للتنقل يعكس بنية المجلدات
صفحات MDX مع مكونات مخصصة (تنبيهات، علامات تبويب، شجرة ملفات)
بحث نصي كامل من جانب العميل مدعوم بـ Orama
وضع داكن وسمة قابلة للوصول
صفحة استكشاف OpenAPI
تبديل بين الإصدارين v1 و v2 من API
تصدير ثابت جاهز للنشر على Vercel أو Cloudflare

لماذا Fumadocs في 2026

قبل ثلاث سنوات، كانت معظم الفرق تلجأ إلى Mintlify أو GitBook أو موقع Next.js مصنوع يدويًا. كان لكل خيار مقايضاته. حبسك Mintlify في نموذج تسعير SaaS، وبدا GitBook بطيئًا للوثائق الكثيفة بالأكواد، وتطلبت المواقع المصنوعة يدويًا إعادة اختراع البحث والسمات والتنقل في كل مرة.

يحل Fumadocs هذه المشاكل الثلاث دفعة واحدة. إنه مكتبة وليس منصة، لذا فأنت تملك الكود الخاص بك. يأتي مع دعم من الدرجة الأولى لـ App Router ومكونات الخادم و MDX 3 وتوافق كامل مع Tailwind CSS v4. السمة الافتراضية رائعة منذ التثبيت، لكن كل مكون قابل للتخصيص.

مقارنة بـ Nextra 4، يمنحك Fumadocs تحكمًا أدق في التوجيه والتخطيط، وتنتج خوارزمية الشجرة الخاصة به بناءات أسرع على مجموعات الوثائق الكبيرة. مقارنة بـ Starlight، يبقى Fumadocs ضمن نظام Next.js البيئي، مما يعني أنه يمكنك وضع صفحات التسويق ولوحات التحكم والوثائق في نفس monorepo.

الخطوة 1: إعداد المشروع

لنبدأ بإنشاء مشروع Next.js 15 جديد. افتح الطرفية وشغّل أمر السقالة الخاص بـ Fumadocs، الذي يُعد كل شيء لك.

npx create-fumadocs-app@latest noqtadocs

سيطرح عليك CLI عدة أسئلة. لهذا الدليل، اختر:

الإطار: Next.js
مصدر المحتوى: Fumadocs MDX
Tailwind CSS: نعم
تثبيت التبعيات: نعم

بمجرد انتهاء التثبيت، انتقل إلى المشروع وشغّل خادم التطوير.

cd noqtadocs
npm run dev

افتح http://localhost:3000 في المتصفح. ستظهر لك صفحة هبوط Fumadocs الافتراضية مع شريط جانبي مملوء بأمثلة ملفات MDX.

نظرة عامة على بنية المجلدات

تنتج السقالة بنية نظيفة وقابلة للتنبؤ.

noqtadocs/
├── app/
│   ├── (home)/
│   │   └── page.tsx
│   ├── docs/
│   │   ├── [[...slug]]/
│   │   │   └── page.tsx
│   │   └── layout.tsx
│   ├── api/
│   │   └── search/
│   │       └── route.ts
│   ├── layout.config.tsx
│   └── layout.tsx
├── content/
│   └── docs/
│       ├── index.mdx
│       └── test.mdx
├── lib/
│   └── source.ts
├── source.config.ts
└── package.json

الملفات المهمة التي يجب تذكرها:

source.config.ts — يعلن عن مجموعات المحتوى ومخطط frontmatter
lib/source.ts — يصدّر كائن source المستخدم لقراءة وثائقك
app/docs/[[...slug]]/page.tsx — المسار الديناميكي الذي يعرض كل صفحة وثائق
app/api/search/route.ts — نقطة نهاية البحث Orama المدمجة
content/docs/ — حيث تعيش ملفات MDX الخاصة بك

الخطوة 2: تكوين مصدر المحتوى

افتح source.config.ts. يخبر هذا الملف Fumadocs بكيفية تحليل MDX، وما هو frontmatter المتوقع، وكيفية إنشاء فهرس البحث.

import { defineDocs, defineConfig } from "fumadocs-mdx/config";
import { z } from "zod";
 
export const docs = defineDocs({
  dir: "content/docs",
  docs: {
    schema: z.object({
      title: z.string(),
      description: z.string().optional(),
      icon: z.string().optional(),
      version: z.enum(["v1", "v2"]).default("v2"),
    }),
  },
});
 
export default defineConfig({
  mdxOptions: {
    rehypeCodeOptions: {
      themes: {
        light: "github-light",
        dark: "github-dark",
      },
    },
  },
});

أضفنا حقلًا مخصصًا version إلى مخطط frontmatter. سنستخدمه لاحقًا لتشغيل تبديل الإصدارات. تتيح كتلة rehypeCodeOptions تمييز بناء الجملة Shiki مع سمات فاتحة وداكنة، تتكيف تلقائيًا مع نظام ألوان المستخدم.

أعد تشغيل خادم التطوير حتى يدخل تغيير المخطط حيز التنفيذ.

npm run dev

الخطوة 3: بناء التنقل الجانبي

يستخرج Fumadocs التنقل مباشرة من بنية المجلدات. لتجميع الوثائق في أقسام، أنشئ ملف meta.json في كل مجلد. استبدل محتويات content/docs/ بالبنية التالية.

content/docs/
├── index.mdx
├── meta.json
├── getting-started/
│   ├── meta.json
│   ├── installation.mdx
│   └── quickstart.mdx
├── guides/
│   ├── meta.json
│   ├── authentication.mdx
│   └── webhooks.mdx
└── reference/
    ├── meta.json
    └── openapi.mdx

هذا هو ملف meta.json الجذر:

{
  "title": "NoqtaDocs",
  "pages": [
    "index",
    "---Getting Started---",
    "getting-started",
    "---Guides---",
    "guides",
    "---Reference---",
    "reference"
  ]
}

تنشئ صيغة ---العنوان--- فواصل أقسام في الشريط الجانبي. يتحكم ترتيب المصفوفة في الترتيب المرئي. هذا التحكم الصريح هو ما يجعل Fumadocs منظمًا بدلًا من فوضوي أبجديًا.

داخل كل مجلد فرعي، أضف ملف meta.json يسرد الصفحات.

{
  "title": "Getting Started",
  "pages": ["installation", "quickstart"]
}

الخطوة 4: كتابة أول صفحات وثائق

لنضف محتوى حقيقيًا. افتح content/docs/getting-started/installation.mdx وألصق ما يلي.

---
title: التثبيت
description: تثبيت Noqta SDK في مشروعك
icon: Download
---
 
تم نشر Noqta SDK على npm ويدعم Node.js 20 وما فوق.
 
## التثبيت باستخدام مدير الحزم الخاص بك
 
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
 
<Tabs items={["npm", "pnpm", "bun"]}>
  <Tab value="npm">```bash npm install @noqta/sdk ```</Tab>
  <Tab value="pnpm">```bash pnpm add @noqta/sdk ```</Tab>
  <Tab value="bun">```bash bun add @noqta/sdk ```</Tab>
</Tabs>
 
## التحقق من التثبيت
 
أنشئ سكريبت اختبار صغيرًا وقم بتشغيله.
 
```typescript
import { NoqtaClient } from "@noqta/sdk";
 
const client = new NoqtaClient({ apiKey: process.env.NOQTA_API_KEY });
const status = await client.health.check();
console.log(status);

إذا تم الإعداد بشكل صحيح، فسترى استجابة JSON تؤكد الاتصال.


مكون `Tabs` هو واحد من العشرات المرفقة مع `fumadocs-ui`. يمكن لكل علامة تبويب استضافة أي محتوى MDX، بما في ذلك المزيد من كتل الأكواد والجداول والصور.

## الخطوة 5: إضافة تنبيهات وشجرة ملفات

يأتي Fumadocs بمجموعة غنية من مكونات MDX. أكثر اثنين فائدة هما `Callout` و `Files`. أضف قسمًا جديدًا إلى صفحة التثبيت الخاصة بك.

```mdx
import { Callout } from "fumadocs-ui/components/callout";
import { Files, Folder, File } from "fumadocs-ui/components/files";

<Callout type="info">
  يأتي SDK مع أنواع TypeScript جاهزة. لا حاجة لتثبيتات إضافية.
</Callout>

<Callout type="warn">
  لا تقم أبدًا بإيداع مفتاح API الخاص بك في git. استخدم متغيرات البيئة بدلًا من ذلك.
</Callout>

## بنية المشروع

بعد التثبيت، يجب أن يبدو مشروعك هكذا.

<Files>
  <Folder name="src" defaultOpen>
    <File name="index.ts" />
    <Folder name="lib">
      <File name="noqta.ts" />
    </Folder>
  </Folder>
  <File name=".env.local" />
  <File name="package.json" />
</Files>

احفظ الملف وأعد تحميل المتصفح. تظهر التنبيهات بحدود ملونة وشجرة الملفات تفاعلية — يمكن توسيع المجلدات وطيها.

الخطوة 6: تخصيص التخطيط

افتح app/layout.config.tsx. يتحكم هذا الملف في التخطيط العام: شريط التنقل العلوي ورأس الشريط الجانبي ورابط GitHub.

import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared";
 
export const baseOptions: BaseLayoutProps = {
  nav: {
    title: (
      <span className="font-semibold">
        NoqtaDocs
      </span>
    ),
  },
  links: [
    { text: "Documentation", url: "/docs" },
    { text: "Blog", url: "/blog" },
    { text: "Changelog", url: "/changelog" },
  ],
  githubUrl: "https://github.com/your-org/noqtadocs",
};

يعرض شريط التنقل العلوي الآن علامتك التجارية والروابط الخارجية. ولأن كل شيء يتم عرضه على الخادم، تتغير هذه العناصر فورًا دون أي وميض من جانب العميل.

الخطوة 7: تنفيذ البحث النصي الكامل

تتضمن السقالة بالفعل بحثًا مدعومًا بـ Orama في app/api/search/route.ts. افتحه وتأكد من أنه يبدو هكذا.

import { source } from "@/lib/source";
import { createFromSource } from "fumadocs-core/search/server";
 
export const { GET } = createFromSource(source);

هذا كل ما يلزم من كود. يمشي Fumadocs عبر شجرة المحتوى الخاصة بك، ويستخرج العناوين، ويبني فهرس Orama في الذاكرة. تتضمن نتائج البحث تمييزًا غنيًا للمصطلحات المطابقة.

لفتح مربع حوار البحث، اضغط على Cmd+K أو Ctrl+K. يتم تجميع نتائج البحث حسب الصفحة وتعرض العنوان المطابق، مما يجعل الربط العميق بأقسام محددة أمرًا تافهًا.

بالنسبة لمجموعات الوثائق الأكبر التي تتجاوز ألف صفحة، انتقل إلى محولات Algolia أو Trieve. تُستخدم نفس واجهة createFromSource ولكن مع خلفية مختلفة.

الخطوة 8: إضافة صفحة هبوط جميلة

صفحة الهبوط الافتراضية مجرد عنصر نائب. استبدل app/(home)/page.tsx ببطل وشبكة ميزات ودعوة لاتخاذ إجراء.

import Link from "next/link";
 
export default function HomePage() {
  return (
    <main className="flex flex-1 flex-col">
      <section className="container flex flex-col items-center gap-6 py-24 text-center">
        <h1 className="text-5xl font-bold tracking-tight">
          أسرع طريقة لشحن الوثائق.
        </h1>
        <p className="max-w-2xl text-lg text-fd-muted-foreground">
          NoqtaDocs منصة توثيق مبنية على Fumadocs و Next.js 15.
          بلا قيود من البائع، إعدادات افتراضية رائعة، بحث فوري.
        </p>
        <div className="flex gap-4">
          <Link
            href="/docs"
            className="rounded-md bg-fd-primary px-6 py-3 font-medium text-fd-primary-foreground"
          >
            اقرأ الوثائق
          </Link>
          <Link
            href="https://github.com/your-org/noqtadocs"
            className="rounded-md border px-6 py-3 font-medium"
          >
            عرض على GitHub
          </Link>
        </div>
      </section>
    </main>
  );
}

لاحظ رموز التصميم المسبوقة بـ fd-. يأتي Fumadocs بنظام كامل لمتغيرات CSS يتكيف مع الأوضاع الفاتحة والداكنة تلقائيًا. استخدم هذه الرموز بدلًا من ترميز الألوان بشكل صريح.

الخطوة 9: تنفيذ تبديل الإصدارات

غالبًا ما تحتاج وثائق API إلى دعم إصدارات متعددة. أضفنا حقل version إلى frontmatter سابقًا. الآن سنستخدمه لتصفية الصفحات.

أنشئ ملفًا جديدًا lib/source.ts إذا لم يكن موجودًا بالفعل.

import { docs } from "@/.source";
import { loader } from "fumadocs-core/source";
 
export const source = loader({
  baseUrl: "/docs",
  source: docs.toFumadocsSource(),
});
 
export function getVersionPages(version: "v1" | "v2") {
  return source.getPages().filter((page) => page.data.version === version);
}

أضف محول إصدارات إلى الشريط الجانبي بإنشاء app/docs/layout.tsx.

import { DocsLayout } from "fumadocs-ui/layouts/docs";
import { source } from "@/lib/source";
import { baseOptions } from "@/app/layout.config";
 
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <DocsLayout
      tree={source.pageTree}
      sidebar={{
        banner: (
          <select className="w-full rounded-md border bg-fd-card p-2">
            <option value="v2">API v2 (الأحدث)</option>
            <option value="v1">API v1 (قديم)</option>
          </select>
        ),
      }}
      {...baseOptions}
    >
      {children}
    </DocsLayout>
  );
}

للحصول على محول تفاعلي بالكامل، استخرج القائمة المنسدلة إلى مكون عميل واستخدم useRouter للانتقال إلى الشجرة الفرعية للإصدار الصحيح. تقوم مواقع الإنتاج عادة بتقسيم الإصدارات إلى مجلدات مثل content/docs/v1/ و content/docs/v2/.

الخطوة 10: إضافة مستكشف OpenAPI

يتضمن Fumadocs تكامل OpenAPI رسمي يحول مواصفات API الخاصة بك إلى وثائق تفاعلية. قم بتثبيته.

npm install fumadocs-openapi

أنشئ ملفات MDX من مواصفات OpenAPI. أنشئ scripts/generate-openapi.ts.

import { generateFiles } from "fumadocs-openapi";
 
void generateFiles({
  input: ["./openapi.json"],
  output: "./content/docs/reference",
  per: "operation",
});

شغّل السكريبت.

npx tsx scripts/generate-openapi.ts

تصبح كل عملية API صفحة MDX خاصة بها، كاملة بجداول المعلمات وعينات الاستجابة ولوحة "جربها" المباشرة. تعيش الصفحات المُنشأة جنبًا إلى جنب مع الوثائق المكتوبة يدويًا وترث نفس السمة.

الخطوة 11: السمات والتشطيب

افتح app/global.css وقم بتخصيص رموز التصميم. يستخدم Fumadocs متغيرات CSS بصيغة HSL يمكنك تجاوزها لكل سمة.

@layer base {
  :root {
    --color-fd-primary: 250 95% 55%;
    --color-fd-primary-foreground: 0 0% 100%;
    --color-fd-background: 0 0% 100%;
  }
 
  .dark {
    --color-fd-primary: 250 95% 65%;
    --color-fd-background: 240 10% 4%;
  }
}

تتدفق لون العلامة التجارية الآن عبر الأزرار والروابط وعناصر الشريط الجانبي النشطة وتمييزات البحث. يتم إعادة تحميل التغييرات على الفور بفضل Tailwind v4.

لإضافة شعارك إلى شريط التنقل العلوي، ضع ملف SVG في public/logo.svg وأشر إليه في layout.config.tsx.

import Image from "next/image";
 
nav: {
  title: (
    <span className="flex items-center gap-2">
      <Image src="/logo.svg" alt="" width={24} height={24} />
      <span className="font-semibold">NoqtaDocs</span>
    </span>
  ),
},

الخطوة 12: البناء والنشر

ابنِ حزمة الإنتاج.

npm run build

يستخدم Fumadocs بشكل افتراضي إعادة التوليد الثابت التدريجي في Next.js. يتم إنشاء كل صفحة بشكل ثابت في وقت البناء، ويتم شحن فهرس البحث كملف JSON واحد يتم جلبه عند الطلب.

للنشر على Vercel، ادفع إلى GitHub واستورد المستودع. لا توجد حاجة لتكوين إضافي.

بالنسبة لـ Cloudflare Pages، أضف ملف wrangler.toml واستخدم محول @cloudflare/next-on-pages. حجم البناء عادة ما يكون أقل من 5 ميجابايت حتى للمواقع التي تحتوي على 500 صفحة، وهو ضمن الحد المجاني لـ Cloudflare.

اختبار التنفيذ

اعرض هذه القائمة قبل مشاركة موقعك.

افتح /docs وانقر على كل عنصر في الشريط الجانبي. يجب أن يتم عرض كل العناصر بدون أخطاء.
اضغط على Cmd+K وابحث عن مصطلحات عبر صفحات متعددة. يجب أن تبرز النتائج التطابقات.
بدّل الوضع الداكن باستخدام محول السمات. تأكد من أن كتل الأكواد تتكيف بشكل صحيح.
قلص النافذة إلى عرض الجوال. يجب أن ينطوي الشريط الجانبي إلى درج.
افحص مصدر الصفحة. يجب أن تأتي كل وثيقة بعلامات meta وصور OpenGraph المناسبة.
شغّل Lighthouse. يحقق موقع Fumadocs المُكوَّن بشكل صحيح درجة 95 أو أعلى في جميع المقاييس.

استكشاف الأخطاء وإصلاحها

الشريط الجانبي لا يُظهر الصفحات الجديدة. أعد تشغيل خادم التطوير. يخزن Fumadocs شجرة الصفحات مؤقتًا عند بدء التشغيل ويعيد بناءها كلما تغير source.config.ts أو meta.json.

مكونات MDX تُعرض كـ HTML خام. تأكد من استيراد المكون في أعلى ملف MDX. على عكس Pages Router، لا تستورد ملفات MDX في App Router تلقائيًا.

البحث لا يعيد أي نتائج. تحقق من أن app/api/search/route.ts يصدّر GET بشكل صحيح. افتح علامة تبويب الشبكة في المتصفح وابحث عن استجابة 200 من /api/search.

يفشل البناء بسبب أخطاء النوع في frontmatter. مخطط Zod الخاص بك في source.config.ts لا يتطابق مع frontmatter في ملفات MDX. أضف الحقل المفقود أو ضع علامة عليه كاختياري.

الخطوات التالية

لديك الآن موقع توثيق على مستوى الإنتاج. إليك بعض الأفكار لتوسيعه.

أضف قسم /blog باستخدام نفس خط أنابيب MDX
ادمج التحليلات مع PostHog أو Plausible لتتبع الصفحات الشائعة
أنشئ صفحات سجل التغييرات تلقائيًا من إصدارات GitHub
أضف مساعد توثيق مدعوم بالذكاء الاصطناعي باستخدام Vercel AI SDK وفهرس البحث الخاص بك
أنشئ مستكشف API عام يقوم بتنفيذ الطلبات مباشرة من المتصفح

للحصول على أنماط أكثر تقدمًا، راجع دروسنا التعليمية ذات الصلة حول server actions في Next.js 15 و AI SDK و TanStack Query.

الخاتمة

يحقق Fumadocs توازنًا نادرًا بين راحة المطور وأناقة التصميم. يمنحك نفس الجمالية الرائعة لمنصات التوثيق SaaS المدفوعة مع الحفاظ على كل سطر من الأكواد في مستودعك. من خلال دمج مكونات الخادم و MDX 3 و Tailwind v4 وبحث Orama، ينتج موقع توثيق سريع البناء وسريع التحميل وسهل الصيانة.

إذا كنت بصدد بدء مشروع جديد في عام 2026، فإن Fumadocs هو الرهان الأكثر أمانًا للتوثيق. المجتمع نشط، وواجهة API مستقرة، ومسار الترقية ودود. اطلقه، شاركه، وراقب تجربة المطور تتحسن بين عشية وضحاها.

بناء موقع توثيق حديث باستخدام Fumadocs و Next.js 15 في 2026