﷽
إن رغبت بصنع موقع بسيط وجميل بسرعة فائقة لتضع فيه شروحا تقنية أو مكانا لجمع الأفكار أو دليل استخدام فإن برمجية م ك دوكس ماتريال mkdocs-material تُعد خياراً مميزاً.
ميزات ام كه دوكس ماتريال mkdocs-material:
- تعتمد صيغة مارك داون المبسطة لتحرير الصفحات 🇲 🇩
- تدعم اللغة العربية ولغات اليمين لليسار 🇷 🇹 🇱
- يتوفر فيها محرك بحث داخلي
- تولّد صفحات ساكنة static html مما يسهل استضافتها على أبسط استضافة حتى github و gitlab
- ملف إعدادات واحد
mkdoks.yml
- مفتوحة المصدر
- ألوان سمة متنوعة ودعم الوضع الليلي
- دعم لغات كثيرة
- إمكان إضافة زر لاختيار اللغة للتوجيه لموقع بلغة أخرى
سبب اختياري لسمة ماتريال على ام كه دوكس الأساسية
السبب الرئيسي لأختياري سمة ماتريال هو أنها تدعم الاتجاه من اليمين لليسار RTL بشكل ممتاز وتذكر ذلك في المستندات الخاصة به وذلك يحصل بمجرد تحديد اللغة كالعربية
البرمجية يطورها Martin Donath
تثبيت ام كه دوكس ماتريال
للثبيت نبدأ كما أنصح دائما باستخدام pipenv ثبت هذه الأداة المفيدة وأنشأ دليلا جديدا ليكون فيه العمل.
داخل الدليل الجديد أكتب:
pipenv shell
ذلك سينشئ بيئة وهمية معزولة عن باقي النظام وهذا أسلم للعمل وأفضل.
ثم نثبت البرمجية:
pipenv install mkdocs-material
بناء الموقع
إنشاء ملفات الموقع
بعد التثبيت ننشئ ملفات الموقع هكذا
mkdocs new .
النقطة تعني أنشئ الملفات في الدليل الحالي ويمكنك تحدي دليل آخر إذا رغبت.
سنجد الآن مجموعة من الملفات أنشئت كنموذج يمكن تعديله هي:
.
├─ docs/
│ └─ index.md
└─ mkdocs.yml
تفعيل السمة
نعدل ملف الإعدادات mkdocs.yml لتفعيل سمة ماتيريال:
theme:
name: material
عرض الموقع
يمكنك تفعيل البرمجية وتجربتها محليا باستخدام:
mkdocs serve
حيث ستعطيك رابط لمعاينة الموقع محليا.
$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
INFO - Documentation built in 0.24 seconds
INFO - [08:45:47] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO - [08:45:47] Serving on http://127.0.0.1:8000/
INFO - [08:45:47] Browser connected: http://127.0.0.1:8000/
INFO - [08:45:48] Browser connected: http://127.0.0.1:8000/
سترى محتوى الصفحة الأساسية index.md.
وهذه صورة لصفحة بعد ترجمة المحتوى أما الاتجاه يمين يسار فكما ترون يعمل بشكل جيد دون تعديل.
الآن عندك صفحة يمكنك فيها وضع كل شيء بصيغة MarkDown وبعض من نصوص HTML. وهذا الموقع الآن يمكنك استخدامه لتخزين مستنداتك بطريقة مرتبة بصورته الحالية ويمكنك إنشاء صفحات إضافية بجانب index.md وستجد أنها ظهرت في العمود اليميني مباشرة.
بناء صفحات ثابتة من الموقع
الموقع جاهز للاستخدام المحلي لكن لتستطيع رفعه على استضافة عليك توليد صفحات ثابتة لرفعها وهذا يتم بالأمر:
mkdocs build
ستجد أنه قد أنشئ مجلد جديد تحت اسم site فيه المحتوى الثابت للموقع والذي يمكنك رفعه لأي استضافة أو حتى استضافته على IPFS فهي مجرد صفحات HTML ساكنة لاتحتاج ل PHP أو نود جي اس أو بايثون في الموقع.
طريقة سهلة جدا ومجانية لعمل موقع على الانترنت
يمكنك استضافة الموقع على صفحات gitlab أو github مجانا كل ماعليك هو أن تذهب لمستودع مجهز مسبقا وتشتقه fork إلى مستودعك الخاص ثم تعدل عليه كما يحلو لك مباشرة أو تسحبه إلى جهازك عن طريق git clone، وعندما تنتهي ترفعه مجددا.
للاستضافة على gitlab.io يمكن الاشتقاق من المستودع الجاهز المعرّب هذا الذي يُشّغل النسخة العربية من ام كه دوكس ماتيريال
أو الاشتقاق من المستودع هذا والذي فيه mkdocs الأساسية والقيام بالتعديلات المطلوبة لتفعيل ماتيريال واللغة العربية:
يعطيك gitlab موقع بصيغة your_name.gitlab.io/your_project
حيث your_name اسم المستخدم و your_project رمز المشروع في gitlab.
بعد الاشتقاق
بعد الاشتقاق لتفعيل موقعك عليك تعديل اسم المشروع إلى your_user.gitlab.io حيث your_user هو أسم المستخدم الخاص بك أو أسم المجموعة لمن فعّل المجموعات ويكون ذلك في Settings > General .
مثال عن تعديل الإسم
كذلك عليك تعديل ملف mkdocs.yml وتغيير العنوان إلى موقعك، مثال:
site_name: My Docs by GitLab Pages
site_url: https://uak.gitlab.io/
site_dir: public
theme:
name: material
language: ar
لمعرفة رابط موقعك
يمكنك معرفة رابط الموقع باستخدام Settings > Pages :
حذف الربط مع المستودع المشتق منه
بعد كل اشتقاق يبقى هناك إشارة للمستودع المشتق منه وبما أن ذلك مطلوب فقط في حال رغبتك بالمساهمة في المستودع الأصلي فإنه يمكنك إزالة الربط من Settings > General > Advanced:
استخدام نطاقك الخاص
ربما يرغب المستخدم باستخدام نطاقه الخاص كأنه اشترى عنوان example.com مثلا ويريد أن يكون هو بوابة الموقع بدل gitlab.io، ذلك ممكن لكن نترك ذلك للتعليمات الرسمية من gitlab حاليا على الرابط التالي (انجليزي):
GitLab Pages custom domains | GitLab Docs
روابط مفيدة
شُكر
أود أن أشكر مجتمع بيتكوين كاش على تقديمه التمويل اللازم لكتابة هذه المقالات التعليمية ونشر المعرفة البرمجية والتوعية في مجالات العملات الرقمية في العالم العربي وتطويره لبرمجيات حرة تمكن آليات التمويل الجماعي غير المركزي ك Flipstarter و IPFS Flipstarter الذي يمكن أي شخص من عمل حملة تمويل جماعي دون الحاجة لوسيط أو حتى استضافة ودون الحاجة لمحفظة خاصة.
