كيفية تثبيت دوكوسوروس على لينكس

  إدارة المحتوى وتطوير الويب, إدارة نظام لينكس
تثبيت وتكوين مولد الموقع الإستاتيكي Docusaurus

Docusaurus هو مولد مواقع إستاتيكية حديث مُحسّن لإنشاء مواقع ويب للوثائق. يوفر تجربة ممتازة جاهزة للاستخدام في الوثائق مع ميزات مثل البحث والإصدار والتعددية اللغوية وغيرها. في هذا الدليل الشامل، سنمر خطوة بخطوة كيفية تثبيت Docusaurus على نظامك.

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

قبل تثبيت Docusaurus، تحتاج إلى تثبيت البرمجيات الأساسية التالية:

  • Node.js (>=12.13.0،<13.0.0 || >=14.15.0)
  • Yarn أو NPM

Node.js

تم بناء Docusaurus على React ويتطلب Node.js لتشغيله.

$ node -v

سيطبع هذا الإصدار المثبت من Node. إذا كان أقل من 12.13.0 أو بين 13.0.0 و 14.15.0، تحتاج إلى ترقية Node.js على نظامك.

لتثبيت Node.js، اذهب إلى الموقع الرسمي لـ Node.js وقم بتنزيل المثبت لنظام التشغيل الخاص بك. اتبع التعليمات لتثبيت Node.js.

Yarn أو NPM

يستخدم Docusaurus مدير حزم مثل Yarn أو NPM لإدارة تبعياته. تحتاج إلى تثبيت Yarn أو NPM.

للتحقق مما إذا كان Yarn مثبتًا:

$ yarn --version

إذا لم يكن Yarn مثبتًا، يمكنك تثبيته عبر npm:

$ npm install --global yarn

للتحقق مما إذا كان NPM مثبتًا:

$ npm --version

عادة ما يأتي NPM مضمّنًا مع تثبيت Node.js. إذا لم يكن لديك ذلك، يمكنك تثبيت NPM من الموقع الرسمي.

بمجرد التحقق من المتطلبات الأساسية، يمكننا الانتقال إلى تثبيت Docusaurus.

تثبيت Docusaurus

هناك طريقتان رئيسيتان لتثبيت Docusaurus – باستخدام القالب الكلاسيكي أو باستخدام أمر واحد. سنغطي كلا الطريقتين في هذا القسم.

1. باستخدام القالب الكلاسيكي

يوفر القالب الكلاسيكي هيكل مشروع افتراضي للبدء بسرعة مع بعض المحتوى الافتراضي. هذه هي الطريقة الموصى بها إذا كنت مبتدئًا في استخدام Docusaurus.

لتثبيت Docusaurus باستخدام القالب الكلاسيكي:

  1. أنشئ دليلًا جديدًا لموقع Docusaurus:
$ mkdir my-website
$ cd my-website
  1. قم بتشغيل سكريبت التثبيت Docusaurus مع npx:
$ npx @docusaurus/init@latest init --template classic

سيقوم هذا بتثبيت جميع التبعيات وإنشاء هيكل مشروع أولي مع بعض الوثائق النموذجية ومدونة وصفحات مخصصة.

  1. ابدأ خادم التطوير Docusaurus:
$ cd my-website
$ npm start

سيتم فتح الموقع على http://localhost:3000/ حيث يمكنك البدء في إضافة المحتوى.

هذا كل شيء! Docusaurus مثبت الآن ويعمل باستخدام القالب الكلاسيكي.

2. باستخدام أمر واحد

يمكنك أيضًا إنشاء موقع Docusaurus أساسي باستخدام أمر npx واحد:

$ npx @docusaurus/init@latest init

سيقوم هذا بتثبيت Docusaurus وإنشاء هيكل مشروع أدنى بدون أي وثائق أو محتوى نموذجي.

لتشغيل خادم التطوير:

$ cd my-website
$ npm start

هذا النهج يعطيك صفحة بيضاء لبناء موقع الوثائق الخاص بك كما تريد. ولكن ستضطر إلى إضافة الوثائق والمدونة والصفحات المخصصة بنفسك.

هيكل المشروع

بمجرد تثبيت Docusaurus ، سترى هيكل دليل مولد مثل هذا:

my-website  
├── blog
├── docs
├── src
│   ├── css
│   └── pages
├── static
├── package.json
├── sidebars.js
├── docusaurus.config.js
└── .gitignore

فيما يلي ما تكون عليه كل هذه المجلدات والملفات:

  • /blog – يحتوي على منشورات المدونة التي ستظهر في قسم المدونة.
  • /docs – يحتوي على ملفات Markdown للوثائق التي ستظهر في قسم الوثائق.
  • /src – يحتوي على مكونات React وملفات CSS والصفحات الثابتة وغيرها من التعليمات البرمجية.
  • /src/css – ملفات CSS لتنسيق الموقع.
  • /src/pages – صفحات ثابتة مثل الصفحة الرئيسية وصفحة حول واتصل بنا الخ.
  • /static – الوسائط الثابتة مثل الصور وملفات PDF إلخ تذهب هنا.
  • package.json – تبعيات NPM والنصوص البرمجية للتطوير.
  • sidebars.js – تهيئة للتنقل الجانبي الأيسر.
  • docusaurus.config.js – ملف تكوين الموقع الرئيسي.
  • .gitignore – يخبر git أي الملفات لا تتبع.

تشغيل خادم التطوير

لمعاينة موقعك محليًا، يمكنك تشغيل خادم تطوير Docusaurus:

$ npm start

سيبدأ هذا خادم التطوير على http://localhost:3000/ وإعادة بناء الموقع مع اجراءك للتغييرات.

ستقوم ميزة إعادة التحميل الساخنة بتحديث الصفحة تلقائيًا عند تعديل الملفات.

تكوين Docusaurus

الملف الرئيسي للتكوين هو docusaurus.config.js الموجود في الجذر.

يحتوي هذا الملف على إعدادات لـ:

  • بيانات الموقع الوصفية مثل العنوان والشعار وعنوان URL والرمز المصغر إلخ.
  • روابط التنقل في الرأس والتذييل.
  • موضوع الألوان.
  • CSS و JavaScript مخصصة
  • ملحقات Markdown مخصصة
  • إضافة صفحات مخصصة
  • تسجيل الوثائق والمدونة والصفحات المخصصة
  • والكثير من خيارات التكوين الأخرى.

على سبيل المثال، لتغيير عنوان الموقع:

// docusaurus.config.js
module.exports = {
  title: 'عنوان موقعي',
  tagline: 'شعار موقعي',
 
  // ...
}

راجع وثائق تكوين Docusaurus للحصول على القائمة الكاملة للخيارات.

يُستخدم ملف sidebars.js لتكوين التنقل الجانبي الأيسر للوثائق. يتيح لك تحديد أي وثائق يجب تضمينها في الشريط الجانبي وبأي ترتيب.

على سبيل المثال:

// sidebars.js
module.exports = {
  tutorialSidebar: [
    'intro',
    'install',
    {
      type: 'category',
      label: 'أدلة', 
      items: [
        'guide1',
        'guide2'
      ]
    }
  ],
}

يربط هذا المستند intro.md بعنصر الشريط الجانبي “مقدمة”، وinstall.md إلى “التثبيت” وهكذا.

توفر وثائق Docusaurus مرجعًا كاملاً لجميع خيارات التكوين.

إنشاء صفحات

لإضافة صفحة جديدة مثل “حولنا”، أنشئ ملف JSX في src/pages/about.js:

// src/pages/about.js
import React from 'react';
function About() {
  return (
    <main>
      <h1>حولنا</h1>
      <p>هذه الصفحة تخبرك عنا...</p> 
    </main>
  )
}
export default About;

سيتم عرض مكون React هذا كصفحة على العنوان /about.

وبالمثل، يمكنك إضافة صفحات مثل /contact و/pricing و/terms وما إلى ذلك.

راجع وثائق صفحات Docusaurus للمزيد من التفاصيل.

إضافة منشورات المدونة

لإنشاء منشور مدونة جديد، أضف ملف Markdown إلى الدليل blog. على سبيل المثال:

blog/welcome.md:

---
slug: welcome  
title: مرحبا بكم في مدونتي
author: جون دو
author_title: المؤلف الرئيسي
author_url: https://github.com/john
author_image_url: https://avatars3.githubusercontent.com/u/123?s=400&v=4
tags: [مرحبا, docusaurus]
---
مرحبا بكم في مدونتي الجديدة! هذه أول مقالة لي.  
سأكتب عن رحلتي مع Docusaurus وأشارك أفكاري. تابعونا للمزيد قريبا!

تسمح سمات المنشور لك بتخصيص رأس المدونة. سيقرأ Docusaurus هذه الملفات Markdown ويولد صفحة مدونة جميلة لكل منشور.

راجع وثائق مدونة Docusaurus للمزيد من التفاصيل حول إنشاء منشورات المدونة.

إضافة وثائق

لإضافة صفحات وثائق، أنشئ ملفات Markdown داخل المجلد /docs.

على سبيل المثال:

docs/intro.md:

# مقدمة
مرحبا بكم في موقع وثائقي!
سأغطي كيفية تثبيت Docusaurus ومناقشة المفاهيم الأساسية.

docs/install.md:

# التثبيت
يمكنك تثبيت Docusaurus باستخدام: 
```bash
npm init docusaurus@latest
```
هذا سيجعلك تبدأ بسرعة.

سيتم تحويل ملفات Markdown إلى HTML وعرضها بشكل جميل مع ميزات مثل شريط جانبي والتنقل والبحث وما إلى ذلك.

يمكنك استخدام العناوين والصور والروابط وكتل التعليمات البرمجية وتمييز البرمجيات وتنسيق Markdown.

راجع وثائق ميزات Markdown في Docusaurus للمزيد من التفاصيل حول ميزات Markdown المتاحة.

الترقيم

يسهل Docusaurus الحفاظ على إصدارات الوثائق مع ميزة الترقيم.

لاستخدام الترقيم، قم أولاً بتهيئة الوثائق:

$ npm run docusaurus docs:version 1.0.0

سينشئ هذا مجلد versioned_docs وينسخ محتوى المجلد docs الحالي إلى المجلد الفرعي versions/1.0.0.

بعد ذلك يمكنك إجراء تغييرات على الوثائق في المجلد docs التي ستنعكس في الإصدار latest.

لإنشاء إصدار جديد:

$ npm run docusaurus docs:version 1.0.1

سينسخ هذا المجلد docs الحالي إلى versions/1.0.1 كلقطة. يمكنك التبديل بين الإصدارات عن طريق تحديدها في مربع الإصدار المنسدل.

راجع دليل الترقيم في Docusaurus للمزيد من التفاصيل.

المظاهر

يأتي Docusaurus مع العديد من المظاهر بما في ذلك:

  • Classic – مظهر Docusaurus الكلاسيكي.
  • Bootstrap – مظهر بأنماط Bootstrap.
  • Minimal – مظهر أدنى مع CSS عادي.

يمكن تكوين المظهر في docusaurus.config.js:

module.exports = {
  // ...
  
  themeConfig: {
    navbar: {
      title: 'عنوان الموقع',
      logo: {
        alt: 'شعار الموقع',
        src: 'img/logo.svg', 
      }
    },
  },
  
  themes: ['@docusaurus/theme-classic'],
}

كما يمكنك أيضًا إنشاء مظاهر مخصصة لتصميم موقعك.

راجع وثائق المظهر للتفاصيل حول تخصيص مكونات مثل أشرطة التنقل والتذييل واللوحة اللونية وما إلى ذلك.

النشر

بمجرد اكتمال موقع Docusaurus الخاص بك، يمكنك نشره بسهولة.

أولاً، قم ببناء صفحات HTML الثابتة:

$ npm run build

سينشئ هذا مجلد build يحتوي على صفحات HTML وحزم JavaScript والوسائط.

الآن يمكنك نشر مجلد build على أي مزود استضافة إستاتيكية مثل GitHub Pages أو Vercel أو Netlify أو Azure Static Web Apps وما إلى ذلك.

على سبيل المثال، للنشر على GitHub Pages:

  1. قم بالتأكيد على مجلد build في فرع gh-pages على GitHub.
  2. قم بتعيين موقع GitHub Pages للإشارة إلى فرع gh-pages.

راجع وثائق النشر في Docusaurus للحصول على أدلة حول النشر على منصات مختلفة.

وهذا كل شيء! يجب الآن أن يكون موقع Docusaurus الخاص بك منشورًا على الإنترنت.

خلاصة

في هذا الدليل، غطينا كيفية:

  • تثبيت Docusaurus باستخدام القالب الكلاسيكي أو الأمر الواحد
  • هيكلة ملفات ومجلدات المشروع
  • تكوين Docusaurus باستخدام docusaurus.config.js
  • تشغيل خادم التطوير
  • إنشاء صفحات React
  • إضافة منشورات مدونة
  • تنظيم الوثائق باستخدام Markdown
  • ترقيم الوثائق
  • تطبيق المظاهر على موقع Docusaurus
  • نشر Docusaurus على الإنتاج

Docusaurus هو أداة رائعة لبناء مواقع ويب للوثائق باستخدام React. إنه يوفر تجربة جميلة جاهزة للاستخدام مع إمكانية تخصيص وتوسيع أي شيء. آمل أن يكون هذا الدليل مفيدًا في تعلم البدء باستخدام Docusaurus لموقع الوثائق الخاص بك.

LEAVE A COMMENT