Tutorial overview

دليل الدروس

يقدم هذا القسم لمحة عامة عن ملفات config.json المستخدمة في وثائق JSQuarto، مع التركيز تحديداً على مجلد tutorials. ملف config.json' يعمل كملفات تكوين تساعد على هيكلة وتنظيم الوثائق، في حين يحتوي مجلدالدروس` على ملفات Markdown لمختلف الدروس.

The tutorials Folder

مجلد “الدروس” داخل دليل التوثيق مكرس لاستضافة دروس حول مختلف المواضيع ذات الصلة بمنصة JSQuarto. يحتوي هذا المجلد على مجموعة من ملفات Markdown، يمثل كل منها درسا فرديا.

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

يمكن تنظيم مجلد “الدروس” في مجلدات فرعية لزيادة تصنيف ودروس ذات صلة بالمجموعة. وهذا يساعد المستخدمين على تحديد مواقع الدروس التي يحتاجونها بسهولة والوصول إليها بناء على اهتماماتهم أو متطلباتهم المحددة.

من خلال هيكلة الدروس داخل مجلد “الدروس” باستخدام Markdown، يمكن للمساهمين المساهمة بدروس جديدة، تحديث الوثائق الموجودة، وضمان أن تظل الوثائق شاملة وسهلة الاستعمال.

ملفات son` ومجلد “الدروس التعليمية” يمكنان من بنية وثائق منظمة تنظيماً جيداً ويمكن الوصول إليها، مما يسمح للمستخدمين بالتنقل واستكشاف وثائق منصة JSQuarto بسهولة.

Overview of config.json Files

يؤدي ملف `config.json’ في وثائق JSQuarto دورا حاسما في تنظيم وتصنيف المحتوى. يحدد هذا الملف هيكل الوثائق ويوفر بيانات فوقية لكل قسم أو برنامج تعليمي أو موضوع. فهي تسمح للقائمين على الصيانة والمساهمين بالتنقل في الوثائق وإدارتها بسهولة عن طريق تحديد العناوين وإنشاء هياكل متداخلة وربط المواضيع ذات الصلة.

باستخدام ملف `config.json’ ، يمكن إنشاء الوثائق وتحديثها ديناميكيا استنادا إلى الهيكل المحدد. وهذا يجعل من الأسهل المحافظة على الاتساق، وتتبع التغييرات، وإضافة محتوى جديد.

The .json configuration

لنشرح كيف تعمل هذه البنية من خلال النظر إلى ملف config.json' في مجلدtutorials /’. يحدد هذا الملف هيكل قسم الدروس في الوثائق، بما في ذلك العناوين، وصلات الوصف لكل درس تعليمي.

{
  "سجل التغييرات": {
    "العنوان: "التغيير"
  },
  "environment_setup": {
    "العنوان": "إعداد البيئة"
  },
  "المساهمة": {
    "العنوان": "المساهمة"
  }
}

في هذا المثال ، يحدد ملف ‘json’ عناوين وعلاقات الأقسام الرئيسية داخل وثائقك. الأقسام ممثلة ككائنات، مع كل كائن له مفتاح فريد و ’title”` في زوج القيمة الرئيسية.

  1. changelog represents the “Changelog” section. يحدد زوج القيمة الرئيسية “title” عنوان هذا القسم كـ “التغيير”.

  2. environment_setup represents the “Environment Setup” section. يحدد زوج القيمة الرئيسية “title” عنوان هذا القسم بأنه “إعداد البيئة”.

  3. contributing represents the “Contributing” section. يحدد زوج القيمة الرئيسية “title” عنوان هذا القسم كـ “التغيير”.

بهذه البنية، سيحتوي مجلد الوثائق الخاص بك على ملفات Markdown منفصلة لكل قسم، يتم تسميتها وفقًا للمفاتيح الموجودة في ملف .json. على سبيل المثال:

“يامل - الوثائق/ - docs / - changelog.md - environment_setup.md - contributing.md - tutorials.json


كل ملف Markdown سيتطابق مع قسم في وثائقك ويجب أن يحتوي على المحتوى ذي الصلة لذلك القسم.

تذكر أن تقوم بتحديث ملف '.json' كلما قمت بإضافة أو تعديل الأقسام للتأكد من أن هيكل التوثيق يعكس بدقة محتوى وثائقك.


### Nested `.json` configuration for tutorials
<hr>
لهيكلة الدروس وإنشاء دروس متداخلة داخل وثائقك، يمكنك استخدام ملف '.json' لتحديد التسلسل الهرمي والعلاقات بين الدروس. إليك مثال على كيفية هيكلة الدروس باستخدام ملف `.json`:

“يامل
{
    "المشرفين": {
        "العنوان": "دليل تقني للقائمين"،
        "الأطفال": {
            "reviewing_pr": {
                "title": "استعراض طلبات السحب"
            },
            "ci_workflow": {
                "title": "CI Workflow "
            },
            "الأسرار_and_security": {
                العنوان : "الوصول السري/الإدارة السرية"
            },
            "نشر الدليل": {
                "عنوان": "دليل النشر"
            }
        }
    },
    "المساهمة": {
        "title": "المساهمة في المشروع"،
        "الأطفال": {
            "adding_a_course": {
                "title": "إضافة دورة"
            },
            "api_project_structure": {
                "title": "بنية مشروع API
            },
            "Improving_documentation": {
                العنوان : "تحسين التوثيق"
            },
            "project_structure": {
                "عنوان": "بنية المشروع"
            },
            "raising_issues": {
                العنوان: "إثارة المشاكل"
            },
            "raising_pr": {
                "عنوان": "رفع طلبات الجذب"
            }
        }
    },
    "عرض": {
        "title": "استعراض المشروع"
    }
}

وفي هذا المثال، يمثل ملف json هيكلا للتوثيق يتألف من قسمين رئيسيين: “الدليل التقني للمتعينين” و”الدليل التقني لمطوري API”. لكل قسم مجموعته الخاصة من الدروس التي تمثل ككائنات متداخلة.

  1. تعريف الأقسام أو الفئات الرئيسية على أنها الكائنات ذات المستوى الأعلى داخل ملف `json’، مثل “المشرفين” و “المساهمة”.

  2. ضمن كل قسم رئيسي، قدم مفتاح “عنوان” لتحديد عنوان أو عنوان ذلك القسم. () على سبيل المثال، “الدليل التقني للقائمين” و”الدليل التقني لمطوري API”.

  3. إضافة مفتاح ‘الأطفال’ داخل كل قسم رئيسي لتحديد الدروس المتداخلة. يتم تمثيل كل برنامج تعليمي ككائن ثانوي داخل كائن الأطفال. وقد لا تحتوي جميع الدروس على دروس للأطفال، ومن الأمثلة على ذلك دروس “مراجعة”. بما أنه ليس لديه أطفال فإن البرنامج سيبحث فقط عن ملف “review.qmd” وليس مجلد “عرض”

  4. لكل برنامج تعليمي، قم بتوفير مفتاح فريد كمفتاح الكائن، مثل “reviewing_pr” و “ci_workflow”.

  5. ضمن كل كائن تعليمي، قم بإدراج مفتاح “title” لتحديد العنوان أو العنوان لذلك البرنامج التعليمي المحدد.

على هذا المثال هنا ما سيبدو عليه هيكل المجلد بافتراض أن المجلد الجذري هو دروس/:

“يامل - دروس/دروس - المشرفون/ - المشرفون - الاستعراض_pr.qmd - ci_workflow.qmd - الأسرار_and_security.qmd - نشر_guide.qmd

        - المساهمة/
            - api.md
            - api_structure.md
            - api_authentication_flow.qmd
            - jwt_token_management.qmd
            - rbac_handler_flow.qmd
        
        - review.qmd
          
        - config.json

```

وفي هذا الهيكل:

  • ملف التكوين ‘json’ موجود في المجلد ‘دروس التعليمية’
  • يحتوي مجلد “الدروس” على مجلدات فرعية تمثل أقسام أو فئات مختلفة من الدروس.
  • كل قسم أو مجلد فئة، مثل ‘المشرفينو 'المساهمة، يحتوي على ملفات’.qmd’ لدروس فردية.

الهيكل المتداخل يسمح لك بتنظيم الدروس هرمياً ، مما يجعل من الأسهل التنقل والبحث عن دروس محددة استناداً إلى موضوعها أو فئتها.

من المهم ملاحظة أن بنية البرنامج التعليمي لا تسمح إلا بمستوى واحد من التعش. هذا يعني أنه يمكنك الحصول على الأقسام الرئيسية ودروسها، ولكن لا يمكنك إنشاء المزيد من المجلدات المتداخلة داخل الدروس.