مبدل README به PDF

یک فایل README.md سندی به زبان Markdown است که یک پروژه، مخزن کد، پکیج، نرم‌افزار، مجموعه داده یا جریان کار را توضیح می‌دهد.

فایل‌های راهنما (README) معمولاً شامل موارد زیر هستند:

• عنوان پروژه و خلاصه آن؛
• دستورالعمل‌های نصب؛
• نمونه‌های استفاده و کاربرد؛
• دستورات خط فرمان؛
• نمونه‌های تنظیمات (configuration)؛
• لیست ویژگی‌ها و قابلیت‌ها؛
• لیست کارهای در دست انجام (task lists)؛
• جدول‌ها؛
• اسکرین‌شات‌ها؛
• شارات (badges)؛
• راهنمای مشارکت در پروژه؛
• اطلاعات مجوز (license) یا پشتیبانی؛
• لینک به مستندات و نسخه‌های منتشر شده.

پسوند .md به این معنی است که فایل با ساختار Markdown نوشته شده است. تبدیل آن به PDF یک سند ثابت و بدون تغییر ایجاد می‌کند در حالی که منبع Markdown اصلی همچنان به عنوان نسخه قابل ویرایش حفظ می‌شود.

فایل PDF زمانی مفید است که فایل README باید خارج از مخزن اصلی خود ارائه شود یا به عنوان یک سند مبتنی بر صفحه مورد بررسی و مراجع قرار گیرد.

دلایل رایج عبارتند از:

• اشتراک‌گذاری مستندات پروژه با یک مشتری یا ذینفع؛
• ضمیمه کردن یک خلاصه فنی به یک ایمیل یا تیکت پشتیبانی؛
• ارسال مستندات برای بازبینی یا تأیید نهایی؛
• ایجاد یک نسخه پشتیبان آفلاین از مخزن پروژه در یک زمان مشخص؛
• چاپ دستورالعمل‌های راه‌اندازی یا راهنمای کاربری عملیاتی؛
• بایگانی مستندات انتشار نسخه؛
• توزیع فایل README برای خوانندگانی که از گیت‌هاب استفاده نمی‌کنند؛
• بررسی کدهای طولانی، معادلات ریاضی، نمودارها و جدول‌ها در یک چیدمان ثابت.

فایل README اصلی باید به عنوان منبع قابل ویرایش و نگهداری باقی بماند. پس از تغییر فایل README، مجدداً پی‌دی‌اف جدیدی تولید کنید.

SolConverter از عناصر Markdown متداولی که در فایل‌های README استفاده می‌شوند پشتیبانی می‌کند.

این موارد عبارتند از:

• سرصفحه‌های ATX و Setext؛
• متن‌های ضخیم (bold)، مورب (italic) و خط‌خورده (strikethrough)؛
• لیست‌های مرتب و نامرتب؛
• لیست‌های تو در تو؛
• لیست کارهای GFM؛
• نقل‌قول‌ها؛
• لینک‌های Markdown و لینک‌های خودکار؛
• کدهای درون‌خطی؛
• بلوک‌های کد محصور با استفاده از علامت‌های backtick یا tilde؛
• برچسب‌های تشخیص زبان بلوک کد؛
• جدول‌های GFM همراه با تنظیم تراز؛
• جدول‌های HTML خام و امن؛
• بخش‌های details و summary؛
• عناصر kbd، sub، sup، figure و figcaption؛
• لنگرهای سرصفحه (heading anchors)؛
• فرانت‌مترهای YAML در ابتدای فایل منبع.

بلوک‌های کدی که حاوی علامت دلار یا جداکننده‌های شبیه LaTeX هستند، به صورت کد باقی می‌مانند و به عنوان معادلات ریاضی تفسیر نمی‌شوند.

فایل‌های راهنما (README) معمولاً شامل دستورات نصب، فایل‌های تنظیمات، نمونه‌های API، متغیرهای محیطی و مقتطف‌های کد منبع هستند.

SolConverter در صورت شناسایی زبان بلوک کد محصور، برجسته‌سازی سینتکس را با استفاده از Highlight.js اعمال می‌کند. در صورت عدم شناسایی زبان، متن منبع اصلی به طور امن حفظ می‌شود.

بلوک‌های کد از یک فونت تک‌فاصله اختصاصی و استایل‌های چاپ ویژه‌ای استفاده می‌کنند که آن‌ها را از توضیحات اطراف متمایز می‌کند. جهت کدها حتی در فایل‌های راهنمای راست‌به‌چپ به صورت چپ‌به‌راست باقی می‌ماند.

یک فایل راهنمای فنی ممکن است شامل فرمول‌ها، ماتریس‌ها، علائم علمی، عبارت‌های احتمالی یا مباحث شیمی باشد.

SolConverter از خروجی MathJax SVG برای جداکننده‌های ریاضی رایج در Markdown، محیط‌های معادله AMS، فرمت‌های Presentation MathML، کدهای پایه‌ای Content MathML و عبارت‌های شیمی نوشته شده با \ce{...} پشتیبانی می‌کند.

ریاضیات پشتیبانی‌شده عبارتند از:

• عبارت‌های درون‌خطی $...$ و \(...\)؛
• عبارت‌های نمایشی $$...$$ و \[...\]؛
• محیط‌های معادله و هم‌ترازی؛
• کسرها، ریشه‌ها، مجموع‌ها، انتگرال‌ها، حدها و ماتریس‌ها؛
• ماکروهای تعریف‌شده در سطح سند؛
• عبارت‌های جمعی طولانی که نیاز به شکستن خط دارند.

فرمول‌های ریاضی به صورت SVG رندر می‌شوند تا کیفیت آن‌ها در PDF کاملاً حفظ شود. ریاضیات نامعتبر به صورت محلی نادیده گرفته می‌شوند تا بقیه متن بدون مشکل رندر شود.

فایل‌های راهنما معمولاً برای توضیح معماری، توالی کار، وضعیت، جریان کار یا روابط بین مؤلفه‌ها از نمودارها استفاده می‌کنند.

بلوک‌های محصور Mermaid پشتیبانی‌شده به صورت محلی به عنوان SVG رندر می‌شوند. ZenUML نیز پشتیبانی می‌شود. نمودارها به عرض صفحه موجود محدود شده و به صورت مستقل پردازش می‌شوند.

اگر نموداری نامعتبر باشد، مبدل یک گزینه جایگزین با متن منبع آن درج کرده و رندر بقیه بخش‌ها را ادامه می‌دهد.

فرمت‌های PlantUML، Graphviz، D2، WaveDrom، BPMN، Nomnoml و TikZ کامل در حال حاضر پشتیبانی نمی‌شوند و نباید در این صفحه تبلیغ شوند.

مبدل از تصاویر آدرس‌های عمومی HTTP و HTTPS و همچنین تصاویر داده‌ای base64 معتبر در فرمت‌های PNG، GIF، JPEG، WebP و SVG پشتیبانی می‌کند.

تصاویر برای تناسب با صفحه تغییر مقیاس داده می‌شوند و نسبت ابعاد آن‌ها حفظ می‌شود. ویژگی‌هایی مانند اشکال، توضیحات، متن جایگزین، عناوین، ابعاد امن و تراز را می‌توان حفظ کرد.

با این حال، بسیاری از فایل‌های راهنما در مخازن کد از مسیرهای نسبی استفاده می‌کنند مانند:

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

جریان کار آپلود فعلی، پوشه مخزن پروژه را بسته‌بندی نمی‌کند و به طور خودکار آن دارایی‌های نسبی را حل نمی‌نماید. قبل از ایجاد PDF، آن‌ها را به آدرس‌های اینترنتی عمومی تصاویر یا تصاویر داده‌ای base64 پشتیبانی‌شده تبدیل کنید.

شارات معمولاً از آدرس‌های اینترنتی عمومی تصاویر استفاده می‌کنند و در صورتی که سرور تصویر به صورت عمومی در دسترس باشد رندر می‌شوند. اگر لود شدن شاره یا تصویری با شکست مواجه شود، SolConverter یک نگه‌دارنده جایگزین محلی درج کرده و فرآیند تبدیل را ادامه می‌دهد.

لینک‌های Markdown داخل یک فایل راهنما می‌توانند مطلق (absolute)، نسبی نسبت به مخزن، یا لینک‌های داخلی مربوط به بخش‌های همان صفحه باشند.

لینک‌های مطلق HTTP و HTTPS در خارج از مخزن نیز معتبر و کارآمد باقی می‌مانند. اما لینک‌های نسبی مانند ./docs/setup.md یا ../CONTRIBUTING.md پس از تبدیل فایل راهنما به یک PDF مستقل، ممکن است به مقصد مفیدی اشاره نکنند.

قبل از اشتراک‌گذاری فایل PDF:

• لینک‌های نسبی مهم را با آدرس‌های اینترنتی مطلق و عمومی جایگزین کنید؛
• به جای تکیه بر فایل‌های لینک شده، دستورالعمل‌های حیاتی را به طور کامل بنویسید؛
• لینک‌های سرصفحه را پس از رندر شدن بررسی و تأیید کنید؛
• بررسی کنید که سند بدون نیاز به ناوبری مخزن گیت‌هاب همچنان مفهوم باشد؛
• در صورتی که هدف از پی‌دی‌اف بایگانی اطلاعات است، نسخه پروژه یا مشخصات انتشار نسخه را در سند درج کنید.

یک فایل راهنمای گیت‌هاب (GitHub README) همچنان یک فایل Markdown است، اما ممکن است گیت‌هاب زمینه‌های مخزنی را اضافه کند که در خود فایل آپلود شده وجود ندارند.

فایل PDF می‌تواند ساختارهای پشتیبانی‌شده GFM مانند جدول‌ها، لیست‌های وظیفه، کدهای محصور، لینک‌های خودکار و سرصفحه‌ها را حفظ کند. همچنین می‌تواند عبارت‌های MathJax و نمودارهای Mermaid پشتیبانی‌شده را رندر نماید.

مبدل تمام عناصر رابط کاربری گیت‌هاب را بازسازی نمی‌کند. تب‌های مخزن، تعداد ایشوها (issues)، ویجت‌های انتشار نسخه، انتخابگرهای شاخه (branch selectors)، کارت‌های داینامیک و سایر بخش‌های صفحه گیت‌هاب جزئی از متن منبع Markdown نیستند.

برای داشتن یک PDF مستقل و تمیز، مطمئن شوید که هویت پروژه، نسخه و لینک‌های مهم در خود سند گنجانده شده‌اند.

یک فایل PDF راهنما می‌تواند به عنوان یک مستند فنی خلاصه و کارآمد عمل کند، زمانی که خواننده نیاز دارد به:

• خلاصه و نمای کلی پروژه؛
• مراحل نصب و راه‌اندازی؛
• دستورات نمونه؛
• پیش‌نیازهای تنظیمات؛
• نمودارهای معماری؛
• نمونه‌های API؛
• یادداشت‌های عملیاتی؛
• دستورالعمل‌های عیب‌یابی؛
• جزئیات مشارکت در پروژه یا پشتیبانی.

برای مستندات بسیار حجیم، به جای گنجاندن تمام راهنماها در یک فایل، از فایل راهنما به عنوان سند ورودی استفاده کنید. پی‌دی‌اف تولید شده از یک فایل راهنمای بسیار طولانی همچنان می‌تواند مفید باشد، اما مدیریت و ناوبری اسناد مجزا آسان‌تر است.

مخازن پروژه به مرور زمان تغییر می‌کنند. تبدیل فایل راهنما به PDF یک لقطه خوانا و پایدار مربوط به یک نسخه منتشر شده، تحویل پروژه یا یک نقطه عطف ایجاد می‌کند.

قبل از بایگانی کردن:

1. نسخه پروژه یا پکیج را اضافه کنید؛
2. تاریخ مرتبط یا شناسه انتشار نسخه را درج کنید؛
3. دستورات و نمونه‌های تنظیمات را بررسی و تأیید نمایید؛
4. لینک‌های موقت را جایگزین کنید؛
5. تصاویر، نمودارها و معادلات را بازبینی کنید؛
6. پی‌دی‌اف نهایی را تولید کرده و بررسی نمایید؛
7. فایل PDF را در کنار سوابق نسخه منتشر شده ذخیره کنید.

فایل PDF تولید شده یک نسخه ثبت‌شده در یک زمان خاص است، نه جایگزینی برای فایل راهنمای اصلی که تحت کنترل نسخه است.

فایل‌های راهنما می‌توانند حاوی کدهای HTML خام، آدرس‌های تصویر راه دور ناامن و بلوک‌های نامعتبر باشند.

SolConverter کدهای HTML رندر شده را پاک‌سازی می‌کند، اسکریپت‌ها و رویدادگیرها را حذف می‌نماید، آدرس‌های اینترنتی ناامن را رد می‌کند، کدهای HTML خام را به یک لیست سفید محدود می‌سازد، تداخل‌های جدول را محدود می‌کند، سیاست‌های امنیتی محتوای سخت‌گیرانه‌ای اعمال می‌کند و درخواست‌های مرورگر خارج از سیاست‌های تصویر مجاز را مسدود می‌سازد.

فایل‌های محکلی، مقاصد localhost، مقادیر آی‌پی خصوصی، آدرس‌های URL دارای javascript: و پروتکل‌های منابع پشتیبانی‌نشده مسدود می‌شوند. تصاویر، معادلات و نمودارهای نامعتبر تا حد امکان به صورت محلی مدیریت می‌شوند تا رندر بقیه بخش‌های فایل راهنما ادامه یابد.

SolConverter چیدمان سند منسجمی را برای فایل‌های راهنما اعمال می‌کند.

فرم وب فعلی از تنظیمات زیر استفاده می‌کند:

• اندازه صفحه A4؛
• جهت عمودی (portrait)؛
• حاشیه‌های تنظیم‌شده برای خروجی خوانا؛
• شماره‌گذاری صفحات به صورت current / total؛
• عنوان خروجی بر اساس نام فایل README؛
• چاپ رنگ‌های پس‌زمینه.

چیدمان عمودی برای خواندن عمومی طراحی شده است. همیشه قبل از دانلود، جدول‌های عریض و بلوک‌های کد را پیش‌نمایش کنید.

زمانی از این صفحه متمرکز بر فایل‌های راهنما استفاده کنید که فایل منبع شما یک README پروژه است و به راهنمایی در مورد کدهای محصور، ساختارهای GFM، شارات (badges)، تصاویر با مسیر نسبی و لینک‌های مخزن نیاز دارید.

برای گزارش‌ها، اسناد ریاضی، یادداشت‌های فنی، پروپوزال‌ها، اسناد چندزبانه و فایل‌های عمومی .md، از مبدل اصلی Markdown به PDF استفاده کنید.

هر دو صفحه از قابلیت تبدیل اصلی یکسانی استفاده می‌کنند، اما اهداف متفاوتی از کاربران را پوشش داده و راهنمایی‌های متفاوتی برای آماده‌سازی فایل ارائه می‌دهند.

• تبدیل هر نوع فایل Markdown به PDF
• تبدیل PDF به Markdown
• تبدیل HTML به Markdown
• تبدیل Word به Markdown
• مشاهده تمام ابزارهای تبدیل فایل به Markdown