ما هو Mintlify Docs وكيفية استخدامه: دليل المبتدئين

هل تجد صعوبة في إنشاء وثائق أنيقة وسهلة الاستخدام لا تشعرك بالملل؟ قل مرحباً بـ Mintlify، المنصة الأصلية للذكاء الاصطناعي التي تجعل بناء وثائق مذهلة سهلاً مثل كتابة منشور مدونة. مع أكثر من 28 ألف نجمة على GitHub وعملاء مثل Stripe، تقدم Mintlify ميزات تفاعلية وأدوات ذكاء اصطناعي وتكاملات سلسة للارتقاء بمستوى وثائقك. في هذا الدليل للمبتدئين، سأرشدك خلال تثبيت Mintlify، وإعداد نطاق مخصص، والاستفادة من استيعاب الذكاء الاصطناعي، ودمج خادم MCP، وإضافة ترجمات، واستخدام OpenAPI لوثائق API. سواء كنت مطوراً أو قائد فريق، ستتمكن من نشر وثائق احترافية في وقت قصير. هل أنت مستعد لجعل التوثيق ممتعاً؟ هيا بنا نتعمق!

💡

قبل أن نبدأ، إذا كنت تتطلع إلى تبسيط تطوير واجهة برمجة التطبيقات (API)، فإن Apidog يقدم منصة شاملة لتصميم واختبار وتوثيق واجهات برمجة التطبيقات. بفضل واجهته البديهية وميزاته القوية، فهو مثالي لكل من المبتدئين والمطورين ذوي الخبرة. والأفضل من ذلك كله، يمكنك البدء مجاناً! (apidog)

button

ما هو Mintlify؟ قوتك الخارقة في التوثيق

Mintlify هي منصة توثيق حديثة تساعد المطورين على إنشاء وثائق جميلة وتفاعلية ومتوافقة مع محركات البحث (SEO) بأقل جهد. تم تصميمها للفرق والمشاريع مفتوحة المصدر، وتقوم بتحويل ملفات Markdown وMDX إلى صفحات متجاوبة، وتدعم تكامل GitHub، وتحتوي على ميزات مدعومة بالذكاء الاصطناعي مثل توليد الأكواد والترجمات. تشمل المزايا الرئيسية ما يلي:

محرر WYSIWYG: قم بتحرير الوثائق في واجهة مستندة إلى المتصفح.
مكونات تفاعلية: أضف علامات تبويب، ومقتطفات أكواد، ومساحات تجريب لواجهات برمجة التطبيقات (API).
تحسين بالذكاء الاصطناعي: عزز البحث وإمكانية الوصول باستخدام استيعاب الذكاء الاصطناعي.
قابل للتخصيص: قم بتعديل السمات والخطوط والتنقل عبر ملف docs.json.

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

تثبيت وإعداد Mintlify

البدء مع Mintlify سهل للغاية، وستحتاج إلى Node.js، وواجهة سطر الأوامر (CLI) الخاصة بـ Mintlify، وحساب GitHub. إليك كيفية البدء، بناءً على الدليل الرسمي.

1. تثبيت المتطلبات الأساسية:

Node.js: قم بتنزيل الإصدار 16.6 أو أعلى من https://nodejs.org/. تحقق باستخدام node -v.
حساب GitHub: قم بالتسجيل في github.com إذا لم يكن لديك حساب بالفعل.
VS Code: اختياري ولكنه موصى به للتحرير. احصل عليه من code.visualstudio.com.

2. استنساخ (Clone) حزمة البداية (Starter Kit):

في الطرفية (terminal)، قم باستنساخ حزمة البداية الخاصة بـ Mintlify من هنا:

git clone https://github.com/mintlify/starter-kit
cd starter-kit

سيؤدي هذا إلى إنشاء مشروع يحتوي على مجلد docs يتضمن ملفات MDX وملف docs.json للإعدادات.

3. تثبيت واجهة سطر الأوامر (CLI) لـ Mintlify:

قم بتثبيت واجهة سطر الأوامر عالمياً:

npm install -g mintlify-cli

تحقق باستخدام mintlify-cli --version (مثال: mintlify-cli version 3.1.25).

4. تشغيل المعاينة المحلية:

في مجلد starter، ابدأ خادم التطوير:

mintlify-cli dev

سيؤدي هذا إلى فتح معاينة على http://127.0.0.1:3000. إذا كان المنفذ 3000 مشغولاً، فسيحاول استخدام 3001 أو استخدم --port 3333 للتخصيص (مثال: mintlify-cli dev --port=3333).

5. تحرير وثائقك:

افتح المشروع في VS Code (code .).
انتقل إلى docs/introduction.mdx وقم بتغيير حقل "title" إلى "Welcome to My Docs!" (مرحباً بك في وثائقي!). احفظ التغييرات، وسيتم تحديث المعاينة على الفور.
استكشف ملف docs.json لتعديل الخطوط أو الألوان أو تمكين الوضع الداكن. على سبيل المثال:

{
  "name": "My Docs",
  "theme": "prism",
  "colors": { "primary": "#3498db" }
}

تحقق من https://mintlify.com/docs للإعدادات العامة مثل الأيقونات أو الشعارات.

لقد قمت بإعداد هذا في أقل من 10 دقائق وكان لدي موقع مباشر مع تعديلاتي - سلس للغاية!

إعداد نطاق مخصص لـ Mintlify

هل تريد أن تكون وثائقك متاحة على docs.yourcompany.com بدلاً من نطاق فرعي على mintlify.app؟ Mintlify يجعل إعداد النطاقات المخصصة سهلاً.

1. الوصول إلى الإعدادات:

قم بتسجيل الدخول إلى لوحة تحكم Mintlify الخاصة بك على mintlify.com.
انتقل إلى Settings (الإعدادات) > Custom Domain (النطاق المخصص).

2. إضافة نطاقك:

أدخل نطاقك (مثال: docs.yourcompany.com).
اتبع تعليمات DNS لمزودك (مثال: Namecheap، GoDaddy):
أضف سجل CNAME: docs → cname.vercel-dns.com.
لمستخدمي Cloudflare، قم بتمكين أمان HTTPS "full strict".
إذا كنت تستخدم Vercel، أضف سجل TXT للتحقق (يظهر في لوحة التحكم).

3. انتظر حتى يتم النشر (Propagation):

قد تستغرق تغييرات DNS ما يصل إلى 48 ساعة، ولكنها غالباً ما تتم بشكل أسرع. تحقق من نطاقك في المتصفح للتأكيد.

لقد قمت بإعداد نطاق مخصص لموقع تجريبي، وكان يعمل خلال بضع ساعات - شعور احترافي بكل المقاييس!

الاستفادة من استيعاب الذكاء الاصطناعي مع Mintlify

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

1. تمكين استيعاب الذكاء الاصطناعي:

في لوحة تحكم Mintlify، انتقل إلى Products (المنتجات) > AI Chat (دردشة الذكاء الاصطناعي).
قم بتبديل مفتاح استيعاب الذكاء الاصطناعي للتشغيل. هذا يقوم بفهرسة وثائقك للبحث بالذكاء الاصطناعي دون إعداد إضافي.
يقوم Mintlify تلقائياً بإنشاء خريطة موقع /llms.txt لنماذج اللغات الكبيرة (LLMs) لفهرسة المحتوى الخاص بك بكفاءة.

2. اختبار البحث بالذكاء الاصطناعي:

في وثائقك المباشرة، استخدم شريط البحث أو دردشة الذكاء الاصطناعي (إذا تم تمكينها عبر docs.json).
اسأل: "كيف أقوم بالمصادقة مع واجهة برمجة التطبيقات (API)؟" سيقوم الذكاء الاصطناعي بسحب الأقسام ذات الصلة، مثل صفحة المصادقة الخاصة بك.

3. التحسين باستخدام إصلاحات الذكاء الاصطناعي:

في محرر الويب، يقترح الذكاء الاصطناعي إصلاحات بناء الجملة لأخطاء MDX (مثال: مكونات مشوهة). قم بتمكين هذا في Settings (الإعدادات) > Editor (المحرر).

لقد جربت البحث بالذكاء الاصطناعي على موقع نموذجي، ووجد وثائق واجهة برمجة التطبيقات (API) الخاصة بي على الفور - أسرع بكثير من التصفح اليدوي!

دمج خادم MCP مع Mintlify

بروتوكول سياق النموذج (MCP) يتيح لتطبيقات الذكاء الاصطناعي التفاعل مع وثائقك أو واجهات برمجة التطبيقات الخاصة بك. يقوم Mintlify بإنشاء خادم MCP لربط المحتوى الخاص بك بنماذج اللغات الكبيرة (LLMs).

1. تثبيت واجهة سطر الأوامر (CLI) لـ MCP:

قم بتشغيل:

npm i @mintlify/mcp

في لوحة تحكم Mintlify، انتقل إلى Products (المنتجات) > MCP Server (خادم MCP) للحصول على أمر التثبيت الفريد الخاص بك.

2. تكوين خادم MCP:

ابحث عن External Admin Key (مفتاح المشرف الخارجي) و Chat API Key (مفتاح واجهة برمجة تطبيقات الدردشة) في Settings (الإعدادات) > API Keys (مفاتيح واجهة برمجة التطبيقات).
قم بتشغيل أمر واجهة سطر الأوامر (CLI) من لوحة التحكم، وأدخل المفاتيح عند المطالبة بذلك.
قم بتبديل مفتاح OpenAPI Access (الوصول إلى OpenAPI) لتضمين نقاط نهاية واجهة برمجة التطبيقات (يتطلب مواصفات OpenAPI).

3. استخدام خادم MCP:

تقوم واجهة سطر الأوامر (CLI) بإخراج أمر لبدء تشغيل الخادم الخاص بك (مثال: npm --prefix ~/.mcp/mintlify start).
اختبر باستخدام عميل MCP مثل Windsurf، مع الاستعلام: "ابحث في وثائقي عن مصادقة واجهة برمجة التطبيقات (API)". سيعيد الخادم نتائج منظمة.

تثبيت خادم Mintlify MCP محلياً

لتشغيل خادم Mintlify MCP على جهازك:

قم بتشغيل:

npx @mintlify/mcp add mintlify

تجاوز مطالبة رمز Bearer بالضغط على Enter.
حدد عميل MCP الخاص بك (مثل Claude Desktop، Windsurf) المثبت محلياً.
سيتم تثبيت الخادم وتكوينه للعميل الذي اخترته.

مثال: لقد استخدمت Windsurf، وأعطتني الطرفية (terminal):

node C:\User\Me.mcp\mintlify\src\index.js

قم بتشغيل هذا الأمر، انقر فوق أيقونة الأدوات في عميلك، وتحقق من توفر الخادم.
بدلاً من ذلك، في لوحة تحكم Mintlify، انتقل إلى MCP Server (خادم MCP) للعثور على أمر لإضافة الخادم إلى عميل MCP الخاص بك (مثال: Apple DB).

نموذج مطالبة (Prompt) (في Windsurf):

Write a help doc about this feature based on this PRD, in the style and tone of AppleDB docs.

أو، لتنسيق متوافق مع Mintlify:

Write this in markdown using Mintlify components like anchors.

انسخ الإخراج من عميل mcp الخاص بك (مثل windsurf أو claude desktop)، الصقه في محرر الويب الخاص بـ Mintlify، قم بالتبديل إلى الوضع المرئي، وقم بالمعاينة!

لقد قمت بإعداد خادم MCP، وسمح لمساعدي الذكي بالاستعلام عن وثائقي كالمحترفين - أشياء مستقبلية!

إضافة ترجمات إلى وثائق Mintlify

هل تريد وثائقك بلغات متعددة؟ الترجمات المدعومة بالذكاء الاصطناعي في Mintlify تجعل عملية التوطين (localization) سهلة للغاية.

1. تمكين الترجمات:

في لوحة تحكم Mintlify، انتقل إلى Settings (الإعدادات) > Translations (الترجمات).
أضف لغة (locale) (مثال: es للإسبانية) واختر إصداراً للترجمة.
يقوم Mintlify بترجمة وثائقك تلقائياً، مع مزامنة التحديثات مع الإصدار الرئيسي.

2. تخصيص الترجمات:

قم بتحرير ملفات MDX المترجمة في مجلد اللغة (locale folder) الخاص بمستودعك (repo) (مثال: docs/es/).
المحتوى الثابت مثل "هل كانت هذه الصفحة مفيدة؟" يتكيف مع اللغة تلقائياً.

3. اختبار الترجمة:

في وثائقك المباشرة، قم بتبديل اللغات عبر القائمة المنسدلة للإصدار (تم تكوينها في docs.json).

تحقق من أن العناوين والمحتوى يعكسان اللغة الهدف (مثال: "¡Bienvenidos!" للإسبانية).

لقد أضفت ترجمات إسبانية، وأصبحت وثائقي جاهزة للعالمية في دقائق - مكسب كبير لإمكانية الوصول!

استخدام Mintlify مع VS Code

هل تقوم بتوثيق الأكواد في VS Code؟ إضافة Mintlify تجعل الأمر سهلاً للغاية!

1. تثبيت إضافة Mintlify:

افتح سوق الإضافات (Extension Marketplace) في VS Code.
ابحث عن "Mintlify" وانقر على Install (تثبيت).

2. توليد التوثيق:

قم بتمييز الكود الذي تريد توثيقه.
انقر على أيقونة Mintlify في الشريط الجانبي واختر Generate Docs (توليد الوثائق)، أو استخدم الاختصار Ctrl + ..
يقوم Mintlify بكتابة التوثيق تلقائياً.

نموذج كود:

test("@e2e wait for api response", async ({ page }) => {
  const sidemenuPage = new SideMenuPage(page);
  await sidemenuPage.interceptApiLink.click();
  const response = await page.waitForResponse((response) =>
    response.url().includes("/comments")
  );
  expect(response.status()).toBe(200);
  await page.getByText("CREATE post").isVisible();
});

التوثيق المُولد:

The code block is a test case that checks if the API response is received successfully.

لقد قمت بتوثيق نص برمجي للاختبار، ونجح Mintlify في كتابة الوصف بدقة - بلا جهد!

استكشاف ميزات Mintlify

Mintlify مليء بالأدوات لجعل وثائقك تتألق. إليك كيفية الارتقاء بالمستوى:

محرر الويب (Web Editor): قم بتحرير الوثائق في المتصفح عبر Dashboard (لوحة التحكم) > Editor (المحرر). اكتب / للمكونات مثل علامات التبويب أو الملاحظات (callouts).
السمات والأنماط (Themes and Styling): قم بتخصيص الألوان أو الخطوط أو الشعارات في ملف docs.json. جرب سمات مثل prism أو default.
تكامل GitHub (GitHub Integration): قم بتثبيت تطبيق Mintlify على GitHub لنشر التغييرات تلقائياً. تحقق من لوحة التحكم للإعداد.
التحليلات (Analytics): تتبع تفاعل المستخدمين في Dashboard (لوحة التحكم) > Analytics (التحليلات) لمعرفة الصفحات الشائعة أو معدلات الخروج.
المكونات (Components): أضف قوائم قابلة للطي (accordions)، مجموعات أكواد (code groups)، أو رسوم بيانية Mermaid عبر MDX. راجع https://mintlify.com/docs للاطلاع على أمثلة.

لقد قمت بتعديل السمة الخاصة بي وأضفت علامات تبويب، مما جعل وثائقي تبدو بتصميم احترافي في أقل من ساعة!

خلاصة: رحلتك مع Mintlify تبدأ الآن

عمل رائع - لقد أطلقت العنان لقوة Mintlify لإنشاء وثائق مذهلة وجاهزة للذكاء الاصطناعي! من تثبيت واجهة سطر الأوامر (CLI) إلى إعداد النطاقات المخصصة، واستيعاب الذكاء الاصطناعي، وخوادم MCP، والترجمات، ومساحات تجريب OpenAPI، أنت الآن جاهز لبناء وثائق تبهر المستخدمين. جرب مكونات جديدة، أضف المزيد من اللغات، أو وثّق واجهات برمجة التطبيقات الخاصة بك باستخدام APIdog! توثيق سعيد!

button