README to PDF कनवर्टर

एक README.md फ़ाइल एक Markdown दस्तावेज़ है जो किसी प्रोजेक्ट, रिपॉजिटरी, पैकेज, एप्लिकेशन, डेटासेट या वर्कफ़्लो की व्याख्या करता है।

README फ़ाइलों में आमतौर पर शामिल होते हैं:

• एक प्रोजेक्ट शीर्षक और सारांश;
• स्थापना निर्देश (installation instructions);
• उपयोग के उदाहरण;
• कमांड-लाइन स्निपेट;
• कॉन्फ़िगरेशन उदाहरण;
• सुविधा सूचियाँ;
• कार्य सूचियाँ (task lists);
• तालिकाएँ;
• स्क्रीनशॉट;
• बैज;
• योगदान निर्देश;
• लाइसेंस या समर्थन जानकारी;
• दस्तावेज़ीकरण और रिलीज़ के लिंक।

.md एक्सटेंशन का अर्थ है कि फ़ाइल Markdown में लिखी गई है। इसे PDF में बदलने से एक निश्चित दस्तावेज़ बनता है जबकि Markdown स्रोत संपादन योग्य संस्करण के रूप में सुरक्षित रहता है।

एक PDF तब उपयोगी होता है जब README को अपने मूल रिपॉजिटरी से बाहर जाना होता है या पृष्ठ-आधारित दस्तावेज़ के रूप में इसकी समीक्षा की जानी होती है।

सामान्य कारणों में शामिल हैं:

• किसी ग्राहक या हितधारक के साथ प्रोजेक्ट दस्तावेज़ साझा करना;
• ईमेल या टिकट में तकनीकी अवलोकन संलग्न करना;
• समीक्षा या अनुमोदन के लिए दस्तावेज़ जमा करना;
• किसी विशिष्ट समय पर रिपॉजिटरी का ऑफ़लाइन स्नैपशॉट बनाना;
• सेटअप निर्देश या परिचालन रनबुक मुद्रित करना;
• रिलीज़ दस्तावेज़ों को संग्रहीत करना;
• उन पाठकों को README वितरित करना जो GitHub का उपयोग नहीं करते हैं;
• एक निश्चित लेआउट में लंबे कोड, समीकरणों, आरेखों और तालिकाओं की समीक्षा करना।

मूल README ही रखरखाव योग्य स्रोत बना रहना चाहिए। README में बदलाव के बाद PDF को पुन: जनरेट करें।

SolConverter उन Markdown तत्वों का समर्थन करता है जो आमतौर पर README फ़ाइलों में उपयोग किए जाते हैं।

इनमें शामिल हैं:

• 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 आउटपुट का समर्थन करता है।

समर्थित गणित में शामिल हैं:

• $...$ और \(...\) इनलाइन अभिव्यक्तियाँ;
• $$...$$ और \[...\] डिस्प्ले अभिव्यक्तियाँ;
• समीकरण और संरेखण (alignment) वातावरण;
• भिन्न, मूल, योग, समाकलन, सीमाएं और मैट्रिक्स;
• दस्तावेज़-क्षेत्रीय मैक्रोज़;
• लंबी योगात्मक अभिव्यक्तियाँ जिन्हें लाइन ब्रेकिंग की आवश्यकता होती है।

PDF में स्पष्ट रहने के लिए गणित को SVG के रूप में प्रस्तुत किया जाता है। अमान्य गणित पूरे README को स्वचालित रूप से रोके बिना स्थानीय रूप से फ़ालबैक हो सकता है।

आर्किटेक्चर, अनुक्रम, स्थिति, वर्कफ़्लो या घटक संबंधों को समझाने के लिए README फ़ाइलों में अक्सर आरेखों का उपयोग किया जाता है।

समर्थित Mermaid फेन्स्ड ब्लॉक स्थानीय रूप से SVG के रूप में प्रस्तुत किए जाते हैं। ZenUML भी एक बंडल Mermaid एकीकरण के माध्यम से समर्थित है। आरेखों को उपलब्ध पृष्ठ चौड़ाई तक सीमित किया जाता है और स्वतंत्र रूप से संसाधित किया जाता है।

यदि एक आरेख अमान्य है, तो कनवर्टर स्रोत के साथ एक फ़ालबैक सम्मिलित करता है और शेष अनुभागों को प्रस्तुत करना जारी रखता है।

PlantUML, Graphviz, D2, WaveDrom, BPMN, Nomnoml, और पूर्ण TikZ वर्तमान में समर्थित नहीं हैं और इस पृष्ठ पर विज्ञापित नहीं किए जाने चाहिए।

कनवर्टर सार्वजनिक HTTP और HTTPS छवियों और PNG, GIF, JPEG, WebP, और SVG स्वरूपों में मान्य base64 डेटा छवियों का समर्थन करता है।

छवियों को पृष्ठ में फिट करने और उनके पक्षानुपात को बनाए रखने के लिए स्केल किया जाता है। आंकड़े, कैप्शन, ऑल्ट टेक्स्ट, शीर्षक, सुरक्षित आयाम और संरेखण को बरकरार रखा जा सकता है।

हालाँकि, कई रिपॉजिटरी README सापेक्ष पथों का उपयोग करते हैं जैसे:

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

वर्तमान अपलोड वर्कफ़्लो रिपॉजिटरी फ़ोल्डर को पैकेज नहीं करता है या उन सापेक्ष संपत्तियों को स्वचालित रूप से हल नहीं करता है। PDF बनाने से पहले उन्हें सार्वजनिक छवि URL या समर्थित base64 डेटा छवियों में बदलें।

बैज आमतौर पर सार्वजनिक छवि URL का उपयोग करते हैं और तब रेंडर हो सकते हैं जब छवि होस्ट सार्वजनिक रूप से सुलभ हो। यदि कोई बैज या छवि लोड नहीं की जा सकती है, तो SolConverter एक स्थानीय प्लेसहोल्डर सम्मिलित करता है और रूपांतरण जारी रखता है।

README के अंदर Markdown लिंक पूर्ण, रिपॉजिटरी-सापेक्ष या पृष्ठ-खंड लिंक हो सकते हैं।

पूर्ण HTTP और HTTPS लिंक रिपॉजिटरी के बाहर भी सार्थक बने रहते हैं। सापेक्ष लिंक जैसे ./docs/setup.md या ../CONTRIBUTING.md README के एक स्टैंडअलोन PDF बनने के बाद उपयोगी गंतव्य की ओर संकेत नहीं कर सकते हैं।

PDF साझा करने से पहले:

• महत्वपूर्ण सापेक्ष लिंक को सार्वजनिक पूर्ण URL से बदलें;
• केवल लिंक की गई फ़ाइलों पर भरोसा करने के बजाय महत्वपूर्ण निर्देशों को लिख लें;
• रेंडरिंग के बाद हेडिंग लिंक सत्यापित करें;
• जांचें कि दस्तावेज़ अभी भी रिपॉजिटरी नेविगेशन के बिना समझ में आता है या नहीं;
• संस्करण या रिलीज़ की जानकारी शामिल करें जब PDF को एक संग्रह (archive) के रूप में रखने का इरादा हो।

एक 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 टूल ब्राउज़ करें