أنشئ Markdown لشارة README مع نص بديل

يعيد المولّد Markdown كاملًا، وعنوان URL للصورة، والنص البديل المقروء في حقول منفصلة. وهو يعالج المسافات والواصلات والشرطات السفلية وعلامات الترقيم والأقواس المربعة ذات الدلالة في Markdown معالجة آمنة، لذلك تبقى البنية صحيحة حتى عندما تصف التسميات مهام بناء فعلية أو قنوات إصدار. استخدم أداة المتصفح لإنشاء شارة سريعة، أو استدعِ API الحتمية عندما تُجمَّع وثائقك آليًّا.

اختر نصًّا موجزًا يعبّر عن الحالة

تجيب الشارة المفيدة عن سؤال صغير ومحدد بنظرة واحدة. ضع الفئة على اليسار بوصفها التسمية، ثم ضع قيمتها الحالية على اليمين بوصفها الرسالة. فمثلًا، يسهل فهم تسمية مثل البناء مع رسالة مثل ناجح أكثر من جملة طويلة مضغوطة داخل صورة واحدة. يربط النص البديل الناتج القيمتين بنقطتين رأسيتين، وبذلك يحصل مستخدمو قارئات الشاشة على العلاقة الأساسية نفسها التي يعرضها التصميم بصريًّا. احرص على أن تبقى القيمتان واضحتين من دون اللون، لأن اللون وحده لا ينبغي أن يحمل حالة أساسية. يزيل المولّد المسافات المحيطة، لكنه يحافظ على الصياغة وحالة الأحرف المقصودتين. وتُرفض التسميات والرسائل الفارغة بدل إنشاء صورة مربكة بنصف فارغ. إذا كانت الشارة تمثل عملية آلية، فاستخدم مفردات ثابتة عبر الإصدارات كي تظل الفروق قابلة للقراءة ويعرف المستخدمون موضع المعلومة. يتيح حقل alt_text كذلك لخط الوثائق فحص الوصف الميسّر أو إعادة استخدامه بصورة مستقلة عن سلسلة Markdown النهائية.

افهم كيفية تكوين عنوان صورة Shields

ترمّز شارات Shields الثابتة التسمية والرسالة واللون داخل مسار الصورة. ولهذا المسار قواعد خاصة للفصل: تتحول المسافات إلى شرطات سفلية، وتُضاعف الشرطة السفلية الحرفية، كما تُضاعف الواصلة الحرفية حتى لا تختلط بالفواصل بين أجزاء الشارة. وتُرمّز بقية علامات الترقيم ترميزًا مئويًّا للحصول على عنوان URL صالح. تطبق هذه القدرة التحويلات بصورة حتمية وتعيد العنوان الناتج مع Markdown. يمكن توفير لون سداسي عشري مسبوق بعلامة التجزئة؛ فتُحذف العلامة قبل إدخال اللون في المسار. ويمكن أيضًا تمرير أسماء ألوان Shields مثل brightgreen مباشرة. لا تتصل الخدمة بـShields ولا تتحقق من طريقة عرض اسم لون بعينه، بل تنشئ مرجع الصورة المتعارف عليه فقط. لذلك يظل التنفيذ سريعًا وخاصًّا ومناسبًا لعمليات بناء الوثائق من دون اتصال. وبما أنه لا يحدث أي طلب شبكي، فالنتيجة الناجحة تعني أن الصياغة أُنشئت بطريقة صحيحة، لا أن الصورة البعيدة جرى تنزيلها. ويمكنك حفظ الناتج في قالب وترك قارئ README النهائي يطلب الصورة بالطريقة المعتادة.

أدرج Markdown الناتج ونفّذ استخدامه آليًّا بأمان

انسخ حقل markdown إلى README أو قالب طلب دمج أو صفحة حزمة أو أي مستند Markdown يسمح بالصور البعيدة. يستخدم الناتج صيغة الصورة المعروفة، فيظهر النص الميسّر بين قوسين مربعين وعنوان Shields بين قوسين دائريين. تُفلت الأقواس المربعة والشرطات المائلة العكسية داخل النص الظاهر، فلا تؤدي صياغة يقدمها المستخدم إلى إغلاق قسم النص البديل قبل أوانه. في مسار عمل آلي، أرسل حقول الإدخال الثلاثة كلما عرضت الوثائق، ثم اكتب قيمة markdown المعادة في المكان المقصود. ولأن الخوارزمية لا تعتمد على ساعة أو عشوائية أو حالة أو شبكة، فإن المدخلات المتطابقة تنتج دائمًا مخرجات متطابقة، وهذا يحافظ على استقرار الملفات المولدة في نظام إدارة الإصدارات. يُفضّل أن تحتفظ بمكان الشارات وترتيبها في قالبك بدل تجميع README كامل بهذه القدرة. فهي تنشئ عنصر شارة واحدًا لكل طلب عن قصد، ولا تعدّل المستودعات ولا تفحص نتائج البناء ولا تقرر ما ينبغي أن تقوله الحالة. توفر العملية السابقة الحقيقة، بينما يتولى هذا المولّد الترميز والعرض الصحيحين فقط.