README to PDF কনভার্টার

একটি README.md ফাইল হলো একটি Markdown ডকুমেন্ট যা কোনো প্রজেক্ট, রিপোজিটরি, প্যাকেজ, অ্যাপ্লিকেশন, ডেটাসেট বা ওয়ার্কফ্লো ব্যাখ্যা করে।

README ফাইলে সাধারণত অন্তর্ভুক্ত থাকে:

• একটি প্রজেক্ট টাইটেল এবং সারাংশ;
• ইনস্টলেশন নির্দেশাবলী;
• ব্যবহারের উদাহরণ;
• কমান্ড-লাইন স্নিপেট;
• কনফিগারেশন উদাহরণ;
• ফিচার বা বৈশিষ্ট্যের তালিকা;
• টাস্ক লিস্ট বা কাজের তালিকা;
• টেবিল বা সারণী;
• স্ক্রিনশট;
• ব্যাজ;
• অবদানের নির্দেশাবলী;
• লাইসেন্স বা সহায়তা সংক্রান্ত তথ্য;
• ডকুমেন্টেশন এবং রিলিজের লিঙ্ক।

.md এক্সটেনশন মানে হলো ফাইলটি Markdown-এ লেখা। এটিকে PDF-এ রূপান্তর করা হলে একটি নির্দিষ্ট ডকুমেন্ট তৈরি হয়, আর Markdown সোর্সটি এডিটেবল সংস্করণ হিসেবে সুরক্ষিত থাকে।

একটি PDF তখন দরকারী হয় যখন README-কে তার মূল রিপোজিটরি ছাড়া অন্য কোথাও পাঠাতে হয় বা পৃষ্ঠা-ভিত্তিক ডকুমেন্ট হিসেবে পর্যালোচনা করার প্রয়োজন হয়।

সাধারণ কারণগুলোর মধ্যে রয়েছে:

• কোনো ক্লায়েন্ট বা অংশীদারের সাথে প্রজেক্ট ডকুমেন্টেশন শেয়ার করা;
• ইমেল বা টিকিটে প্রযুক্তিগত ওভারভিউ সংযুক্ত করা;
• পর্যালোচনা বা অনুমোদনের জন্য ডকুমেন্টেশন জমা দেওয়া;
• একটি নির্দিষ্ট সময়ে একটি রিপোজিটরির অফলাইন স্ন্যাপশট তৈরি করা;
• সেটআপ নির্দেশাবলী বা একটি অপারেশনাল রানবুক প্রিন্ট করা;
• রিলিজ ডকুমেন্টেশন আর্কাইভ করা;
• যারা GitHub ব্যবহার করেন না এমন পাঠকদের কাছে README বিতরণ করা;
• একটি নির্দিষ্ট লেআউটে দীর্ঘ কোড, সমীকরণ, ডায়াগ্রাম এবং টেবিল পর্যালোচনা করা।

মূল README সোর্স ফাইল হিসেবেই থাকা উচিত। README পরিবর্তনের পর আবার PDF জেনারেট করুন।

README ফাইলে সাধারণত ব্যবহৃত Markdown উপাদানগুলোকে SolConverter সমর্থন করে।

এগুলোর মধ্যে রয়েছে:

• ATX এবং Setext হেডিং;
• বোল্ড, ইটালিক এবং স্ট্রাইকথ্রু টেক্সট;
• অর্ডারড এবং আনঅর্ডারড তালিকা;
• নেস্টেড তালিকা;
• GFM টাস্ক লিস্ট;
• ব্লককোট;
• Markdown লিঙ্ক এবং অটো-লিঙ্ক;
• ইনলাইন কোড;
• ব্যাকটিক বা টিল্ড ব্যবহার করে ফেন্সড কোড ব্লক;
• কোড-ফেন্স ভাষার লেবেল;
• অ্যালাইনমেন্ট সহ GFM টেবিল;
• নিরাপদ র HTML টেবিল;
• details এবং summary সেকশন;
• kbd, sub, sup, figure, এবং figcaption;
• হেডিং অ্যাঙ্কর;
• সোর্সের শুরুতে YAML ফ্রন্ট ম্যাটার।

যে কোড ফেন্সগুলোতে ডলার চিহ্ন বা LaTeX-এর মতো ডিলিমিটার থাকে, সেগুলো সমীকরণ হিসেবে ব্যাখ্যা না হয়ে কোড হিসেবেই থাকে।

README ফাইলে প্রায়শই ইনস্টলেশন কমান্ড, কনফিগারেশন ফাইল, API উদাহরণ, এনভায়রনমেন্ট ভ্যারিয়েবল এবং সোর্স-কোড স্নিপেট থাকে।

কোড-ফেন্স ভাষা শনাক্ত করা হলে SolConverter Highlight.js দিয়ে সিনট্যাক্স হাইলাইটিং প্রয়োগ করে। অপরচিত ভাষাগুলোর ক্ষেত্রে মূল সোর্স নিরাপদে রাখা হয়।

কোড ব্লকগুলোতে একটি নির্দিষ্ট মনোস্পেস ফন্ট এবং প্রিন্ট স্টাইলিং ব্যবহার করা হয় যা সেগুলোকে চারপাশের ব্যাখ্যা থেকে আলাদা করে। ডান-থেকে-বাম ভাষার README-এর মধ্যেও কোড বাম-থেকে-ডান হিসেবেই থাকে।

একটি প্রযুক্তিগত README-তে সূত্র, ম্যাট্রিক্স, বৈজ্ঞানিক নোটেশন, প্রোবাবিলিটি বা কেমিস্ট্রি সমীকরণ থাকতে পারে।

SolConverter সাধারণ Markdown ম্যাথ ডিলিমিটার, AMS সমীকরণ পরিবেশ, প্রেজেন্টেশন MathML, বেসিক কন্টেন্ট MathML এবং \ce{...} দিয়ে লেখা কেমিস্ট্রি সমীকরণের জন্য MathJax SVG আউটপুট সমর্থন করে।

সমর্থিত গণিতের মধ্যে রয়েছে:

• $...$ এবং \(...\) ইনলাইন সমীকরণ;
• $$...$$ এবং \[...\] ডিসপ্লে সমীকরণ;
• সমীকরণ এবং অ্যালাইনমেন্ট পরিবেশ;
• ভগ্নাংশ, মূল, যোগফল, ইন্টিগ্রাল, লিমিট এবং ম্যাট্রিক্স;
• ডকুমেন্ট-স্কোপড ম্যাক্রো;
• দীর্ঘ যোগাত্মক সমীকরণ যার জন্য লাইন ব্রেকিং প্রয়োজন।

PDF-এ স্পষ্ট রাখার জন্য গণিতকে SVG হিসেবে রেন্ডার করা হয়। অবৈধ গণিত পুরো README-কে স্বয়ংক্রিয়ভাবে বন্ধ না করে স্থানীয়ভাবে ফলব্যাক হতে পারে।

আর্কিটেকচার, সিকোয়েন্স, স্টেট, ওয়ার্কফ্লো বা উপাদানের সম্পর্ক ব্যাখ্যা করতে README ফাইলে প্রায়শই ডায়াগ্রাম ব্যবহার করা হয়।

সমর্থিত Mermaid ফেন্সড ব্লকগুলো স্থানীয়ভাবে SVG হিসেবে রেন্ডার করা হয়। ZenUML-ও একটি যুক্ত Mermaid ইন্টিগ্রেশনের মাধ্যমে সমর্থিত। ডায়াগ্রামগুলোকে উপলব্ধ পৃষ্ঠার প্রস্থের মধ্যে সীমাবদ্ধ রাখা হয় এবং স্বাধীনভাবে প্রসেস করা হয়।

যদি একটি ডায়াগ্রাম অবৈধ হয়, তবে কনভার্টার সোর্স সহ একটি ফলব্যাক যুক্ত করে এবং বাকি সেকশনগুলো রেন্ডার করা চালিয়ে যায়।

PlantUML, Graphviz, D2, WaveDrom, BPMN, Nomnoml এবং সম্পূর্ণ TikZ বর্তমানে সমর্থিত নয় এবং এই পৃষ্ঠায় তা প্রচার করা উচিত নয়।

কনভার্টারটি পাবলিক HTTP এবং HTTPS ইমেজ এবং PNG, GIF, JPEG, WebP এবং SVG ফরম্যাটের বৈধ base64 ডাটা ইমেজ সমর্থন করে।

ইমেজগুলোকে পৃষ্ঠার সাথে মানানসই করতে স্কেল করা হয় এবং অ্যাসপেক্ট রেশিও ঠিক রাখা হয়। ফিগার, ক্যাপশন, অল্টারনেটিভ টেক্সট (alt text), টাইটেল, নিরাপদ মাত্রা এবং অ্যালাইনমেন্ট বজায় রাখা যেতে পারে।

তবে, অনেক রিপোজিটরির README রিলেটিভ পাথ ব্যবহার করে যেমন:

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

বর্তমান আপলোড ওয়ার্কফ্লো রিপোজিটরি ফোল্ডারকে প্যাকেজ করে না বা সেই রিলেটিভ সম্পদগুলোকে স্বয়ংক্রিয়ভাবে সমাধান করে না। PDF তৈরির আগে সেগুলোকে পাবলিক ইমেজ URL বা সমর্থিত base64 ডাটা ইমেজে রূপান্তর করুন।

ব্যাজগুলো সাধারণত পাবলিক ইমেজ URL ব্যবহার করে এবং ইমেজ হোস্ট সর্বজনীনভাবে অ্যাক্সেসযোগ্য হলে রেন্ডার হতে পারে। যদি কোনো ব্যাজ বা ইমেজ লোড করা না যায়, তবে SolConverter একটি স্থানীয় প্লেসহোল্ডার যুক্ত করে রূপান্তর চালিয়ে যায়।

README-এর ভেতরের Markdown লিঙ্কগুলো অ্যাবসোলিউট (absolute), রিপোজিটরি-রিলেটিভ বা পেজ-ফ্র্যাগমেন্ট লিঙ্ক হতে পারে।

অ্যাবসোলিউট HTTP এবং HTTPS লিঙ্কগুলো রিপোজিটরির বাইরেও কার্যকর থাকে। কিন্তু ./docs/setup.md বা ../CONTRIBUTING.md-এর মতো রিলেটিভ লিঙ্কগুলো README একটি একক PDF হয়ে যাওয়ার পর কোনো কার্যকর গন্তব্যে নিয়ে নাও যেতে পারে।

PDF শেয়ার করার আগে:

• গুরুত্বপূর্ণ রিলেটিভ লিঙ্কগুলোকে পাবলিক অ্যাবসোলিউট URL দিয়ে প্রতিস্থাপন করুন;
• শুধু লিঙ্ক করা ফাইলের ওপর নির্ভর না করে গুরুত্বপূর্ণ নির্দেশাবলী লিখে রাখুন;
• রেন্ডার করার পর হেডিং লিঙ্কগুলো যাচাই করুন;
• রিপোজিটরি নেভিগেশন ছাড়াও ডকুমেন্টটি বোধগম্য হচ্ছে কি না তা পরীক্ষা করুন;
• PDF-কে আর্কাইভ হিসেবে রাখার উদ্দেশ্য থাকলে সংস্করণ বা রিলিজের তথ্য অন্তর্ভুক্ত করুন।

একটি GitHub README এখনও একটি Markdown ফাইল, তবে GitHub এমন রিপোজিটরি প্রসঙ্গ যুক্ত করতে পারে যা আপলোড করা ফাইলে নিজে থেকে থাকে না।

PDF সমর্থিত GFM গঠন যেমন টেবিল, টাস্ক লিস্ট, ফেন্সড কোড, অটো-লিঙ্ক এবং হেডিং সংরক্ষণ করতে পারে। এটি সমর্থিত MathJax সমীকরণ এবং Mermaid ডায়াগ্রামও রেন্ডার করতে পারে।

কনভার্টারটি প্রতিটি GitHub ইন্টারফেসের উপাদান তৈরি করে না। রিপোজিটরি ট্যাব, ইস্যু সংখ্যা, রিলিজ উইজেট, ব্রাঞ্চ সিলেক্টর, ডাইনামিকালি জেনারেট করা কার্ড এবং অন্যান্য GitHub পৃষ্ঠার ক্রোম Markdown সোর্সের অংশ নয়।

সবচেয়ে পরিষ্কার একক PDF পেতে নিশ্চিত করুন যে README ফাইলের ভেতরেই প্রজেক্টের পরিচয়, সংস্করণের তথ্য এবং গুরুত্বপূর্ণ লিঙ্ক অন্তর্ভুক্ত রয়েছে।

একটি README PDF একটি সংক্ষিপ্ত প্রযুক্তিগত হ্যান্ডঅফ হিসেবে কাজ করতে পারে যখন পাঠকের প্রয়োজন হয়:

• একটি প্রজেক্ট ওভারভিউ;
• ইনস্টলেশন এবং সেটআপ ধাপ;
• কমান্ডের উদাহরণ;
• কনফিগারেশন প্রয়োজনীয়তা;
• আর্কিটেকচার ডায়াগ্রাম;
• API উদাহরণ;
• অপারেশনাল নোট;
• সমস্যা সমাধান নির্দেশিকা;
• অবদান বা সমর্থনের বিবরণ।

বড় ডকুমেন্টেশন সেটের জন্য, প্রতিটি গাইডকে একটি ফাইলে জোর করে অন্তর্ভুক্ত না করে README-কে এন্ট্রি ডকুমেন্ট হিসেবে বিবেচনা করুন। খুব দীর্ঘ README থেকে জেনারেট করা PDF-ও কার্যকর হতে পারে, তবে আলাদা ডকুমেন্ট বজায় রাখা এবং ব্রাউজ করা সহজ হতে পারে।

রিপোজিটরিগুলো সময়ের সাথে সাথে পরিবর্তিত হয়। README-কে PDF-এ রূপান্তর করা কোনো রিলিজ, ডেলিভারি, রিভিউ বা মাইলফলকের সাথে সম্পর্কিত একটি স্ন্যাপশট তৈরি করে।

আর্কাইভ করার আগে:

1. প্রজেক্ট বা প্যাকেজের সংস্করণ যুক্ত করুন;
2. প্রাসঙ্গিক তারিখ বা রিলিজের তথ্য অন্তর্ভুক্ত করুন;
3. কমান্ড এবং কনফিগারেশন উদাহরণগুলো যাচাই করুন;
4. অস্থায়ী লিঙ্কগুলো প্রতিস্থাপন করুন;
5. ইমেজ, ডায়াগ্রাম এবং সমীকরণগুলো পর্যালোচনা করুন;
6. চূড়ান্ত PDF জেনারেট করুন এবং পরিদর্শন করুন;
7. PDF ফাইলটি রিলিজ রেকর্ডের পাশে সংরক্ষণ করুন।

জেনারেট করা PDF একটি স্ন্যাপশট মাত্র, এটি ভার্সন-নিয়ন্ত্রিত README সোর্সের বিকল্প নয়।

README ফাইলে র HTML, দূরবর্তী ইমেজের URL এবং ত্রুটিপূর্ণ ব্লক থাকতে পারে।

SolConverter রেন্ডার করা HTML স্যানিটাইজ করে, স্ক্রিপ্ট এবং ইভেন্ট হ্যান্ডলার সরিয়ে দেয়, অনিরাপদ URL প্রত্যাখ্যান করে, র HTML-কে একটি অ্যালাওলিস্টে সীমাবদ্ধ করে, টেবিল স্প্যান সীমিত করে, একটি কঠোর কন্টেন্ট সিকিউরিটি পলিসি প্রয়োগ করে এবং ইমেজ পলিসির বাইরের ব্রাউজার রিকোয়েস্ট ব্লক করে।

স্থানীয় ফাইল, লোকালহোস্ট গন্তব্য, প্রাইভেট-IP লিটারাল, javascript: URL এবং অসমর্থিত রিসোর্স স্কিমগুলো ব্লক করা হয়। অবৈধ ইমেজ, সমীকরণ এবং ডায়াগ্রাম যথাসম্ভব স্থানীয়ভাবে পরিচালনা করা হয় যাতে বাকি README রেন্ডার হওয়া চালিয়ে যেতে পারে।

SolConverter README ফাইলগুলোর ওপর একটি সামঞ্জস্যপূর্ণ ডকুমেন্ট লেআউট প্রয়োগ করে।

বর্তমান ওয়েব ফর্মটি ব্যবহার করে:

• A4 পৃষ্ঠার আকার;
• পোর্ট্রেট ওরিয়েন্টেশন;
• পড়ার উপযোগী মার্জিন;
• current / total পৃষ্ঠা নম্বর;
• README ফাইলের নামের ওপর ভিত্তি করে আউটপুট টাইটেল;
• প্রিন্ট ব্যাকগ্রাউন্ড।

পোর্ট্রেট লেআউটটি সাধারণ পঠনের জন্য ডিজাইন করা হয়েছে। ডাউনলোড করার আগে সর্বদা চওড়া টেবিল এবং কোডের প্রিভিউ দেখে নিন।

এই README-কেন্দ্রিক পেজটি ব্যবহার করুন যখন সোর্স ফাইলটি একটি প্রজেক্ট README এবং আপনার কোড ফেন্স, GFM স্ট্রাকচার, ব্যাজ, রিপোজিটরি-রিলেটিভ ইমেজ এবং রিপোজিটরি লিঙ্ক সম্পর্কে নির্দেশনার প্রয়োজন হয়।

রিপোর্ট, গাণিতিক ডকুমেন্ট, প্রযুক্তিগত নোট, প্রস্তাব, বহুভাষিক ডকুমেন্ট এবং সাধারণ .md ফাইলের জন্য মূল Markdown to PDF কনভার্টার ব্যবহার করুন।

উভয় পেজ একই মূল রূপান্তর ক্ষমতা ব্যবহার করে, তবে তারা বিভিন্ন ব্যবহারকারীর কাজ সম্পন্ন করে এবং বিভিন্ন প্রস্তুতি নির্দেশিকা প্রদান করে।

• যেকোনো Markdown ফাইলকে PDF-এ রূপান্তর করুন
• PDF-কে Markdown-এ রূপান্তর করুন
• HTML-কে Markdown-এ রূপান্তর করুন
• Word-কে Markdown-এ রূপান্তর করুন
• সমস্ত ফাইল-টু-Markdown সরঞ্জাম ব্রাউজ করুন