انتقل إلى المحتوى

الإعداد

توضع الإعدادات العامة للموقع في onedocs.config.ts في جذر مشروعك. مرّر الكائن المُصدَّر إلى DocsLayout وHomePage وcreateMetadata لتقرأه. يُحدَّد مكان المحتوى في source.config.ts، وليس هنا (راجع البدء).

الإعداد الأساسي

TypeScript
import { defineConfig } from "onedocs/config";

export default defineConfig({
  title: "My Project",
  description: "Documentation for My Project",
});

هذا هو الحد الأدنى. كل ما عداه اختياري.

مثال كامل

أيقونات الميزات هي عناصر React، لذا يجب أن يكون ملف الإعداد الذي يستخدمها ملف .tsx:

TSX
import { defineConfig } from "onedocs/config";
import { Rocket, Zap } from "lucide-react";

export default defineConfig({
  title: "My Project",
  description: "Documentation for My Project",

  // Logo (string or light/dark variants)
  logo: "/logo.svg",
  // logo: { light: "/logo-light.svg", dark: "/logo-dark.svg" },

  // Favicon (string or light/dark variants), used by createMetadata
  icon: "/icon.png",

  // Navigation bar
  nav: {
    links: [
      { label: "Blog", href: "/blog" },
      { label: "Changelog", href: "/changelog" },
    ],
    github: "username/repo",
  },

  // Homepage
  homepage: {
    hero: {
      title: "My Project",
      description: "Documentation that ships with the code",
      cta: { label: "Get Started", href: "/docs" },
    },
    features: [
      {
        title: "Fast",
        description: "Static pages built by Next.js",
        icon: <Zap className="size-5 text-fd-primary" />,
      },
      {
        title: "Simple",
        description: "Write markdown, get docs",
        icon: <Rocket className="size-5 text-fd-primary" />,
      },
    ],
  },

  // Homepage footer
  footer: {
    links: [{ label: "License", href: "https://github.com/username/repo/blob/main/LICENSE" }],
  },
});

الخيارات

title (مطلوب)

اسم موقعك. يعرضه شريط التنقل عند عدم تعيين logo، ويستخدمه createMetadata عنوانًا افتراضيًا للصفحة وفي القالب %s | Title، كما تستخدمه الصفحة الرئيسية عنوانًا رئيسيًا ونصًا في سطر حقوق النشر بالتذييل.

TypeScript
title: "My Project"

الوصف

وصف قصير. يستخدمه createMetadata للوصف الوصفي، وتعرضه الصفحة الرئيسية أسفل العنوان الرئيسي عند عدم تعيين homepage.hero.description.

TypeScript
description: "Documentation for My Project"

يستبدل العنوان في شريط التنقل. استخدم مسارًا واحدًا أو نسختين فاتحة وداكنة؛ ارتفاع الصورة 24 px ويُستخدم title نصًا بديلاً لها.

TypeScript
// Single logo
logo: "/logo.svg"

// Light/dark mode
logo: {
  light: "/logo-light.svg",
  dark: "/logo-dark.svg"
}

أيقونة

الأيقونة المفضلة، تُضبط عبر createMetadata. تُقدَّم النسختان الفاتحة والداكنة باستخدام استعلامات الوسائط prefers-color-scheme.

TypeScript
icon: "/icon.png"

// Light/dark mode
icon: {
  light: "/icon-light.png",
  dark: "/icon-dark.png"
}

إعدادات شريط التنقل، التي يستخدمها DocsLayout وHomePage.

TypeScript
nav: {
  // Extra links in the navbar
  links: [
    { label: "Blog", href: "/blog" },
    { label: "API", href: "/api" },
  ],

  // GitHub repo as "owner/name" (adds an icon link to https://github.com/owner/name)
  github: "username/repo",
}

الصفحة الرئيسية

العنوان الرئيسي وشبكة الميزات التي يعرضها HomePage.

TSX
homepage: {
  hero: {
    title: "My Project",        // Defaults to config.title
    description: "Description", // Defaults to config.description
    cta: {
      label: "Get Started",     // Default: "Get Started"
      href: "/docs",            // Default: "/docs"
    },
  },
  features: [
    {
      title: "Feature 1",
      description: "Description of feature 1",
      icon: <Rocket className="size-5" />, // Optional React element
    },
  ],
}

يُعرض icon كما هو، لذا مرّر عنصرًا مثل أيقونة lucide-react. أما سلسلة مثل "rocket" فتُطبع كنص.

يستبدل خياران إضافيان للعنوان الرئيسي أجزاءً من العنوان الافتراضي:

  • يستبدل hero.left العنوان والوصف وكتلة التثبيت والزر بمحتوى خاص بك. ويقبل عقدة React أو دالة تُرجع واحدة.
  • يملأ hero.right النصف الأيمن من العنوان الرئيسي. ويُخفى أسفل نقطة التوقف lg.

الروابط وأيقونات التواصل الاجتماعي في تذييل HomePage، بجوار سطر حقوق النشر. يفتح كلاهما في علامة تبويب جديدة.

TSX
// import { GitHubIcon } from "onedocs";
footer: {
  links: [{ label: "Privacy", href: "/privacy" }],
  socials: [
    { label: "GitHub", href: "https://github.com/username/repo", icon: <GitHubIcon /> },
  ],
}

يستخدم كل رابط اجتماعي label اسمًا يسهل الوصول إليه.

خيارات لم يُفعّل تأثيرها بعد

يحدّد OnedocsConfig أيضًا أنواع docs وtheme وi18n، ويملأ defineConfig القيم الافتراضية لـdocs.dir وtheme.darkMode، لكن لا يقرأها أي جزء من شيفرة Onedocs (#2). لن يغيّر ضبطها شيئًا:

  • docs.dir: مجلد المحتوى هو dir الذي تمرّره إلى defineDocs في source.config.ts.
  • theme.primaryColor وtheme.darkMode: تأتي الألوان من سمة Fumadocs UI التي يستوردها الإعداد المسبق CSS، ويأتي الوضعان الفاتح والداكن من RootProvider في UI الخاص بـFumadocs.
  • i18n: لا يدعم Onedocs تعدد اللغات.

TypeScript

يوفّر لك المساعد defineConfig إكمالًا تلقائيًا كاملًا:

TypeScript
import { defineConfig, type OnedocsConfig } from "onedocs/config";

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

export default defineConfig(config);

يعيد defineConfig الكائن الذي تمرّره، بالإضافة إلى القيمتين الافتراضيتين غير المستخدمتين docs وtheme الموضحتين أعلاه.