Rspress 2.0 إصدار: ترقية جديدة تركز على التجربة و AI

نحن سعداء بالإعلان عن الإصدار الرسمي لـ Rspress 2.0!

Rspress هو مولد مواقع ثابتة يعتمد على Rsbuild، مصمم كأداة لمواقع الوثائق للمطورين. منذ إطلاقه الرسمي في عام 2023، قامت Rspress 1.x بإصدار 144 إصدارًا، بمشاركة 125 مساهمًا في تطوير المشروع. يختار المزيد من المطورين Rspress، مستفيدين من أداء التجميع الفعال، والتوجيه القائم على الاتفاق، ومعاينة مكتبة المكونات، لبناء مواقع وثائقية جميلة وموثوقة.

استنادًا إلى ملاحظات واقتراحات المجتمع، تقدم Rspress 2.0 تحسينات في جمالية الموضوع، و AI-native، و تجربة تطوير الوثائق، و الاستخدام مع Rslib.

لماذا Rspress 2.0

لقد عالجت Rspress 1.x مشكلة أداء تجميع إطار عمل مواقع الوثائق، ولكن لا تزال هناك بعض المشكلات التي تؤثر على التجربة الأساسية كأداة لتطوير الوثائق. الإصدار 2.0 لن يركز فقط على تحسين أداء التجميع، بل سيعالج أيضًا جوانب أخرى من تجربة موقع الوثائق:

• أسلوب الموضوع: مجموعة من الموضوعات الافتراضية الأكثر جاذبية، مع توفير طرق متعددة لتخصيص الموضوع، مما يحل مشكلة عدم وجود واجهة برمجة تطبيقات مستقرة لتخصيص الموضوع في 1.x.
• AI-native: الوثائق لا تخدم فقط القراء البشريين، بل تحتاج أيضًا إلى أن تُفهم وتُستخدم بشكل أفضل من قبل الوكلاء. الآن، يحتوي Rspress على وظيفة توليد llms.txt و SSG-MD المشتقة من SSG، لتوليد محتوى Markdown عالي الجودة لقراءته الوكلاء.
• تجميع حسب الطلب، بدء فوري: تم تفعيل lazyCompilation بشكل افتراضي، مع وظيفة preload للموارد عند التحويم على الروابط، مما يبني الملفات المطلوبة فقط عند الوصول إلى مسارات معينة، مما يحقق بدءًا فوريًا بغض النظر عن حجم المشروع.
• تسليط الضوء على الشيفرة باستخدام Shiki: تم دمج Shiki بشكل افتراضي، لإكمال تسليط الضوء على بناء الجملة أثناء البناء، مع دعم تبديل الموضوعات، وتوسيع المحولات، مثل @rspress/plugin-twoslash، مما يوفر تأثيرات عرض أكثر ثراءً لكتل الشيفرة.
• تجربة تطوير الوثائق: تحسين HMR لملفات nav.json، meta.json وغيرها، وإضافة مخطط json لتلميحات الشيفرة داخل IDE؛ تم تفعيل وظيفة فحص الروابط الميتة بشكل افتراضي؛ إضافة بناء جملة كتل الشيفرة للملفات، مع دعم استيراد الملفات الخارجية؛ دعم استخدام @rspress/plugin-preview و @rspress/plugin-playground في نفس الوقت.
• دمج Rslib: الآن يمكنك اختيار Rspress كأداة وثائق عند استخدام create-rslib لإنشاء مشروع مكتبة مكونات، لبناء موقع وثائق المكونات بسرعة.

ميزات 2.0 الجديدة

موضوع جديد

تلقى الموضوع الافتراضي 2.0 ترقية شاملة، تم تصميمه بواسطة المصمم @Zovn Wei، حيث تم تحسين الجوانب البصرية وتجربة القراءة بشكل كبير، وكل مكون يمكن استبداله بشكل مستقل، مما يوفر قابلية تخصيص عالية.

تخصيص الموضوع

وفقًا لمستوى التخصيص من المنخفض إلى العالي، هناك أربع طرق لتخصيص الموضوع: متغيرات CSS، أسماء فئات BEM، إعادة تصدير ESM، وإخراج المكونات.- متغيرات CSS: الموضوع الجديد يكشف عن المزيد من متغيرات CSS، تغطي ألوان الموضوع، كتل التعليمات البرمجية، أنماط الصفحة الرئيسية، وغيرها. يمكنك في صفحة متغيرات CSS معاينة وتعديل جميع متغيرات CSS بشكل تفاعلي، وبعد العثور على التكوين الذي يعجبك، يمكنك نسخه مباشرة لاستخدامه في المشروع.

• أسماء فئات BEM: تستخدم المكونات المدمجة الآن معيار تسمية BEM. هذا خيار قديم جداً، لكنه قرار مدروس بعناية. يمكن للمستخدمين تعديل الأنماط بدقة من خلال محددات CSS، مما يجعل هيكل HTML أكثر وضوحًا.
• إعادة تصدير ESM: إذا كانت التعديلات على CSS لا تلبي احتياجات التخصيص، يمكن إجراء تخصيص أعمق باستخدام JS. في theme/index.tsx، باستخدام إعادة تصدير ESM، يمكنك تجاوز أي مكون مدمج في Rspress.
• إخراج المكونات: يمكنك استخدام الأمر الجديد rspress eject [component]، والذي سيقوم بنسخ كود المصدر للمكون المحدد إلى دليل theme/components/، يمكنك تعديل هذا الكود بحرية، حتى يمكنك تسليمه مباشرة للذكاء الاصطناعي لتعديله، لتحقيق تخصيص عميق.

شريط التنقل، شريط الجانب tag

حقق Rspress 2.0 مكون Tag، والآن يمكنك استخدام خاصية tag في frontmatter، لإجراء علامات UI في شريط الجانب أو شريط التنقل.

دعم متعدد اللغات مدمج

في الإصدار 1.x، كان Rspress يحتوي فقط على نصوص باللغة الإنجليزية، وإذا كنت تستخدم لغات أخرى مثل zh، كان يجب تكوين جميع النصوص، مما يجعل الأمر معقدًا. الآن، يحتوي موضوع 2.0 على نصوص ترجمة للعديد من اللغات مثل zh، en، ja، ko، ru، وسيقوم النظام تلقائيًا بإجراء "Tree Shaking" بناءً على تكوين اللغة، فقط حزم النصوص واللغات التي تستخدمها.

دعم llms.txt

الآن، قام Rspress بدمج القدرة على توليد llms.txt في النواة، وحقق قدرة جديدة على SSG-MD (توليد المواقع الثابتة إلى Markdown).

في إطار العمل الأمامي الديناميكي القائم على React، غالبًا ما توجد مشكلة صعوبة استخراج المعلومات الثابتة، ويواجه Rspress نفس التحدي. يسمح Rspress للمستخدمين بتعزيز تعبير الوثائق من خلال مقاطع MDX، مكونات React، Hooks، وTSX routing وغيرها من الميزات الديناميكية. لكن هذه المحتويات الديناميكية تواجه المشاكل التالية عند تحويلها إلى نص Markdown:

• إدخال MDX مباشرة إلى الذكاء الاصطناعي سيحتوي على الكثير من ضوضاء بناء الجملة البرمجية، ويفقد محتوى مكونات React.
• تحويل HTML إلى Markdown غالبًا ما يكون غير فعال، وجودة المعلومات يصعب ضمانها.

لحل هذه المشكلة، قدم Rspress 2.0 ميزة SSG-MD. هذه ميزة جديدة تمامًا، تشبه توليد المواقع الثابتة (SSG)، لكن الاختلاف هو أنها تقوم برسم صفحاتك كملفات Markdown، بدلاً من ملفات HTML، وتولد ملفات llms.txt وllms-full.txt ذات الصلة.

تمييز كتل التعليمات البرمجية في وقت تجميع ShikiRspress 2.0 تستخدم Shiki بشكل افتراضي لتسليط الضوء على الكود. مقارنةً بخطة تسليط الضوء في وقت التشغيل prism في 1.x، تقوم Shiki بمعالجة تسليط الضوء أثناء وقت الترجمة.

• تدعم أنماط مواضيع متعددة، مثل إمكانية التبديل والمعاينة التفاعلية لموضوعات Shiki المختلفة في صفحة متغيرات CSS.
• في الوقت نفسه، تسمح Shiki أيضًا باستخدام محولات مخصصة للتوسع في الكتابة، مثل twoslash وغيرها.
• استيراد لغات البرمجة حسب الحاجة، دون زيادة تكاليف وقت التشغيل وحجم الحزمة.
• تعتمد على بناء جملة TextMate لتحقيق تسليط الضوء الدقيق المتوافق مع VS Code.

تحسين أداء البناء

يتم تشغيل Rspress 2.0 بواسطة Rsbuild و Rspack 2.0 في إصدار المعاينة، وفي الوقت نفسه تم تفعيل الترجمة حسب الحاجة والتخزين المؤقت الدائم بشكل افتراضي.

الترجمة حسب الحاجة

تم تفعيل dev.lazyCompilation بشكل افتراضي، حيث يتم تجميع الصفحة فقط عند زيارتها، مما يزيد بشكل كبير من سرعة بدء التطوير، حتى تحقيق بدء تشغيل في مللي ثانية. كما أن Rspress نفذت استراتيجية تحميل مسبق للتوجيه، حيث يتم تحميل الصفحة المستهدفة مسبقًا عند تمرير الماوس فوق الرابط، مما يحقق تجربة تطوير بدون فقدان.

التخزين المؤقت الدائم

تم تفعيل التخزين المؤقت الدائم بشكل افتراضي في 2.0، مما يعيد استخدام نتائج الترجمة السابقة في بدء التشغيل الساخن، مما يزيد من سرعة البناء بنسبة 30%-60%. وهذا يعني أنه بعد التشغيل الأول لـ rspress dev أو rspress build، ستزداد سرعة البدء بشكل ملحوظ في المرات اللاحقة.

تجربة تطوير الوثائق

تفعيل فحص الروابط المعطلة بشكل افتراضي

تم تفعيل وظيفة فحص الروابط المعطلة بشكل افتراضي في Rspress 2.0. خلال عملية البناء، سيتم الكشف تلقائيًا عن الروابط غير الصالحة في الوثائق، مما يساعدك على اكتشافها وإصلاحها في الوقت المناسب.

كتل كود الملفات

يمكنك استخدام خاصية file="./path/to/file" للإشارة إلى ملفات خارجية كمحتوى لكتل الكود، مما يسمح لك بالحفاظ على كود المثال في ملفات منفصلة.

استخدام meta أكثر مرونة في preview

@rspress/plugin-preview الآن يعتمد على خاصية meta، مما يجعله أكثر مرونة، ويمكن أيضًا دمجه مع كتل كود الملفات.

Rslib & Rspress

عند استخدام create-rslib لإنشاء مشروع، يمكنك الآن اختيار أداة Rspress. هذا يتيح لك بناء موقع وثائق مصاحب بسرعة أثناء تطوير مكتبة المكونات، لكتابة تعليمات استخدام المكونات، وعرض مرجع API، أو معاينة تأثيرات المكونات في الوقت الحقيقي.

المزيد من الإضافات الرسمية لـ Rspress

أضافت Rspress 2.0 العديد من الإضافات الرسمية:

• @rspress/plugin-algolia: يدعم استبدال البحث المدمج في Rspress بـ Algolia DocSearch
• @rspress/plugin-twoslash: يضيف تلميحات نوعية لكتل كود TypeScript
• @rspress/plugin-llms: يوفر القدرة على إنشاء llms.txt للمشاريع التي لا تدعم SSG وSSG-MD
• @rspress/plugin-sitemap: ينشئ تلقائيًا ملفات Sitemap، لتحسين SEO

تغييرات كبيرة

الانتقال من Rspress 1.x

إذا كنت مستخدمًا لمشروع 1.x، فقد أعددنا وثيقة انتقال مفصلة لمساعدتك في الترقية من 1.x إلى 2.0. يمكنك استخدام وظيفة "نسخ Markdown" في الصفحة مباشرة، وإدخالها إلى وكيل الترميز الذي تستخدمه عادةً (مثل Claude Code وغيرها) لإكمال الانتقال.Rspress 2.0 يتطلب إصدار Node.js 20+، وإصدار React 18+. [[HTMLPLACEHOLDER0]] إصدار Rspress 2.0 هو مجرد نقطة انطلاق جديدة. بعد هذا الإصدار، ستستمر Rspress في التطور: [[HTMLPLACEHOLDER1]] استخدم أو قم بالترقية إلى Rspress 2.0 الآن، واستمتع برحلة تطوير مستندات جديدة! [[HTMLPLACEHOLDER2]]