Softonic

مولد ملف README

خطوة 1 / 4 README.md
التالي

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

كيفية إعداد ملف README

  1. 1

    أضف الأساسيات

    اسم المشروع، ورابط مستودع اختياري، وشعار من سطر واحد. يصبح الاسم عنوان `#`؛ ويصبح الشعار اقتباسًا تحته.

  2. 2

    اذكر الميزات وبدءًا سريعًا

    ميزة واحدة في كل سطر (تصبح كل واحدة نقطة تعداد)، إضافة إلى مقطع بدء سريع قصير يُغلَّف داخل كتلة كود محصورة.

  3. 3

    التثبيت والترخيص والمؤلف

    يوضَع أمر التثبيت داخل كتلة كود `bash` ضمن قسم التثبيت؛ وأضف الترخيص (MIT، Apache-2.0…) وسطر مؤلف اختياري.

  4. 4

    انسخ كود Markdown

    انقر على نسخ، والصق الناتج باسم `README.md` في جذر مستودعك. ثم ادفعه، فتظهر النسخة المعروضة في صفحة المشروع.

ما الذي يحتويه ملف README الجيد؟

يتفق دليل الأسلوب الخاص بـ GitHub والمواصفة الشائعة standard-readme على الترتيب. ضع العناصر السريعة القراءة في الأعلى: فالزائر الذي يصل إلى مستودعك يقرر خلال 20 ثانية ما إذا كان سيواصل القراءة.

القسم الموقع الغرض
العنوان + الشعار السطر 1–2 # Project متبوعًا بجملة عمّا يفعله
الشارات السطر 3–5 حالة CI، إصدار npm، الترخيص، التغطية
التثبيت أعلى الصفحة أمر واحد يمكن للآخرين نسخه
الاستخدام أعلى الصفحة أصغر مقطع عملي يُنتج مخرجات
API / الخيارات الوسط جداول للرايات أو مفاتيح التهيئة أو نقاط النهاية
المساهمة قرب النهاية رابط إلى CONTRIBUTING.md، ومدونة السلوك، وأعراف طلبات الدمج
الترخيص الأخير معرّف SPDX مع رابط إلى LICENSE

الشارات التي تساعد فعلاً

تتبع عناوين shields.io نمطًا متوقعًا: https://img.shields.io/badge/<label>-<message>-<color>.svg. تشير الشارات الحية المفيدة إلى حالة البناء وإصدار الحزمة وأعداد التنزيلات، لا إلى مقاييس مظهرية. أربع شارات تكفي عادةً؛ وما زاد فهو ضجيج.

أخطاء شائعة في ملفات README

  • غياب أمر التثبيت في السطر الأول من قسم التثبيت. يبحث القراء عن npm install أو pip install؛ فإذا أخفيته خلف نص عادي، غادروا.
  • لقطات شاشة بحجم 3 ميغابايت. غيّر الحجم إلى عرض 800 بكسل واضغطها؛ سيعرضها GitHub على أي حال، لكن قراء الأجهزة المحمولة يدفعون ثمن استهلاك البيانات.
  • شارات قديمة. تُخبر شارة CI الحمراء الزوار بأن المشروع معطَّل. فإما أن تُصلح CI أو تحذف الشارة.
  • غياب الترخيص. بدون ترخيص، يكون كودك “جميع الحقوق محفوظة” افتراضيًا، ولا يمكن للشركات استخدامه.

الأسئلة الشائعة

نعم. تُعرَض كتل الكود المحصورة والقوائم النقطية والعناوين بنمط ATX (بادئة #) على GitHub وGitLab وBitbucket دون تعديل. يُوسَم أمر التثبيت ككتلة bash؛ ويُترك مقطع البدء السريع دون وسم لتحدّد أنت لغته.

بالنسبة لمعظم البيئات، استخدم README.md. واستخدم .rst فقط إذا كنت تنشر حزمة بايثون توجد وثائقها على Read the Docs وترغب في أن يعيد Sphinx استخدام الملف كصفحة وصول.

عند تقديمك رابط مستودع، يضيف المولّد شارة ترخيص ثابتة واحدة (https://img.shields.io/badge/license-<type>-blue.svg). أما الشارات الحية (حالة البناء، الإصدار، التنزيلات) فانسخ أحد أنماط عناوين shields.io والصقه بنفسك في الناتج.

لا. يُجمَّع ملف README من قيم النموذج ولا يُحفَظ شيء. أغلق علامة التبويب وتختفي البيانات.

أدوات ذات صلة

مرجع جدول ASCII

جدول ASCII كامل من 0 إلى 127 مع التمثيل العشري والست عشري والثماني والثنائي والمرجع الرقمي في HTML لكل محرف، بما في ذلك أكواد التحكم مثل NUL وLF وDEL.

مرجع أحرف HTML

قائمة قابلة للبحث بكيانات HTML، مع رموزها المسمّاة والرقمية، بالإضافة إلى خيار النسخ بنقرة واحدة للأحرف والرموز الخاصة.

مرجع اختصارات لوحة المفاتيح

ابحث في الاختصارات الافتراضية الموثقة لـ VS Code وChrome وBash مع GNU Readline على macOS وWindows وLinux.

مدقق البريد الإلكتروني

تحقق من عنوان بريد إلكتروني: فحص صياغة RFC 5322، واستعلام حي عن سجل MX، بالإضافة إلى تفاصيل الجزء المحلي والنطاق والطول. لا يتم إرسال أي بريد.

مولد EditorConfig

أنشئ ملف .editorconfig من قواعد المسافة البادئة ونهاية السطر ومجموعة الأحرف، ثم أضف قسمًا صحيحًا لكل لغة في مستودعك: Python وGo وYAML وMakefile وغيرها.

عدّاد FPS

قِس معدل الإطارات FPS في المتصفح عبر requestAnimationFrame: تنعيم، وأدنى وأقصى معدل إطارات، وحد تنبيه، ورسم بياني اختياري. يعمل محليًا بلا رفع ملفات وبلا API.

الأداة متاحة بلغات أخرى