Blog

كيفية استخدام Nextra Docs ونشره على Vercel: دليل خطوة بخطوة

Ashley Goolam

Ashley Goolam

12 يونيو 2025

كيفية استخدام Nextra Docs ونشره على Vercel: دليل خطوة بخطوة

إذا كنت ترغب في إنشاء موقع ويب أنيق وعصري للتوثيق بسهولة، فإن Nextra Docs هي واحدة من أفضل الأدوات المتاحة. تم بناء Nextra فوق Next.js، وتتيح لك كتابة التوثيق الخاص بك بصيغة Markdown أو MDX، وتخصيص المظهر والشكل، ونشره بسهولة—خاصة على Vercel. في هذا المقال، سنتعرف خطوة بخطوة على كيفية إعداد موقع Nextra Docs من الصفر ونشره على Vercel مجانًا.

💡
هل تريد أداة رائعة لاختبار واجهات برمجة التطبيقات (API Testing) تولد توثيق API جميل؟

هل تريد منصة متكاملة وشاملة لفريق المطورين لديك للعمل معًا بـ أقصى إنتاجية؟

Apidog يلبي جميع متطلباتك، ويحل محل Postman بسعر معقول جدًا!
button

ما هي Nextra Docs؟ صديقك المفضل لبناء التوثيق

Nextra docs هو إطار عمل يعتمد على Next.js يجعل إنشاء مواقع التوثيق أمرًا سهلاً للغاية. يتعلق الأمر كله بمحتوى Markdown (أو MDX) مع سمة توثيق مسبقة البناء تحتوي على التنقل والبحث وجدول المحتويات جاهزًا للاستخدام. إليك سبب روعة nextra docs:

يثني المستخدمون على nextra docs لـ "إتقانه بدون تهيئة" وعمليات النشر على Vercel. هل أنت مستعد لبناء موقعك؟ لنبدأ!

لماذا تستخدم Nextra Docs مع Vercel؟

Nextra docs مثالي للمطورين، الشركات الناشئة، أو المشاريع مفتوحة المصدر التي تحتاج إلى توثيق احترافي بسرعة. اقترانه بـ Vercel—موطن Next.js—يعني:

لقد قمت بنشر موقع تجريبي على Vercel، وكان مباشرًا في أقل من 5 دقائق—سلس كالحرير!

كيفية إعداد Nextra Docs: دليل خطوة بخطوة

لنقم بإنشاء موقع nextra docs من الصفر باستخدام موجه تطبيق Next.js. اتبع الخطوات، وسيكون لديك موقع محلي يعمل في حوالي 20 دقيقة!

1. إنشاء مشروع Next.js جديد

npx create-next-app my-nextra-docs
next js project options
cd my-nextra-docs

2. تثبيت تبعيات Nextra Docs

ثبّت الحزم الأساسية لـ nextra docs:

npm install next react react-dom nextra nextra-theme-docs

3. تحديث سكربتات package.json

تأكد من أن package.json يتضمن هذه السكربتات (عادة ما يتم إضافتها بواسطة create-next-app):

"scripts": {
  "dev": "next",
  "build": "next build",
  "start": "next start"
}

"dev": "next --turbopack"
package.json
npm run dev

زر http://localhost:3000 للتأكد من أن تطبيق Next.js يعمل.

next js home page

قبيح :( لكنه يعمل! الآن دعنا نحاول إصلاح هذا.

4. تهيئة Nextra Docs

import nextra from 'nextra'

const withNextra = nextra({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.js'
})

export default withNextra({
  async redirects() {
    return [
      {
        source: '/',
        destination: '/resources',
        permanent: true
      }
    ]
  }
})

"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", "next.config.mjs", ".next/types/**/*.ts"]

5. إعداد مكونات MDX

import { useMDXComponents as getThemeComponents } from 'nextra-theme-docs'

const themeComponents = getThemeComponents()

export function useMDXComponents(components) {
  return {
    ...themeComponents,
    ...components
  }
}

6. تحديث تخطيط التطبيق

import { Footer, Layout, Navbar } from 'nextra-theme-docs'
import { Banner, Head } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-docs/style.css'
 
export const metadata = {
  // Define your metadata here
  // For more information on metadata API, see: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
}
 
const banner = <Banner storageKey="some-key">Nextra 4.0 is released 🎉</Banner>
const navbar = (
  <Navbar
    logo={<b>Nextra</b>}
    // ... Your additional navbar options
  />
)
const footer = <Footer>MIT {new Date().getFullYear()} © Nextra.</Footer>
 
export default async function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html
      // Not required, but good for SEO
      lang="en"
      // Required to be set
      dir="ltr"
      // Suggested by `next-themes` package https://github.com/pacocoursey/next-themes#with-app
      suppressHydrationWarning
    >
      <Head
      // ... Your additional head options
      >
        {/* Your additional tags should be passed as `children` of `<Head>` element */}
      </Head>
      <body>
        <Layout
          banner={banner}
          navbar={navbar}
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs"
          footer={footer}
          // ... Your additional layout options
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}

7. إضافة صفحات التوثيق

home page 404 error message
/app/resources
  /page.mdx

لأغراض الاختبار، أضفت:

# Resources

Resources related to various topics and fields.

## Learning
- [Build Your Own X](https://github.com/codecrafters-io/build-your-own-x): Master programming by recreating your favourite technologies from scratch.

## Useful Articles
- [CSR vs SSR vs SSG vs ISR: A Deep Dive for Modern Web Development](csr-vs-ssr-vs-ssg-vs-isr-a-deep-dive-for-modern-web-development-33kl#:~:text=Here's%20a%20quick%20summary%3A,as%20SPAs%2C%20CSR%20is%20perfect.)
- [The Art of Comand Line](https://github.co./jlevy/the-art-of-command-line)

لكن المحتوى لا يحتاج أن يكون معقدًا ويمكن أن يكون بسيطًا مثل:

# Getting Started

Hi <Your Name>! Welcome to your **nextra docs** site:)

- Easy Markdown editing
- Automatic navigation
- Search and TOC built-in
nextra home page

انطلق - عدّل هذه الصفحة، أضف المزيد من الصفحات، وجرّب جميع الميزات مثل الوضع الداكن/الفاتح. القوة بين يديك، والخيارات لا حصر لها!

light and dark mode

نشر Nextra Docs على Vercel

الآن، لننشر موقع nextra docs الخاص بك مباشرة على Vercel—الأمر سهل للغاية لأن Vercel مبني لـ Next.js.

8. رفع الكود الخاص بك إلى GitHub

git init
git add .
git commit -m "Initial nextra docs"
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main

9. النشر على Vercel

varcel

تخصيص موقع Nextra Docs الخاص بك

هل تريد جعل موقع nextra docs الخاص بك مميزًا؟ جرب هذه الخيارات:

لقد أضفت مكون تنبيه مخصصًا إلى توثيقي—بدا احترافيًا في 10 دقائق!

استكشاف الأخطاء وإصلاحها ونصائح لـ Nextra Docs

custom nextra documentation example

لماذا Nextra Docs وVercel هما الثنائي المثالي

Nextra docs يجعل التوثيق ممتعًا ببساطة Markdown وسرعة Next.js. عمليات النشر بنقرة واحدة من Vercel والاستضافة المجانية تحسم الأمر. بالتأكيد، قد يربك موجه التطبيق المبتدئين في Next.js، لكن توثيق Nextra قوي. مقارنة بـ Docusaurus، تشعر nextra docs بأنها أخف وأكثر حداثة.

هل أنت مستعد لإطلاق توثيقك؟ ابنِ موقع nextra docs الخاص بك وانشره على Vercel—أنا متحمس لرؤية إبداعك! وبالتأكيد لا تنسَ التحقق من Apidog.

💡
هل تريد أداة رائعة لاختبار واجهات برمجة التطبيقات (API Testing) تولد توثيق API جميل؟

هل تريد منصة متكاملة وشاملة لفريق المطورين لديك للعمل معًا بـ أقصى إنتاجية؟

Apidog يلبي جميع متطلباتك، ويحل محل Postman بسعر معقول جدًا!
button

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات

التسجيل مجانًاتحميل