github flavored markdown to html
1.0.0
وحدة بيثون سهلة الاستخدام وواجهة خط الأوامر لتحويل Markdown إلى HTML. يستخدم GitHubs عبر الإنترنت إلى HTML-API افتراضيًا (والذي يتطلب اتصال بالإنترنت) ، ولكنه يأتي مع خيار للتحويل غير المتصلة بالإنترنت (والذي يقلد عن كثب سلوك GitHubs) ، ويمكن توصيل أي أداة أخرى من Python أو خط الأوامر أيضًا. يتم تمديد كل ما تستخدمه معها تلقائيًا مع الكثير من الوظائف ، مثل المزيد من خيارات الإخراج والإخراج ، و CSS بنكهة Github ، ودعم الصيغة ، وتخزين الصور المتقدمة والتحسين ، وتوحيد الملفات والملفات الجاهزة للمضيف ، و PDF-Conversion ، ودعم الرمز القصير في الرموز التعبيرية ، ودعم TOC والمزيد.
في حين أن الغرض الرئيسي منه هو إنشاء صفحات ثابتة من ملفات Markdown ، على سبيل المثال بالتزامن مع منشئ موقع ويب ثابت أو إجراءات github إذا كنت تستضيف على Github ، يمكن أن تكون مستخدمة جيدًا لأي غرض آخر.
فيما يلي قائمة (ليست بالضرورة واسعة) من مزاياها وميزاتها:
$ -formula- $ لاستخدامها) ، وهو ما لا يفعله github عادة. يستخدم GH-MD-to-HTML LATEX و DVISVGM إذا تم تثبيتهما (ميزة: سريع ، لا يتطلب الإنترنت) ، وإلا[[_TOC_]] ، {:toc} و [toc] في بداية خط فارغ خلاف ذلك لإنشاء جدول للمحتوى للوثيقة ، مثل MITLAB-SLAVOR MORKDODER ، من بين أمور أخرى.في حال كنت تبحث عن بديل لـ Pandoc لتحويل Markdown إلى PDF ، فإليك قائمة بالأسباب التي تجعلك ترغب في استخدام GH-MD-to-HTML بدلاً من PANDOC للوظيفة:
في حين أن استخدام PANDOC للتحويل من Markdown إلى PDF عادة ما يؤدي إلى نتائج أكثر جمالًا (يستخدم Pandoc اللاتكس ، بعد كل شيء) ، لدى GH-MD-to-HTML مجموعة من مزاياها الخاصة عندما يتعلق الأمر بتحويل الملفات المعقدة بسرعة لمهمة الواجب المنزلي أو غيرها
$ -signs وما هي الأحرف التي قد تبدأ بها الصيغة. لا تنطبق هذه القواعد في بعض المحررين المشتركين مثل MarkText ، مما يؤدي إلى الكثير من الإحباط عندما لا تعمل الصيغ التي عملت في المحرر عند التحويل مع Pandoc (تفشل تصدير الصادرات إلى PDF الخاصة بـ MarkText في بعض الأحيان على ملفات الصيغة دون رسالة خطأ ، مما يجعلها أقل موثوقية). أسوأ جزء هو أنه كلما فشل Pandoc في تحويل .md إلى .pdf بسبب هذا ، فإنه يوضح رقم السطر للخطأ استنادًا إلى ملف .TEX الوسيط بدلاً من ملف الإدخال .MD ، مما يجعل من الصعب العثور على جذر المشكلة. كما قد تكون قد خمنت ، فإن GH-MD-to-HTML لا يمكن أن يهتم بمقدار المساحة البيضاء التي تبدأ بها صيغك ، وترك هذا القرار لك.لتلخيص ذلك ، يعمل تحويل MD-to-PDF من PANDOC إلى غير عادي عندما يتعلق الأمر بالصور ، أو القوائم المتداخلة ، أو إدخالات نقطة الرصاص المتعددة ، أو الصيغ ، و GH-MD-to-HTML لا.
استخدم pip3 install gh-md-to-html للتثبيت مباشرة من فهرس حزمة Python ، أو python3 -m pip install gh-md-to-html إذا كنت على Windows.
قد يتطلب كلاهما sudo على Linux ، ويمكنك القيام به اختياريا
python3 -m pip install gh-md-to-html[pdf_export]
وتثبيت WKHTMLTOPDF (v0.12.6 أو أكثر) للحصول على ميزة التحويل PDF الاختياري وتحويل ملفات markdown إلى PDF ، و/أو
python3 -m pip install gh-md-to-html[offline_conversion]
للحصول على ميزة التحويل غير المتصل بالإنترنت وتشغيلها.
إذا كنت على Windows ، فقد تضطر إلى إضافة wkhtmltopdf إلى مسارك في دليل العمل الحالي الخاص بك من أجل الحصول على تحويل PDF إلى العمل ، على سبيل المثال مع PATH=%PATH%;c:/program files/wkhtmltopdf/bin أو شيء مماثل ، اعتمادًا على موقع التثبيت الخاص بك.
إذا كنت ترغب في الوصول إلى الواجهة باستخدام سطر الأوامر الخاص بك ، فيمكنك فقط توفير gh-md-to-html مع الوسيطات الموثقة في نص المساعدة (يمكن الوصول إليها مع gh-md-to-html -h وموضحة أدناه). على Windows ، يجب عليك توفير python3 -m gh_md_to_html مع الوسائط المقابلة.
إذا كنت ترغب في الوصول إلى الواجهة عبر Python ، فيمكنك الاستخدام
import gh_md_to_html ثم استخدم gh_md_to_html.main() مع نفس الوسائط (والقيم الافتراضية) التي ستزودها بواجهة سطر الأوامر.
إذا كنت ترغب فقط في تقليد نتائج التحويل من خلال واجهة برمجة تطبيقات REST الخاصة بـ Github ، ولكن لا تريد تخزين الصور ودعم الصيغة وتصميم CSS الفاخرة ، والاستخدام
html_as_a_string = gh_md_to_html.core_converter.markdown(your_markdown_as_a_string)
في بيثون.
الاستخدام : gh-md-to-html <input_name> <optional_arguments>
السلوك الافتراضي :
بشكل افتراضي ، يأخذ GH-MD-to-HTML اسم ملف Markdown كوسيطة ، ويحفظ HTML تم إنشاؤه في ملف يحمل نفس الاسم ، مع .html بدلاً من .md .
بعض المراوغات:
github-markdown-css/github-css.css (إضافة -c لجعلها مضمونة بدلاً من ذلك)../images (إضافة -i لتعطيل هذا).-w إذا كنت ترغب في عرضه مباشرة في متصفح بدلاً من ذلك).id والروابط الداخلية للملفات بواسطة user-content- -بحيث يمكنك تضمين HTML التي تم إنشاؤها في موقع ويب أكبر دون المخاطرة بمواجهات الهوية. بعض حالات الاستخدام الشائعة :
من خلال القضايا السابقة ، أدركت أن هناك بعض حالات الاستخدام الشائعة جدًا التي يبدو أن معظم الناس لديهم لهذه الوحدة. فيما يلي الأكثر شيوعًا ، والخيارات والحجج التي يجب استخدامها لهم:
-i -w --math false --box-width 25cm ، على الرغم من أن Grip قد تكون أكثر كفاءة لهذا الغرض.--toc لدعم بناء جملة TOC Gitlab.--math true --emoji-support 0 --dont-make-images-links true .-i -c للحصول على كل شيء في ملف واحد. تحويل ملفات Markdown من الويب باستخدام --origin-type :
قد لا ترغب ليس فقط في تحويل ملف Markdown المحلي ، ولكن أيضًا ملفًا من مستودع GitHub أو ملف مستضيف على شبكة الإنترنت أو محتويات سلسلة. غالبًا ما لا يكون تنزيلها أو تخزينها في ملف غير كافٍ ، لأن موقعها على الويب يؤثر أيضًا على كيفية حل الروابط إلى الصور التي تشير إليها. لحسن الحظ ، حصل GH-MD-to-HTML على ظهرك!
هناك عدد من الوسائط المختلفة التي يمكنك استخدامها لوصف نوع الملف الذي أعطيته المراجع:
--origin-type file : الافتراضي ؛ يأخذ مسار ملف (نسبي أو مطلق)--origin-type repo : يأخذ PTH إلى ملف Markdown في مستودع GitHub ، بالتنسيق <user_name>/<repo_name>/<branch-name>/<path_to_markdown>.md <branch-name>/<ather_to_markdown> .md.--origin-type web : يأخذ عنوان URL لملف Markdown الذي يستضيفه الويب.--origin-type string : تأخذ سلسلة تحتوي على تخفيض. تؤثر بعض هذه الخيارات التي تستخدمها على كيفية حل روابط الصور داخل ملف Markdown ؛ يوضح قسم لاحق من هذا ReadMe هذا بالتفصيل. صقل ما يسير فيه :
تتم كتابة GH-MD-to-HTML بهدف إنشاء موقع ويب ثابت مضيف لك ، مع دليل العمل الحالي الخاص بك كجذره. بصرف النظر عن استخدام -w لتعطيل ذلك والسماح لك بعرض الملف الذي تم إنشاؤه مباشرة في المتصفح ، هناك عدد من الخيارات التي تسمح لك بضبط ما يسير فيه ، والأكثر شعبية ، جذر الموقع. ليست هناك حاجة للقيام بذلك إلا إذا كنت ترغب في ذلك لسبب ما ، لذلك لا تهتم بقراءة هذا إذا لم تكن بحاجة لذلك!
--website-root (أو -w ): ترك هذا الخيار فارغًا ، كما تمت مناقشته أعلاه ، يتيح لك معاينة ملف HTML الذي تم إنشاؤه مباشرة في المتصفح (على معظم الأنظمة بالنقر المزدوج) في حال كنت لا ترغب في استضافة ملف HTML الذي تم إنشاؤه ، ولكن يمكنك أيضًا توفير أي دليل تريد استخدامه كجذر لموقع الويب. إنه افتراضي إلى دليل العمل الحالي الخاص بك.--destination (أو -d ): المسار ، بالنسبة إلى- --website-root ، حيث يتم تخزين ملف HTML الذي تم إنشاؤه. بشكل افتراضي ، يتم استخدام جذر موقع الويب لهذا.--image-paths (أو -i ): يمكنك ترك هذا فارغًا لتعطيل التخزين المؤقت للصور ، كما هو موضح أعلاه (على الرغم من أن هذا لن يعمل في حالة تعديل --origin-type ) ، أو توفير مسار بالنسبة لجذر موقع الويب لتعديل مكان تخزين الصور. انها الافتراضات images .image-paths تلقائيًا بين عمليات تشغيل متعددة من GH-MD-to-HTML لهذا السبب ، لضمان إمكانية استخدام هذا التحسين المتقاطع عند تحويل ملفات متعددة بكميات كبيرة.--css-paths (أو -c ): يمكنك ترك هذا فارغًا لتعطيل تخزين CSS في ملف CSS خارجي (على سبيل المثال ، إذا كنت ترغب في تحويل ملف واحد فقط) ، كما هو موضح أعلاه ، أو توفير مسار بالنسبة إلى الجذر الإلكتروني لتعديل مكان ملف CSS (يسمى github-css.css ). الافتراضي هو github-markdown-css .--output-name (أو -n ): اسم الملف الذي بموجبه لتخزين ملف HTML الذي تم إنشاؤه في دليل الوجهة. يمكنك استخدام <name> في أي مكان في هذه السلسلة ، وسيتم استبدالها تلقائيًا باسم ملف Markdown ، لذلك ، على سبيل المثال ، سيقوم gh-md-to-html inp.md -n "<name>-conv.html" بتخزين النتيجة في ino-conv.html (هذا لا يعمل مع --origin-type string ، بالطبع).-n print من أجل كتابة الإخراج إلى stdout (طباعته على وحدة التحكم) بدلاً من حفظه في أي مكان. القيمة الافتراضية هي <name>.html ، لذلك تتكيف مع اسم ملف الإدخال الخاص بك.--output-pdf (أو -p ): الملف الذي لتخزين PDF الذي تم إنشاؤه. يمكنك استخدام <name> -syntax هنا أيضًا. إذا لم يتم استخدام -p -Ption ، فلن يتم إنشاء أي PDF (وتحتاج إلى اتباع تعليمات تثبيت PDFKIT & WKHTMLTOPDF أعلاه للحصول على هذا الخيار) ، ولكن يمكنك استخدام -p دون أي وسيطات لاستخدامها <name>.pdf كاسم ملف حساس. التصدير كـ PDF :
كما ذكر أعلاه ، يمكنك تصدير ملف HTML الذي تم إنشاؤه كـ PDF باستخدام --output-pdf -Ption. يتطلب القيام بذلك تثبيت wkhtmltopdf (الإصدار الذي تم تحديده QT) ، لإضافته إلى المسار (إذا كنت على Windows) ، وتثبيت pdfkit (على سبيل المثال عبر pip3 install gh-md-to-html[offline_conversion] ) ، ولكن جميع هذه المتطلبات محددة بالفعل في قسم التثبيت.
هناك بعض الأشياء التي تستحق الإشارة إليها هنا. بادئ ذي بدء ، لا تستخدم هذا الخيار إذا كان لديك معلومات قيمة في ملف يسمى {yourpdfexportdestination}.html ، حيث {yourpdfexportdestination} هو ما قدمته إلى -p ، حيث سيتم الكتابة على هذا الملف مؤقتًا في العملية ؛ علاوة على ذلك ، لا تستخدم -p على الإطلاق إذا كنت تقوم بتزويد مدخلات غير موثوق بها إلى -x -Ption.
هناك أيضًا بعض الخيارات المصممة خصيصًا للاستخدام مع -p ؛ هذه حاليا:
--style-pdf (أو -s ): اضبط هذا على false لتعطيل تصميم ملف PDF الذي تم إنشاؤه باستخدام CSS Github. قد ترغب في القيام بذلك لأن الحدود التي يرسمها CSS من Github حول الصفحة يمكن أن تبدو غير بديهية في PDFs ، على الرغم من أن القيام بذلك يمكن أن يؤثر سلبًا على ظهور أجزاء أخرى ، لذلك استخدم هذا مع حبة من الملح. تغيير المحول الأساسي للاستخدام :
لا يفعل GH-MD-to-HTML في الواقع كل هذا الرفع الثقيل نفسه عندما يتعلق الأمر بتحليل التخفيض وتحويله إلى PDF ؛ بدلاً من ذلك ، يلفت حول ما يسمى "المحول الأساسي" الذي يقوم بالتحويل الأساسي وفقًا للمواصفات المتولد ، وتبني خياراته وميزاته وتخصيصاتها وتصميمها فوق ذلك. بشكل افتراضي ، يتم استخدام واجهة برمجة تطبيقات REST REST GITHUB لذلك ، لأنها تأتي الأقرب إلى ما يفعله Github مع قراءاتها ، ولكن يمكنك أيضًا إعطاء GH-MD-to-HTML أي محول تخفيض أساسي آخر للعمل معه.
يأتي GH-MD-to-HTML أيضًا مع محولات أساسية بديلة للبناء لاستخدامها ، مما يقلد واجهة برمجة تطبيقات REST الخاصة بـ Github في أقرب وقت ممكن مع إضافة لمسة شخصية خاصة بها.
خيار تحديد المحول الأساسي:
--core-converter (أو -o ): يمكنك استخدام هذا الخيار للاختيار من بين عدد من المحولات الأساسية المحددة مسبقًا (انظر أدناه) في حالة اختلافك عن الخيار الافتراضي.
يمكنك أيضًا تزويد الأمر Bash (على أنظمة UNIX/Linux) لهذا ، أو أمر cmd.exe على Windows ، حيث يقف {md} كمكافأة نائبة للمكان الذي يتم فيه إدراج تخفيض الإدخال القذيف بواسطة GH-MD-to-HTML. على سبيل المثال،
gh-md-to-html inp.md -o "pandoc -f markdown -t html <<< {md}"
سوف تستخدم باندوك كمحول أساسي لها.
يمكنك أيضًا القيام بذلك باستخدام أوامر متعددة ، مثل
gh-md-to-html -o "printf {md} >> temp.md; pandoc -f markdown -t html temp.md; rm temp.md" ،
طالما تم طباعة النتيجة إلى stdout.
إذا كنت تستخدم واجهة Python إلى GH-MD-to-HTML ، فيمكنك أيضًا توفير أي وظيفة تقوم بتحويل سلسلة Markdown إلى سلسلة HTML إلى هذه الوسيطة.
المحولات الأساسية المحددة مسبقًا التي يمكنك تزويدها بسهولة --core-converter كأسلاك:
OFFLINE : يقلد واجهة برمجة تطبيقات GitHub Rest Rest ، ولكن في وضع عدم الاتصال باستخدام Mistune. يتطلب هذا التبعيات الاختيارية لتلبية "Online_Conversion" ، باستخدام pip3 install gh-md-to-html[offline_conversion] أو pip3 install mistune>=2.0.0rc1 .OFFLINE+ : يتصرف متطابق مع عدم الاتصال بالإنترنت ، لكنه لا يزيل المحتوى الضار المحتمل مثل JavaScript و CSS مثل Github Rest API عادة. لا تستخدم هذه الميزة إلا إذا كنت بحاجة إلى وسيلة لتحويل ملفات Markdown Secure التي تم فحصها يدويًا دون أن يتم تجريد كل ما تبذلونه من js/styling! الدعم للتشكيلات المضمنة :
يدعم gh-md-to-html ، بشكل افتراضي ، صيغ مضمنة (بغض النظر عن المحول الأساسي ، انظر أعلاه ، يمكنك استخدامه). هذا يعني أنه يمكنك كتابة صيغة اللاتكس بين علامتين دولارتين على نفس الخط ، وسيتم استبدالها بصورة SVG التي تعرض الصيغة المذكورة. على سبيل المثال،
$e = m cdot c^2$
سيضيف صيغة آينشتاين الشهيرة كصورة SVG ، محاذاة جيدة مع بقية النص المحيط به ، في المستند الخاص بك.
يحاول gh-md-to-html دائمًا استخدام تثبيت LaTeX المحلي للقيام بهذا التحويل (ميزة: سريع ولا يتطلب الإنترنت). ومع ذلك ، إذا لم يتم تثبيت LATEX أو DVISVGM أو لا يمكن العثور عليها ، فإنه يستخدم محولًا عبر الإنترنت (ميزة: لا تتطلب منك تثبيت 3 جيجابايت من مكتبات اللاتكس) لتحقيق ذلك.
يمكنك استخدام الخيارات التالية لتعديل هذا السلوك:
--math (أو -m ): اضبط هذا على false لتعطيل عرض الصيغة.--suppress-online-fallbacks : قم بتعيين هذا على true لتعطيل التراجع عبر الإنترنت لتقديم الصيغة ، وزيادة خطأ إذا لم يتم تثبيت متطلباته محليًا أو لا يمكن العثور عليها لسبب ما. تخزين الصور وضغط الصورة :
كما هو موضح في التعمق أعلاه ، يحفظ GH-MD-to-HTML الصور بحيث يمكن تحميلها جميعًا من نفس المجلد. هذا يأتي مع مزايا
بالإضافة إلى هذه المزايا ، يتيح لك GH-MD-to-HTML أيضًا تعيين مستوى من ضغط الصورة لاستخدامه في هذه الصور. إذا قررت القيام بذلك ، فسيتم تحويل كل صورة إلى JPEG (باستخدام لون الخلفية وإعدادات الجودة من رغبتك) ، وسيتم تقليص الصور إذا كانت HTML التي تم إنشاؤها هي أنه لن تكون هناك حاجة إليها بحجمها الكامل على أي حال (يمكنك الاستفادة من هذا EG باستخدام <img> -Tags مباشرة في وثيقتك وتزويدها بقيمة width أو قيمة height .
يعد GH-MD-to-HTML أيضًا المحول الوحيد للتخفيض القادر على الاستفادة من HTML srcset -Attribute ، والذي يسمح للوثيقة التي تم إنشاؤها بالرجوع إلى العديد من الإصدارات المقيدة بشكل مختلف من نفس الصورة ، ثم يقوم المتصفح بتحميل أصغر واحد على أحجام الشاشة الأصغر ، مما يؤدي إلى تخفيضات كبيرة في التحميل على متن الهاتف المحمول. يمكن أن يؤدي تمكين هذه الميزة إلى مزيد من التخفيضات في وقت التحميل دون التضحية بأي جودة صورة مرئية ، مما يجعل GH-MD-to-HTML الخيار الأفضل إذا كنت ترغب في إنشاء مواقع ويب سريعة التحميل من ملفات تخفيض الصور الثقيلة الخاصة بك.
خيار استخدام كل هذا
--compress-images .
ويقبل جزء من بيانات JSON مع السمات التالية:
bg-color : اللون لاستخدامه كأنه لون خلفية عند تحويل صور RGBA إلى JPEG (مؤسسة RGB). الإعدادات الافتراضية لـ " white " وتقبل تقريبًا أي قيمة ملونة HTML5 (" #FFFFFF " و " #ffffff " و " white " و " rgb(255, 255, 255) " كانت كلها قيمًا صالحة).progressive : حفظ الصور كـ JPEGs تقدمية. الافتراضي كاذب.srcset : احفظ إصدارات مختلفة من الصورة بشكل مختلف وقم بتوفيرها للصورة في سمة SRCSET الخاصة بها. الإعدادات الافتراضية إلى خطأ. يأخذ مجموعة من العروض المختلفة أو True ، والتي تعمل كاختصار لـ " [500, 800, 1200, 1500, 1800, 2000] ".quality : قيمة من 0 إلى 100 تصف الجودة التي يجب حفظ الصور. الإعدادات الافتراضية إلى 90. إذا تم تحديد حجم معين لصورة محددة في HTML ، يتم تحويل الصورة دائمًا إلى الحجم الأيمن قبل تقليل الجودة.إذا تركت هذه الحجة فارغة ، فلا يتم استخدام أي ضغط على الإطلاق. إذا تم تعيين هذه الوسيطة على TRUE ، يتم استخدام جميع القيم الافتراضية. إذا تم تعيينها على بيانات JSON وتم حذف بعض القيم ، يتم استخدام الافتراضيات لهذه.
يمكنك أيضًا تمرير DICT بدلاً من سلسلة تحتوي على بيانات JSON إذا كنت تستخدم هذا الخيار في الواجهة الأمامية Python.
لن يعمل ضغط الصورة ، لأسباب واضحة ، إذا كنت تستخدم -i لتعطيل التخزين المؤقت للصور.
اختياراتي الشخصية :
يتخذ تخفيض التنقل والتخفيض بشكل عام بشكل عام بعض الخيارات غير الشعبية ، كما أن GH-MD-to-HTML ، مما يقلدها ، تقوم أيضًا بالكثير من هذه الخيارات. إذا لم يكن هدفك أقرب ما يمكن إلى تخفيض (GitHub-slavor) ، وكنت ترغب في استخدام الطاقة الكاملة التي يوفرها GH-MD-to-HTML إلى أقصى حد ، أوصي بقائمة الإعدادات والخيارات التالية (المأخوذة للغاية). لاحظ أن بعضها غير آمن عند تحويل المحتوى الذي تم إنشاؤه بواسطة المستخدم.
--math true : تم تمكين هذا بالفعل افتراضيًا ، لذلك ليس توصية حقًا ، لكن على الأرجح تريد الحصول على دعم الرياضيات اللاتكس في ملفك.--core-converter OFFLINE+ : هذا يحول ملفات Markdown في وضع عدم الاتصال بدلاً من استخدام واجهة برمجة تطبيقات REST الخاصة بـ Github ، ويسمح باستخدام أشياء غير آمنة مثل الرمز المضمن وكل HTML الذي يمكن أن ترغب فيه في ملف Mermdown.--compress-images : هناك العديد من الطرق لتحديد هذه الخيارات ، ولكنها تتيح بعض التحسينات الرائعة على الصور المخزنة مؤقتًا ، بما في ذلك استخدام HTML srcset -Attribute ، والتي لا يدعم أي محول آخر حاليًا AFAIK.--box-width 25cm : من المرجح أن ترغب في الحد من عرض المربع الذي يتم فيه عرض محتوى موقع الويب الذي تم إنشاؤه لأسباب قابلية القراءة ، إلا إذا كنت تخطط لتضمين HTML تم إنشاؤها في ملف HTML أكبر.--toc true : يتيح لك هذا استخدام [[_TOC_]] كاختصار لجدول المحتويات في الملف الذي تم إنشاؤه.--dont-make-images-links true ، ، ، يلف جيثب كل صورة في رابط لمصدر الصورة ، ما لم تكن الصورة ملفوفة بالفعل في رابط مختلف. يعطل هذا الخيار هذا السلوك لمزيد من التحكم في روابط صورتك.--emoji-support 2 : GH-MD-to-HTML يدعم استخدام الرموز المختصرة Emoji ، مثل :joy: ، والتي يتم استبدالها بعد ذلك مع الرموز التعبيرية في ملف HTML الذي تم إنشاؤه. -يأخذ --emoji-support 2 هذا المستوى الواحد من خلال السماح لك باستخدام الرموز التعبيرية المخصصة الخاصة بك ، لذلك :path/to/funny_image.png: سوف تضيف funny_image.png .--soft-wrap-in-code-boxes true افتراضي ، يعرض Github صناديق الرموز المتعددة مع شريط تمرير أفقي إذا كانت معرضة لخطر الفائض. استخدم هذا الخيار للحصول على (IMHO أكثر منطقية) في مربعات الرمز بدلاً من ذلك. يرجى ملاحظة أن الخيارات مدرجة من خلال الأهمية ، وكلها لها افتراضات معقولة ، لذلك لا تشعر بالإرهاق من عددهم ؛ يمكنك فقط قراءتها حتى تجد ما تبحث عنه ، وتجاهل الباقي بأمان.
تهدف معظم الخيارات إلى تخصيص السلوك الافتراضي ، لذلك لا يوجد أي منها إلزامي لمعظم حالات الاستخدام.
usage: __main__.py [-h] [-t {file,repo,web,string}]
[-w WEBSITE_ROOT [WEBSITE_ROOT ...]]
[-d DESTINATION [DESTINATION ...]]
[-i [IMAGE_PATHS [IMAGE_PATHS ...]]]
[-c CSS_PATHS [CSS_PATHS ...]]
[-n OUTPUT_NAME [OUTPUT_NAME ...]]
[-p OUTPUT_PDF [OUTPUT_PDF ...]] [-s STYLE_PDF]
[-f FOOTER [FOOTER ...]] [-m MATH]
[-x EXTRA_CSS [EXTRA_CSS ...]]
[-o CORE_CONVERTER [CORE_CONVERTER ...]]
[-e COMPRESS_IMAGES [COMPRESS_IMAGES ...]]
[-b BOX_WIDTH [BOX_WIDTH ...]] [-a TOC]
MD-origin [MD-origin ...]
Convert markdown to HTML using the GitHub API and some additional tweaks with
python.
positional arguments:
MD-origin Where to find the markdown file that should be
converted to html
optional arguments:
-h, --help show this help message and exit
-t {file,repo,web,string}, --origin-type {file,repo,web,string}
In what way the MD-origin-argument describes the origin
of the markdown file to use. Defaults to file. The
options mean:
* file: takes a relative or absolute path to a file
* repo: takes a path to a markdown-file in a github
repository, such as <user_name>/<repo_name>/<branch-
name>/<path_to_markdown>.md
* web: takes an url to a markdown file
* string: takes a string containing the files content
-w WEBSITE_ROOT [WEBSITE_ROOT ...], --website-root WEBSITE_ROOT [WEBSITE_ROOT ...]
Only relevant if you are creating the html for a static
website which you manage using git or something similar.
--website-root is the directory from which you serve
your website (which is needed to correctly generate the
links within the generated html, such as the link
pointing to the css, since they are all root- relative),
and can be a relative as well as an absolute path.
Defaults to the directory you called this script from.
If you intent to view the html file on your laptop
instead of hosting it on a static site, website-root
should be a dot and destination not set. The reason the
generated html files use root-relative links to embed
images is that on many static websites,
https://foo/bar/index.html can be accessed via
https://foo/bar, in which case relative (non-root-
relative) links in index.html will be interpreted as
relative to foo instead of bar, which can cause images
not to load.
-d DESTINATION [DESTINATION ...], --destination DESTINATION [DESTINATION ...]
Where to store the generated html. This path is relative
to --website-root. Defaults to "".
-i [IMAGE_PATHS [IMAGE_PATHS ...]], --image-paths [IMAGE_PATHS [IMAGE_PATHS ...]]
Where to store the images needed or generated for the
html. This path is relative to website-root. Defaults to
the "images"-folder within the destination folder. Leave
this option empty to completely disable image
caching/downloading and leave all image links
unmodified.
-c CSS_PATHS [CSS_PATHS ...], --css-paths CSS_PATHS [CSS_PATHS ...]
Where to store the css needed for the html (as a path
relative to the website root). Defaults to the
"<WEBSITE_ROOT>/github-markdown-css"-folder.
-n OUTPUT_NAME [OUTPUT_NAME ...], --output-name OUTPUT_NAME [OUTPUT_NAME ...]
What the generated html file should be called like. Use
<name> within the value to refer to the name of the
markdown file that is being converted (if you don't use
"-t string"). You can use '-n print' to print the file
(if using the command line interface) or return it (if
using the python module), both without saving it.
Default is '<name>.html'.
-p OUTPUT_PDF [OUTPUT_PDF ...], --output-pdf OUTPUT_PDF [OUTPUT_PDF ...]
If set, the file will also be saved as a pdf file in the
same directory as the html file, using pdfkit, a python
library which will also need to be installed for this to
work. You may use the <name> variable in this value like
you did in --output-name. Do not use this with the -c
option if the input of the -c option is not trusted;
execution of malicious code might be the consequence
otherwise!!
-s STYLE_PDF, --style-pdf STYLE_PDF
If set to false, the generated pdf (only relevant if you
use --output-pdf) will not be styled using github's css.
-f FOOTER [FOOTER ...], --footer FOOTER [FOOTER ...]
An optional piece of html which will be included as a
footer where the 'hosted with <3 by github'-footer in a
gist usually is. Defaults to None, meaning that the
section usually containing said footer will be omitted
altogether.
-m MATH, --math MATH If set to True, which is the default, LaTeX-formulas
using $formula$-notation will be rendered.
-x EXTRA_CSS [EXTRA_CSS ...], --extra-css EXTRA_CSS [EXTRA_CSS ...]
A path to a file containing additional css to embed into
the final html, as an absolute path or relative to the
working directory. This file should contain css between
two <style>-tags, so it is actually a html file, and can
contain javascript as well. It's worth mentioning and
might be useful for your css/js that every element of
the generated html is a child element of an element with
id xxx, where xxx is "article-" plus the filename
(without extension) of:
* output- name, if output-name is not "print" and not
the default value.
* the input markdown file, if output- name is "print",
and the input type is not string. * the file with the
extra-css otherwise. If none of these cases applies, no
id is given.
-o CORE_CONVERTER [CORE_CONVERTER ...], --core-converter CORE_CONVERTER [CORE_CONVERTER ...]
The converter to use to convert the given markdown to
html, before additional modifications such as formula
support and image downloading are applied; this defaults
to using GitHub's REST API and can be
* on Unix/ any system with a cmd: a command containing
the string "{md}", where "{md}" will be replaced with an
escaped version of the markdown file's content, and
which returns the finished html. Please note that
commands for Unix-system won't work on Windows systems,
and vice versa etc.
* when using gh-md-to- html in python: A callable which
converts markdown to html, or a string as described
above.
* OFFLINE as a value to indicate that gh-md-to-html
should imitate the output of their builtin
md-to-html-converter using mistune. This requires the
optional dependencies for "offline_conversion" to be
satisfied, by using `pip3 install
gh-md-to-html[offline_conversion]` or `pip3 install
mistune>=2.0.0rc1`.
* OFFLINE+ behaves identical to OFFLINE, but it doesn't
remove potentially harmful content like javascript and
css like the GitHub REST API usually does. DO NOT USE
THIS FEATURE unless you need a way to convert secure
manually-checked markdown files without having all your
inline js stripped away!
-e COMPRESS_IMAGES [COMPRESS_IMAGES ...], --compress-images COMPRESS_IMAGES [COMPRESS_IMAGES ...]
Reduces load time of the generated html by saving all
images referenced by the given markdown file as jpeg.
This argument takes a piece of json data containing the
following information; if it is not used, no compression
is done:
* bg-color: the color to use as a background color when
converting RGBA-images to jpeg (an RGB-format). Defaults
to "white" and accepts almost any HTML5 color-value
("#FFFFFF", "#ffffff", "white" and "rgb(255, 255, 255)"
would've all been valid values).
* progressive: Save images as progressive jpegs. Default
is False.
* srcset: Save differently scaled versions of the image
and provide them to the image in its srcset attribute.
Defaults to False. Takes an array of different widths or
True, which serves as a shortcut for "[500, 800, 1200,
1500, 1800, 2000]".
* quality: a value from 0 to 100 describing at which
quality the images should be saved (this is done after
they are scaled down, if they are scaled down at all).
Defaults to 90. If a specific size is specified for a
specific image in the html, the image is always
converted to the right size. If this argument is left
empty, no compression is down at all. If this argument
is set to True, all default values are used. If it is
set to json data and values are omitted, the defaults
are also used. If a dict is passed instead of json data
(when using the tool as a python module), the dict is
used as the result of the json data.
-b BOX_WIDTH [BOX_WIDTH ...], --box-width BOX_WIDTH [BOX_WIDTH ...]
The text of the rendered file is always displayed in a
box, like GitHub READMEs and issues are. By default,
this box fills the entire screen (max-width: 100%), but
you can use this option to reduce its max width to be
more readable when hosted stand-alone; the resulting box
is always centered. --box-width accepts the same
arguments the css max-width attribute accepts, e.g. 25cm
or 800px.
-a TOC, --toc TOC Enables the use of `[[_TOC_]]`, `{:toc}` and `[toc]`
at the beginning of an otherwise empty line to create a
table of content for the document. These syntax are
supported by different markdown flavors, the most
prominent probably being GitLab-flavored markdown
(supports `[[_TOC_]]`), and since GitLab displays its
READMEs quite similar to how GitHub does it, this option
was added to improve support for GitLab- flavored
markdown.
كما هو مذكور أعلاه ، يتم تخزين أي صورة مشار إليها في ملف Markdown محليًا والرجوع إليها باستخدام ارتباطات تشعبية تربية الجذر في HTML التي تم إنشاؤها. كيف يخمن المحول موقع الصورة في الجدول التالي ، مع ملاحظة نوع ImageLink في الجزء العلوي ونوع تخفيض الإدخال المذكور على اليسار:
https:// أو http:// | القيمة المطلقة. فيليب | rel. فيليب | بدءا من / (على سبيل المثال /imagedir/image.png ) | لا تبدأ بـ / (على سبيل المثال imagedir/image.png ) | |
|---|---|---|---|---|---|
-t file | من العنوان | القيمة المطلقة. فيليب | rel. FilePath (من حيث يكمن .md -file) | - | - |
-t string | من العنوان | ABS.FilePath ، ولكن يحتاج إلى تأكيد لأسباب أمنية | rel. FilePath (إلى حيث يتم استدعاء الأداة من) ، ولكن يحتاج إلى تأكيد لأسباب أمنية | - | - |
username/repo/dir/file.md -t repo | من العنوان | - | - | username/repo/imagedir/image.png | username/repo/dir/imagedir/image.png |
https://foo.com/bar/baz.md -t web | من العنوان | - | - | https://foo.com/image.png | https://foo.com/bar/image.png |
كما هو الحال مع جميع مشاريعي ، فإن التعليقات (حتى لو كانت مجرد شيء صغير مثل إخباري بحالة الاستخدام لمشروعي ، أو تخبرني أنك لم تعجبك بنية Readme ، أو تخبرني أنك أحببت على وجه التحديد ميزة محددة) ، وتساعدني على جعل هذا المشروع أفضل ، حتى لو كان شيئًا صغيرًا للغاية! يمكنك فقط إسقاط مشكلة في ملاحظاتك ، قصيرة وغير رسمية ، أو حتى مراسلتي عبر البريد الإلكتروني إذا كنت لا ترغب في إثارة مشكلة لسبب ما. لا أخطط لإضافة ميزات في المستقبل في الوقت الحالي ، لكنني دائمًا منفتح على إصلاح الميزات الحالية وتبديلها ، والتوثيق وما إلى ذلك ، ومن الواضح أنني أحب سماع اقتراحات الميزة الخاصة بك حتى لو لم أخطط لإضافتها في المستقبل القريب.
أنا بشكل عام مستجيب للغاية عندما يتعلق الأمر بقضايا GitHub ، وأخذها جادة للغاية وأحاول حلها في أسرع وقت ممكن. إذا واجهت الأخطاء والسلوكيات الغريبة وأخطاء التثبيت وما شابه ذلك أثناء استخدام أداتي ، فلا تتردد في إخباري في مشكلة ، حتى أتمكن من حل المشكلة!
إذا وجدت هذه الأداة مفيدة ، فالرجاء التفكير في بطولة على Github لتظهر لي تقديرك! سأقدر أيضًا إذا أخبرتني عن المشكلات التي واجهتها حتى لو تمكنت من إصلاحها في نسختك الخاصة من الرمز ، حتى أتمكن من إصلاحها في هذا الريبو أيضًا.
gh-md-to-html لتحويل MD إلى PDF (تحت جوهر حول تحويل MD إلى PDF): الرابطgh-md-to-html في وثائق مشروع آخر: الرابطتم صنع الرموز بواسطة
.md-file.icon: freepik من flaticon.com
.md-file.icon: freepik من flaticon.com
Arrow-Icon: Font Awesome by Dave Gandy ، مرخصة بموجب سهم الإسناد الإبداعي الإبداعي على حد سواء 3.0 Unported
Github-icon: أيقونة Github على Iconscout
إخلاء المسئولية : لا تتم كتابة هذه الوحدة النمطية بواسطة Github ، ولا يتم تأييدها مع Github ، بدعم من Github ، مدعوم من Github أو تابعة لـ Github. لا يستخدم سوى واجهة برمجة تطبيقات عامة توفرها GitHub وكذلك ملف ترخيص من قبل Github بموجب ترخيص معهد ماساتشوستس للتكنولوجيا.
