يتيح لك Nextra إنشاء موقع في دقائق ، لذا فهو مثالي لتوزيع المستندات على فريقك.
إذا كنت معتادًا على Next.js ، فيمكنك استخدامه لتطوير موقع توثيق بسهولة. يعتني إطار عمل Nextra بالأمور الجوهرية من أجلك ؛ كل ما عليك فعله هو إضافة Markdown أو محتوى HTML وبيانات YAML أو JSON.
تجول في هذه الخطوات لإنشاء موقع توثيق باستخدام Nextra ، وهو مولد موقع ثابت يستند إلى Next.js. ستقوم بتثبيت وإعداد التبعيات الضرورية ، ثم تعلم كيفية إضافة مستندات وصفحات جديدة ، وكتابة Markdown ، وتضمين مكونات React.
متطلبات إنشاء موقع مستند باستخدام Nextra
ابدأ بتثبيت Node.js إذا لم تكن قد قمت بذلك بالفعل. ال أحدث إصدار من Node.js يأتي مع npm ، مدير حزمة العقدة ، والذي ستحتاج إلى تثبيت التبعيات لهذا المشروع.
إلى جانب Node.js ، ستحتاج إلى تثبيت ملفات شخص سخيف. تحتاج إلى Git لنشر الموقع على صفحات GitHub أو Netlify أو موفر استضافة آخر. ستحتاج أيضًا إلى محرر كود متقدم ، مثل VS Code.
تثبيت Nextra
يمكنك استخدام ملف قالب مستندات Nextra لتمهيد موقع التوثيق. قم بتشغيل موجه الأوامر وانتقل إلى الدليل الذي تريد إعداد مشروعك فيه. ثم قم بتشغيل الأمر التالي لبدء تشغيل موقع التوثيق:
استنساخ بوابة https://github.com/shuding/nextra-docs-template
سيقوم هذا الأمر بسقالة تطبيق داخل الدليل الحالي. بعد ذلك ، قم بتشغيل الأمر التالي لتثبيت التبعيات:
قالب nextra-docs-cd
تثبيت npm
بمجرد اكتمال التثبيت ، ابدأ التطبيق. قم بذلك عن طريق تشغيل الأمر التالي على جهازك الطرفي:
npm تشغيل dev
يبدأ هذا الأمر خادم تطوير على المضيف المحلي: 3000. اتبع الرابط الموجود على جهازك لعرض موقع التوثيق. يجب أن تبدو الصفحة الرئيسية كما يلي:
إذا نظرت إلى الجانب الأيسر من الصفحة ، فستجد الصفحات المسماة مقدمة و صفحة أخرى. أسفل روابط الصفحة هذه ، ستجد صفحة باسم Satori ، متداخلة داخل ملف متقدم (مجلد) الدليل. أخيرًا ، في منطقة التنقل ، ستجد روابط إلى ملف عن و اتصال الصفحات.
لفهم كيفية عمل هذه الصفحات ، يجب أن تفهم أولاً كيف يعرض Next.js الصفحات.
فهم هيكل الدليل
نظرًا لأن Nextra يستخدم إطار عمل Next.js ، فإنه يعرض كل ملف في ملف صفحات / مجلد كصفحة منفصلة.
داخل الصفحات الدليل ، ستجد أربعة ملفات قالب: about.mdx, Advanced.mdx, other.mdx، و index.mdx. يتوافق كل ملف من هذه الملفات مع صفحة على الموقع الإلكتروني ؛ على سبيل المثال، index.mdx يتوافق مع الصفحة الرئيسية. عنوان URL المضيف المحلي: 3000 / حول يتوافق مع about.mdx، وما إلى ذلك وهلم جرا.
داخل الصفحات، هناك أيضًا مجلد باسم متقدم، يحتوي على ملف واحد اسمه satori.mdx. سيكون عنوان URL لهذا الملف هو المضيف المحلي: 3000 / متقدم / ساتوري.
لاحظ كيف ينتهي كل ملف من هذه الملفات بامتداد .mdx امتداد.
ما هو MDX؟
اذا كنت تمتلك تجربة مع React، يجب أن تعرف عن JSX. هذه لغة شبيهة بلغة HTML يمكنك استخدامها لوصف واجهة المستخدم لمكونات React.
يقوم MDX بتحميل JSX وتحليله وعرضه في مستند Markdown. بفضل MDX ، يمكنك كتابة مكونات React واستيرادها إلى مستندات Markdown الخاصة بك عند الحاجة. تنتهي ملفات MDX بالملحق .mdx ويمكن أن تتضمن كلاً من Markdown و JSX.
يتيح لك MDX دمج معرفتك بـ Markdown مع React لإنشاء مكونات قابلة لإعادة الاستخدام. أنت تستطيع إنشاء وحدات CSS لتصميم المكونات. يساعدك هذا في تنظيم المكونات الخاصة بك لتحسين إمكانية القراءة وقابلية الصيانة.
كيفية تحرير الصفحات الموجودة في موقع التوثيق
لتحرير صفحة موجودة ، ما عليك سوى فتح الملف المقابل وإجراء التغييرات عليه. اللغات المدعومة هي Markdown و JSX.
على سبيل المثال ، افتح ملف index.mdx ملف واستبدال المحتوى بهذا:
# مرحبًا بكم في وثائقي
أنا سعيد برؤيتك هنا. شكرًا
## التواصل الاجتماعي الخاص بي
تابعني على [تويتر](https://twitter.com/kingchuuks) و [ينكدين](https://linkedin.com/in/kingchuks)
يستخدم هذا المثال Markdown لتنسيق المحتوى. يحتوي على عنوان من المستوى الأول وعنوان من المستوى الثاني واثنين من روابط الوسائط الاجتماعية.
احفظ الملف وقم بزيارة الصفحة الرئيسية لموقع التوثيق الخاص بك. يجب أن تبدو الصفحة الآن كما يلي:
في الجزء السفلي من الصفحة ، يمكنك أيضًا العثور على تاريخ آخر تحديث للمستند.
إضافة صفحة جديدة
قبل إضافة صفحة جديدة ، عليك أولاً تحديد ما إذا كانت الصفحة ستكون في ملف صفحات / الدليل أو داخل مجلد بداخله. استخدم المجلدات إذا كنت تريد تصنيف صفحاتك أو تطوير تسلسل هرمي.
في هذه الحالة ، قم بإنشاء صفحة مستقلة في المستوى الأعلى. افتح ملفًا باسم التثبيت. mdx في محرر التعليمات البرمجية الخاص بك والصق رمز Markdown التالي فيه:
# دليل التثبيت
اتبع هذا الدليل لتثبيت الحزمة الخاصة بي في مشروعك## 1. قم بتثبيت Node.js
لتثبيت Node.js ، قم بزيارة ملف
[موقع توثيق Node.js](https://nodejs.org/en/download)
احفظ الملف وتحقق من المتصفح. ستجد ملصق التثبيت في القائمة الجانبية. عندما تضغط على الرابط ، فإن محتوى التثبيت. mdx يعرض على الصفحة:
يمكنك تغيير التسمية وتنفيذ التكوينات الأخرى في ملف _meta.json داخل دليل الصفحات. لمعرفة المزيد حول هذا الموضوع ، راجع تنظيم الملفات قسم من وثائق نكسترا.
باستخدام مكونات React
يمكن أن تتضمن ملفات MDX JSX ، وهي اللغة التي يستخدمها React. يمكنك إنشاء مكون داخل مجلد المكونات واستيراده في أي من المستندات الموجودة على موقعك.
يمكنك مشاهدة مثال على كيفية تضمين المكونات في Markdown في ملف other.mdx ملف:
## عنصر
استيراد {useState} من "رد فعل"
استيراد الأنماط من "../components/counters.module.css"عداد التصدير الثابت = () => {
const [count، setCount] = useState (0) ،
يعود(
تم النقر على {count} مرة
)
}
<عداد />
## المكونات الخارجية
استيراد عدادات من "../components/counters"
<عدادات />
يحتوي ملف Markdown هذا على تعريف لمكون العداد. بعد ذلك ، تقوم باستيراد مكون العدادات من ملف عناصر الدليل.
إذا كنت ستستخدم نفس المكون عبر موقع التوثيق الخاص بك ، فمن الأفضل إنشائه كمكون مستقل واستيراده عندما تحتاج إليه.
تعرف على المزيد حول Markdown
لإنشاء محتوى لموقع التوثيق الخاص بك ، تحتاج إلى معرفة كيفية استخدام Markdown. والخبر السار هو أن بناء جملة Markdown سهل الفهم. عندما تجمع بين معرفتك بـ Markdown و React ، يمكنك إنشاء مواقع توثيق قوية حقًا.
