محول README إلى PDF

ملف README.md هو مستند Markdown يشرح مشروعًا أو مستودعًا أو حزمة أو تطبيقًا أو مجموعة بيانات أو سير عمل.

تتضمن ملفات README عادةً ما يلي:

• عنوان المشروع وملخصه؛
• تعليمات التثبيت؛
• أمثلة على الاستخدام؛
• مقتطفات من أسطر الأوامر؛
• أمثلة التكوين؛
• قوائم الميزات؛
• قوائم المهام؛
• الجداول؛
• لقطات الشاشة؛
• الشارات؛
• تعليمات المساهمة؛
• معلومات الترخيص أو الدعم؛
• روابط للوثائق والإصدارات.

يعني الامتداد .md أن الملف مكتوب بلغة Markdown. يؤدي تحويله إلى PDF إلى إنشاء مستند ثابت مع الحفاظ على مصدر Markdown كإصدار قابل للتعديل.

يكون ملف PDF مفيدًا عندما يحتاج ملف README إلى الخروج من مستودعه الأصلي أو مراجعته كمستند يعتمد على الصفحات.

تشمل الأسباب الشائعة ما يلي:

• مشاركة وثائق المشروع مع عميل أو صاحب مصلحة؛
• إرفاق نظرة عامة تقنية بريد إلكتروني أو تذكرة دعم؛
• تقديم الوثائق للمراجعة أو الموافقة؛
• إنشاء لقطة غير متصلة بالإنترنت لمستودع في وقت محدد؛
• طباعة تعليمات الإعداد أو دليل تشغيل عملي؛
• أرشفة وثائق الإصدار؛
• توزيع ملف README على القراء الذين لا يستخدمون GitHub؛
• مراجعة التعليمات البرمجية الطويلة والمعادلات والمخططات والجداول في تخطيط ثابت.

يجب أن يظل ملف README الأصلي هو المصدر القابل للصيانة. أعد إنشاء ملف PDF بعد تغيير ملف README.

يدعم SolConverter عناصر Markdown الشائعة الاستخدام في ملفات README.

وتشمل هذه:

• عناوين ATX و Setext؛
• النصوص العريضة والمائلة والمشطوبة؛
• القوائم المرتبة وغير المرتبة؛
• القوائم المتداخلة؛
• قوائم مهام GFM؛
• الاقتباسات؛
• روابط Markdown والروابط التلقائية؛
• التعليمات البرمجية المضمنة؛
• كتل التعليمات البرمجية المسيجة باستخدام العلامات الخلفية (backticks) أو التلدة (tildes)؛
• تسميات لغة كتل التعليمات البرمجية؛
• جداول GFM مع المحاذاة؛
• جداول HTML الخام الآمنة؛
• أقسام details و summary؛
• عناصر kbd، و sub، و sup، و figure، و figcaption؛
• روابط العناوين؛
• بيانات YAML الفوقية (front matter) في بداية المصدر.

تظل كتل التعليمات البرمجية التي تحتوي على علامات الدولار أو محددات تشبه LaTeX رموزًا برمجية بدلاً من تفسيرها كمعادلات.

غالباً ما تحتوي ملفات README على أوامر تثبيت، وملفات تكوين، وأمثلة على واجهات برمجة التطبيقات (API)، ومتغيرات بيئة، ومقتطفات من التعليمات البرمجية المصدر.

يطبق SolConverter إبراز الصيغة باستخدام Highlight.js عند التعرف على لغة الكتل البرمجية المسيجة. تحتفظ اللغات غير المعترف بها بالمصدر الأصلي بأمان.

تستخدم كتل الكود خطًا أحادي المسافة مخصصًا وأسلوب طباعة يفصلها عن الشرح المحيط بها. يظل الكود من اليسار إلى اليمين حتى في ملف README مكتوب من اليمين إلى اليسار.

قد يحتوي ملف README التقني على صيغ، أو مصفوفات، أو رموز علمية، أو تعبيرات احتمالية، أو كيمياء.

يدعم SolConverter مخرجات MathJax SVG لمحددات الرياضيات الشائعة في Markdown، وبيئات معادلات AMS، و Presentation MathML، و Content MathML الأساسي، وتعبيرات الكيمياء المكتوبة باستخدام \ce{...}.

تتضمن الرياضيات المدعومة ما يلي:

• تعبيرات مضمنة باستخدام $...$ و \(...\)؛
• تعبيرات معروضة باستخدام $$...$$ و \[...\]؛
• بيئات المعادلات والمحاذاة؛
• الكسور والجذور والمجاميع والتكاملات والنهايات والمصفوفات؛
• وحدات الماكرو على مستوى المستند؛
• التعبيرات الإضافية الطويلة التي تحتاج إلى فاصل أسطر.

يتم عرض الرياضيات كرسومات SVG لتظل حادة في ملف PDF. يمكن للرياضيات غير الصالحة أن تتراجع محليًا دون إيقاف بقية ملف README تلقائيًا.

تستخدم ملفات README بشكل متكرر المخططات البيانية لشرح الهندسة المعمارية أو التسلسل أو الحالة أو سير العمل أو علاقات المكونات.

يتم عرض كتل Mermaid المسيجة المدعومة محليًا كـ SVG. يتم دعم ZenUML من خلال تكامل Mermaid مدمج. يتم تقييد المخططات بعرض الصفحة المتاح ومعالجتها بشكل مستقل.

إذا كان أحد المخططات غير صالح، فسيقوم المحول بإدراج تراجع محلي مع المصدر ومواصلة عرض الأقسام المتبقية.

لا يتم دعم PlantUML و Graphviz و D2 و WaveDrom و BPMN و Nomnoml و TikZ الكامل حاليًا ولا ينبغي الإعلان عنها في هذه الصفحة.

يدعم المحول صور HTTP و HTTPS العامة وصور بيانات base64 الصالحة بتنسيقات PNG و GIF و JPEG و WebP و SVG.

يتم قياس الصور لتناسب الصفحة والحفاظ على نسبة العرض إلى الارتفاع. يمكن الاحتفاظ بالأشكال والتسميات التوضيحية والنصوص البديلة والعناوين والأبعاد الآمنة والمحاذاة.

ومع ذلك، تستخدم العديد من ملفات README الخاصة بالمستودعات مسارات نسبية مثل:

./images/screenshot.png
docs/architecture.svg
../assets/demo.gif

لا يقوم سير عمل الرفع الحالي بحزم مجلد المستودع أو حل تلك الأصول النسبية تلقائيًا. قم بتحويلها إلى عناوين URL عامة للصور أو صور بيانات base64 مدعومة قبل إنشاء ملف PDF.

تستخدم الشارات عادةً عناوين URL عامة للصور ويمكن عرضها عندما يكون مضيف الصورة متاحًا للجمهور. إذا تعذر تحميل شارة أو صورة، يقوم SolConverter بإدراج نائب محلي ويستمر في التحويل.

يمكن أن تكون روابط Markdown داخل ملف README روابط مطلقة، أو نسبية للمستودع، أو روابط لأجزاء من الصفحة.

تظل روابط HTTP و HTTPS المطلقة ذات مغزى خارج المستودع. بينما الروابط النسبية مثل ./docs/setup.md أو ../CONTRIBUTING.md قد لا تشير إلى وجهة مفيدة بعد أن يصبح ملف README ملف PDF مستقلًا.

قبل مشاركة ملف PDF:

• استبدل الروابط النسبية المهمة بعناوين URL مطلقة عامة؛
• اكتب الإرشادات الهامة بدلاً من الاعتماد فقط على الملفات المرتبطة؛
• تحقق من روابط العناوين بعد العرض؛
• تأكد من أن المستند لا يزال منطقيًا دون التنقل في المستودع؛
• قم بتضمين معلومات الإصدار أو تاريخ النشر عندما يكون الهدف من ملف PDF هو الأرشفة.

لا يزال ملف README الخاص بـ GitHub عبارة عن ملف Markdown، ولكن قد يضيف GitHub سياق مستودع غير موجود في الملف المرفوع نفسه.

يمكن لملف PDF حفظ هياكل GFM المدعومة مثل الجداول وقوائم المهام والرموز البرمجية المسيجة والروابط التلقائية والعناوين. ويمكنه أيضًا عرض تعبيرات MathJax ومخططات Mermaid المدعومة.

لا يقوم المحول بإعادة إنتاج كل عنصر من عناصر واجهة مستخدم GitHub. علامات تبويب المستودع، وعدد المشكلات (issues)، وعناصر واجهة مستخدم الإصدار، ومحددات الفروع، والبطاقات المنشأة ديناميكيًا، وعناصر صفحة GitHub الأخرى ليست جزءًا من مصدر Markdown.

للحصول على أنظف ملف PDF مستقل، تأكد من تضمين هوية المشروع، وسياق الإصدار، والروابط الهامة في المستند نفسه.

يمكن أن يعمل ملف PDF الخاص بـ README كوثيقة تسليم تقنية موجزة عندما يحتاج القارئ إلى:

• نظرة عامة على المشروع؛
• خطوات التثبيت والإعداد؛
• أمثلة على الأوامر؛
• متطلبات التكوين؛
• مخططات الهندسة المعمارية؛
• أمثلة على واجهات برمجة التطبيقات (API)؛
• ملاحظات تشغيلية؛
• تعليمات استكشاف الأخطاء وإصلاحها؛
• تفاصيل المساهمة أو الدعم.

بالنسبة لمجموعات الوثائق الكبيرة، تعامل مع ملف README كمستند دخول بدلاً من إجبار كل دليل تشغيل في ملف واحد. يمكن أن يظل ملف PDF الناتج عن ملف README طويل جداً مفيدًا، ولكن قد يكون من الأسهل صيانة المستندات المنفصلة والتنقل بينها.

تتغير المستودعات بمرور الوقت. يؤدي تحويل ملف README إلى PDF إلى إنشاء لقطة مقروءة مرتبطة بإصدار أو تسليم أو مراجعة أو حدث رئيسي.

قبل الأرشفة:

1. أضف إصدار المشروع أو الحزمة؛
2. قم بتضمين التاريخ ذي الصلة أو معرف الإصدار؛
3. تحقق من الأوامر وأمثلة التكوين؛
4. استبدل الروابط المؤقتة؛
5. راجع الصور والمخططات والمعادلات؛
6. قم بإنشاء وفحص ملف PDF النهائي؛
7. قم بتخزين ملف PDF بجانب سجل الإصدار.

ملف PDF الناتج هو لقطة ثابتة، وليس بديلاً لملف README الخاضع للتحكم في الإصدار.

يمكن أن تحتوي ملفات README على تعليمات HTML خام، وعناوين URL لصور بعيدة، وكتل تالفة.

يقوم SolConverter بتطهير الـ HTML المعروض، ويزيل النصوص البرمجية ومعالجات الأحداث، ويرفض عناوين URL غير الآمنة، ويقيد الـ HTML الخام بقائمة مسموحات، ويحد من امتدادات الجداول، ويطبق سياسة أمان محتوى مقيدة، ويحظر طلبات المتصفح خارج سياسة الصور المسموح بها.

يتم حظر الملفات المحلية، ووجهات المضيف المحلي (localhost)، وعناوين IP الخاصة، وعناوين URL التي تبدأ بـ javascript:، ومخططات الموارد غير المدعومة. يتم التعامل مع الصور والمعادلات والمخططات غير الصالحة محليًا حيثما أمكن ذلك حتى يتمكن باقي ملف README من مواصلة العرض.

يطبق SolConverter تخطيط مستند متسقًا على ملفات README.

يستخدم نموذج الويب الحالي:

• حجم الصفحة A4؛
• الاتجاه الرأسي؛
• هوامش مدارة لإنتاج مخرجات مقروءة؛
• ترقيم الصفحات current / total؛
• عنوان مخرج يعتمد على اسم ملف README؛
• الخلفيات المطبوعة.

التخطيط الرأسي مصمم للقراءة العامة. قم دائمًا بمعاينة الجداول العريضة والأكواد البرمجية قبل التنزيل.

استخدم هذه الصفحة التي تركز على README عندما يكون المصدر هو README الخاص بالمشروع وتحتاج إلى إرشادات حول كتل التعليمات البرمجية، وهياكل GFM، والشارات، والصور النسبية للمستودع، وروابط المستودع.

استخدم محول Markdown إلى PDF الرئيسي للتقارير والمستندات الرياضية والملاحظات التقنية والمقترحات والمستندات متعددة اللغات وملفات .md العامة.

تستخدم كلتا الصفحتين نفس إمكانية التحويل الأساسية، لكنهما تخدمان مهام مستخدم مختلفة وتقدمان إرشادات إعداد مختلفة.

• تحويل أي ملف Markdown إلى PDF
• تحويل PDF إلى Markdown
• تحويل HTML إلى Markdown
• تحويل Word إلى Markdown
• تصفح جميع أدوات تحويل الملفات إلى Markdown