Markdown کو HTML میں تبدیل کریں

فریگمنٹ یا مکمل صفحہ، اور آپ کو کون سا چاہیے

دو کارآمد آؤٹ پٹس ہیں اور یہ ایک دوسرے کی جگہ نہیں لے سکتے۔ فریگمنٹ صرف تبدیل شدہ مارک اپ ہے — ہیڈنگز، پیراگراف، فہرستیں، لنکس — بغیر کسی دستاویزی ڈھانچے کے، اور یہی چاہیے جب نتیجہ کسی ٹیمپلیٹ، CMS فیلڈ یا دوسرے صفحے میں جا رہا ہو۔ مکمل صفحہ اس میں doctype، ہیڈ، کیریکٹر سیٹ کا اعلان اور اسٹائل شیٹ شامل کرتا ہے، اس لیے یہ اکیلے کھلتا ہے اور ڈھنگ کا نظر آتا ہے۔ مکمل صفحہ CMS میں پیسٹ کریں تو دستاویز کے اندر دستاویز بن جاتی ہے؛ فریگمنٹ براؤزر میں کھولیں تو بغیر اسٹائل کا ٹیکسٹ ملتا ہے۔

تبدیلی Markdown کے اس توسیعی سیٹ کا احاطہ کرتی ہے جس پر عام طور پر اتفاق ہے: ہیڈنگز، زور (emphasis)، فہرستیں، لنکس، تصاویر، بلاک کوٹس، ٹیبلز، سنٹیکس ہائی لائٹنگ والے فینسڈ کوڈ بلاکس، ٹاسک لسٹس، اسٹرائیک تھرو اور فٹ نوٹس۔ ہیڈنگز کو ان کے ٹیکسٹ سے بنے شناختی نام ملتے ہیں، اس لیے ان پر براہِ راست لنک دیا جا سکتا ہے — یہی اینکر لنکس لمبی دستاویزات کو قابلِ استعمال بناتے ہیں۔

Markdown کے اندر موجود خام HTML جوں کا توں آگے جاتا ہے، جو اسپیسیفکیشن کا حصہ ہے اور اس پر سوچ سمجھ کر عمل کرنا چاہیے: اس کا مطلب ہے کہ کسی ناقابلِ اعتماد ذریعے سے آئی Markdown فائل میں script ٹیگ ہو سکتا ہے، اور اسے تبدیل کرنے سے بننے والے صفحے میں وہ اسکرپٹ موجود ہوگا۔ اجنبیوں کا Markdown کبھی رینڈر نہ کریں جب تک بعد میں HTML کو سینیٹائز نہ کر لیں — یہ تبدیلی کوئی سیکیورٹی حد نہیں ہے اور نہ کبھی ایسی بنائی گئی تھی۔

دو چیزیں جان بوجھ کر رینڈر ہونے کے بجائے کوڈ بلاکس کے طور پر آتی ہیں۔ LaTeX میں لکھے ریاضی کے فارمولوں کو ٹائپ سیٹنگ لائبریری چاہیے، اور Mermaid ڈایاگرامز کو ڈایاگرام رینڈرر — دونوں بڑی ڈیپینڈنسیز ہیں، اور غلط رینڈر ہوئی مساوات صاف دکھائی دینے والے کوڈ سے بدتر ہے۔ مکمل صفحہ کوئی فونٹ ڈاؤن لوڈ کرنے کے بجائے عام سسٹم فونٹس استعمال کرتا ہے، اس لیے یہ آف لائن بھی چلتا ہے اور Windows، macOS اور Linux پر تھوڑا مختلف نظر آتا ہے۔

جب آپ کو کچھ اور چاہیے

Pandoc وہ حصے بھی سنبھالتا ہے جو یہاں چھوڑ دیے گئے ہیں، اور اس سے کہیں زیادہ: pandoc in.md -o out.html --mathjax --standalone --toc ریاضی درست رینڈر کرتا ہے، فہرستِ مضامین بناتا ہے، اور ٹیمپلیٹ قبول کرتا ہے تاکہ آؤٹ پٹ آپ کی اپنی سائٹ جیسا ہو۔ یہ تقریباً چالیس دوسرے فارمیٹس میں اور ان سے تبدیلی بھی کرتا ہے، اسی لیے اسے ایک بار انسٹال کر لینا فائدہ مند ہے۔

اگر فائل کے بجائے ویب سائٹ بنانی ہو تو صفحات ایک ایک کر کے تبدیل کرنے کے بجائے جنریٹر استعمال کریں۔ Hugo، Eleventy، Jekyll اور MkDocs Markdown کے فولڈر کو نیویگیشن، سرچ اور یکساں اسٹائلنگ والی سائٹ میں بدل دیتے ہیں، اور جب بھی سورس بدلے اسے دوبارہ بنا دیتے ہیں — ایک سے زیادہ دستاویز ہو تو اصل کام یہی ہے۔