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 من قيم النموذج ولا يُحفَظ شيء. أغلق علامة التبويب وتختفي البيانات.

أدوات ذات صلة

مولّد إعدادات Webpack

أنشئ ملف webpack.config.js لـ webpack 5 لمشاريع JavaScript الخالصة أو React أو Vue: مع TypeScript وBabel وCSS أو Sass والصور وHtmlWebpackPlugin وخادم التطوير وسطر npm install.

محوّل ترميز ملفات النصوص

حوّل النص بين UTF-8 وUTF-16 وLatin-1 وWindows-1252 وترميزات أخرى لإصلاح الأحرف المشوّهة.

مُحقق تنسيق XSD

قم بالتحقق من وثيقة XML وفقًا لمخطط XSD، وعرض أي اختلافات بين العناصر وأنواعها مع تحديد أرقام السطور بدقة.

مولّد ملف .gitignore

اجمع قواعد استبعاد المشروع لـ Laravel وNode.js وPython وRails. انسخ الناتج أو نزّل ملف ZIP يحتوي على .gitignore، مع إبقاء القواعد الشخصية منفصلة.

مرجع جدول ASCII

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

أداة إزالة التشفير في لغة جافا سكريبت (JavaScript Deobfuscator)

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

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