الإعداد
توضع الإعدادات العامة للموقع في onedocs.config.ts في جذر مشروعك. مرّر الكائن المُصدَّر إلى DocsLayout وHomePage وcreateMetadata لتقرأه. يُحدَّد مكان المحتوى في source.config.ts، وليس هنا (راجع البدء).
الإعداد الأساسي
import { defineConfig } from "onedocs/config";
export default defineConfig({
title: "My Project",
description: "Documentation for My Project",
});
هذا هو الحد الأدنى. كل ما عداه اختياري.
مثال كامل
أيقونات الميزات هي عناصر React، لذا يجب أن يكون ملف الإعداد الذي يستخدمها ملف .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، كما تستخدمه الصفحة الرئيسية عنوانًا رئيسيًا ونصًا في سطر حقوق النشر بالتذييل.
title: "My Project"
الوصف
وصف قصير. يستخدمه createMetadata للوصف الوصفي، وتعرضه الصفحة الرئيسية أسفل العنوان الرئيسي عند عدم تعيين homepage.hero.description.
description: "Documentation for My Project"
الشعار
يستبدل العنوان في شريط التنقل. استخدم مسارًا واحدًا أو نسختين فاتحة وداكنة؛ ارتفاع الصورة 24 px ويُستخدم title نصًا بديلاً لها.
// Single logo
logo: "/logo.svg"
// Light/dark mode
logo: {
light: "/logo-light.svg",
dark: "/logo-dark.svg"
}
أيقونة
الأيقونة المفضلة، تُضبط عبر createMetadata. تُقدَّم النسختان الفاتحة والداكنة باستخدام استعلامات الوسائط prefers-color-scheme.
icon: "/icon.png"
// Light/dark mode
icon: {
light: "/icon-light.png",
dark: "/icon-dark.png"
}
التنقل
إعدادات شريط التنقل، التي يستخدمها DocsLayout وHomePage.
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.
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، بجوار سطر حقوق النشر. يفتح كلاهما في علامة تبويب جديدة.
// 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 إكمالًا تلقائيًا كاملًا:
import { defineConfig, type OnedocsConfig } from "onedocs/config";
const config: OnedocsConfig = {
title: "My Project",
};
export default defineConfig(config);
يعيد defineConfig الكائن الذي تمرّره، بالإضافة إلى القيمتين الافتراضيتين غير المستخدمتين docs وtheme الموضحتين أعلاه.