github flavored markdown to html
1.0.0
Modul Python yang ramah pengguna dan frontend baris perintah untuk mengonversi Markdown ke HTML. Ini menggunakan githubs online-ke-html-API secara default (yang memerlukan koneksi internet), tetapi dilengkapi dengan opsi untuk konversi offline (yang secara erat meniru perilaku GitHubs), dan alat Python- atau Commandline lainnya dapat dicolokkan ke dalamnya juga. Apa pun yang Anda gunakan secara otomatis diperluas dengan satu ton fungsionalitas, seperti lebih banyak opsi in-dan output, CSS rasa gitub, dukungan formula, caching gambar canggih dan optimasi, penempatan file dan gambar yang siap host dan lebih banyak lagi.
Sementara tujuan utamanya adalah pembuatan halaman statis dari file-file markdown, misalnya dalam hubungannya dengan pembangun situs web statis atau tindakan github jika Anda meng-host di GitHub, itu dapat digunakan dengan sangat baik untuk tujuan lain apa pun.
Berikut adalah daftar (tidak harus luas) dari keuntungan dan fitur -fiturnya:
$ -Formula- $ untuk menggunakannya), yang biasanya tidak dilakukan oleh GitHub. GH-MD-to-HTML menggunakan lateks dan DVISVGM jika keduanya diinstal (keuntungan: cepat, tidak memerlukan internet), dan sebaliknya codecogs eqneditor (keuntungan: tidak mengharuskan Anda menginstal 3 GB perpustakaan lateks) untuk mencapai ini.[[_TOC_]] , {:toc} dan [toc] di awal garis kosong yang sebaliknya untuk membuat tabel konten untuk dokumen, seperti markdown yang penuh rasa gitlab, antara lain.Jika Anda mencari alternatif untuk Pandoc untuk mengubah penurunan harga menjadi PDF, berikut adalah daftar alasan mengapa Anda ingin menggunakan GH-MD-to-HTML alih-alih Pandoc untuk pekerjaan itu:
Sementara menggunakan Pandoc untuk dikonversi dari penurunan harga ke PDF biasanya menghasilkan hasil yang lebih indah (Pandoc menggunakan lateks, setelah semua), GH-MD-to-HTML memiliki seperangkat keuntungan sendiri ketika datang untuk dengan cepat mengonversi file kompleks untuk penugasan pekerjaan rumah atau tujuan lain di mana keandalan lebih berat daripada keindahan:
$ -Sign dan karakter apa rumus yang mungkin dimulai. Namun, aturan-aturan ini tidak berlaku di beberapa editor penurunan harga yang umum seperti MarkText, yang mengarah pada banyak frustrasi ketika rumus yang bekerja di editor tidak berfungsi lagi ketika mengonversi dengan Pandoc (Fungsi Ekspor-ke-PDF Marktext kadang-kadang gagal pada file yang berat tanpa formula tanpa pesan kesalahan, yang membuatnya lebih kurang dapat diandalkan). Bagian terburuknya adalah bahwa, setiap kali Pandoc gagal mengubah .md menjadi .pdf karena ini, itu menunjukkan jumlah garis kesalahan berdasarkan pada file .tex menengah alih-alih input .md-file, yang membuatnya sulit untuk menemukan akar masalah. Seperti yang mungkin sudah Anda duga, GH-MD-to-HTML tidak peduli tentang jumlah whitespasi Anda yang memulai formula Anda, menyerahkan keputusan ini kepada Anda.Singkatnya, tindakan konversi MD-to-PDF Pandoc sangat tidak biasa dalam hal gambar, daftar bersarang, entri titik peluru multilin, atau formula, dan GH-MD-to-HTML tidak.
Gunakan pip3 install gh-md-to-html untuk menginstal langsung dari indeks paket Python, atau python3 -m pip install gh-md-to-html jika Anda menggunakan Windows.
Keduanya mungkin membutuhkan sudo di Linux, dan Anda dapat melakukannya secara opsional
python3 -m pip install gh-md-to-html[pdf_export]
dan instal WKHTMLTOPDF (v0.12.6 atau lebih besar) untuk mendapatkan fitur konversi PDF opsional dan mengonversi file Markdown ke PDF, dan/atau
python3 -m pip install gh-md-to-html[offline_conversion]
Untuk mendapatkan fitur dan berjalan-konversi offline opsional.
Jika Anda berada di Windows , Anda mungkin harus menambahkan wkhtmltopdf ke jalur Anda di direktori kerja Anda saat ini untuk mendapatkan konversi PDF berfungsi, misalnya dengan PATH=%PATH%;c:/program files/wkhtmltopdf/bin atau sesuatu yang serupa, tergantung pada lokasi instalasi Anda.
Jika Anda ingin mengakses antarmuka dengan baris perintah Anda, Anda dapat menyediakan gh-md-to-html dengan argumen yang didokumentasikan dalam teks bantuan (dapat diakses dengan gh-md-to-html -h dan ditampilkan di bawah). Di Windows, Anda harus menyediakan python3 -m gh_md_to_html dengan argumen yang sesuai.
Jika Anda ingin mengakses antarmuka melalui Python, Anda dapat menggunakan
import gh_md_to_html dan kemudian gunakan gh_md_to_html.main() dengan argumen yang sama (dan nilai default) Anda akan menyediakan ke antarmuka baris perintah.
Jika Anda hanya ingin meniru hasil hasil konversi dengan API REST GitHub secara offline, tetapi tidak ingin caching gambar, dukungan formula dan gaya CSS mewah, gunakan
html_as_a_string = gh_md_to_html.core_converter.markdown(your_markdown_as_a_string)
di Python.
Penggunaan : gh-md-to-html <input_name> <optional_arguments>
Perilaku default :
Secara default, GH-MD-to-HTML mengambil nama file markdown sebagai argumen, dan menyimpan HTML yang dihasilkan dalam file dengan nama yang sama, dengan .html bukan .md .
Beberapa keanehan:
github-markdown-css/github-css.css (add -c untuk membuatnya sejalan)../images (tambahkan -i untuk menonaktifkan ini).-w jika Anda ingin secara langsung melihatnya di browser sebagai gantinya).id dan file-internal diawali dengan user-content- , sehingga Anda dapat menanamkan HTML yang dihasilkan di situs web yang lebih besar tanpa mempertaruhkan bentrokan ID. Beberapa kasus penggunaan umum :
Melalui masalah masa lalu, saya menyadari bahwa ada beberapa kasus penggunaan yang sangat umum yang tampaknya dimiliki kebanyakan orang untuk modul ini. Berikut adalah yang paling umum, dan opsi dan argumen mana yang digunakan untuk mereka:
-i -w --math false --box-width 25cm , meskipun cengkeraman mungkin lebih efisien untuk tujuan ini.--toc untuk mendukung sintaks TOC Gitlab.--math true --emoji-support 0 --dont-make-images-links true .-i -c untuk memiliki semuanya dalam satu file. Mengonversi file Markdown dari web dengan --origin-type :
Anda mungkin ingin tidak hanya mengonversi file markdown lokal, tetapi juga file dari repositori GitHub, yang di-host web, atau isi string. Cukup mengunduh ini atau menyimpannya dalam file seringkali tidak cukup, karena lokasi mereka di web juga mempengaruhi bagaimana tautan ke gambar yang mereka referensi harus diselesaikan. Untungnya, GH-MD-to-HTML telah mendukung Anda!
Ada sejumlah argumen berbeda yang dapat Anda gunakan untuk menggambarkan jenis file apa yang Anda berikan referensi:
--origin-type file : default; mengambil jalur file (relatif atau absolut)--origin-type repo : Membawa PTH ke file markdown di repositori GitHub, dalam format <user_name>/<repo_name>/<branch-name>/<path_to_markdown>.md .md.--origin-type web : Mengambil URL dari file markdown yang di-host web.--origin-type string : Mengambil string yang berisi markdown. Beberapa opsi yang Anda gunakan mempengaruhi bagaimana tautan gambar dalam file markdown diselesaikan; Bagian selanjutnya dari Readme ini menguraikan ini secara rinci. Menyempurnakan apa yang pergi ke mana :
GH-MD-to-HTML ditulis dengan tujuan menghasilkan situs web statis siap host untuk Anda, dengan direktori kerja Anda saat ini sebagai root. Selain menggunakan -w untuk menonaktifkan ini dan memungkinkan Anda untuk melihat file yang dihasilkan langsung di browser, ada sejumlah opsi yang memungkinkan Anda untuk menyempurnakan apa yang terjadi di mana, dan paling populer, ubah akar situs web. Tidak perlu melakukannya kecuali Anda ingin beberapa alasan, jadi jangan repot -repot membaca ini jika Anda tidak perlu!
--website-root (atau -w ): Membiarkan opsi ini kosong, seperti yang dibahas di atas, memungkinkan Anda untuk melihat pratinjau file HTML yang dihasilkan langsung di browser (pada sebagian besar sistem dengan mengklik dua kali) jika Anda tidak ingin meng-host file HTML yang dihasilkan, tetapi Anda juga dapat menyediakan direktori apa pun yang ingin Anda gunakan sebagai root situs web untuk ini. Itu default ke direktori kerja Anda saat ini.--destination (atau -d ): Path, relatif terhadap --website-root , di mana file html yang dihasilkan disimpan. Secara default, root situs web digunakan untuk ini.--image-paths (atau -i ): Anda dapat meninggalkan ini kosong untuk menonaktifkan caching gambar, seperti yang dijelaskan di atas (meskipun ini tidak akan berfungsi jika Anda memodifikasi --origin-type ), atau menyediakan jalur relatif terhadap root situs web untuk memodifikasi di mana gambar disimpan. Itu default ke images .image-paths -direktori tidak dikosongkan secara otomatis antara beberapa proses GH-MD-to-HTML karena alasan ini, untuk memastikan bahwa optimasi ini dapat digunakan lintas file saat mengonversi beberapa file dalam jumlah besar.--css-paths (atau -c ): Anda dapat meninggalkan ini kosong untuk menonaktifkan menyimpan CSS dalam file CSS eksternal (EG yang berguna jika Anda ingin mengonversi hanya satu file), seperti dijelaskan di atas, atau memasok jalur relatif terhadap root situs web untuk memodifikasi di mana file CSS (disebut github-css.css ) akan disimpan. Standarnya adalah github-markdown-css .--output-name (atau -n ): Nama file yang digunakan untuk menyimpan file HTML yang dihasilkan di Destination-Directory. Anda dapat menggunakan <name> di mana saja di string ini, dan secara otomatis akan diganti dengan nama file markdown, jadi, misalnya, gh-md-to-html inp.md -n "<name>-conv.html" akan menyimpan hasilnya di ino-conv.html (ini tidak berfungsi dengan --origin-type string , tentu saja).-n print untuk hanya menulis output ke stdout (cetak di konsol) alih -alih menyimpannya di mana saja. Nilai default adalah <name>.html , sehingga beradaptasi dengan nama file input Anda.--output-pdf (atau -p ): File tempat untuk menyimpan PDF yang dihasilkan. Anda dapat menggunakan <name> -synax di sini juga. Jika -p -Option tidak digunakan, tidak ada PDF yang akan dihasilkan (dan Anda harus mengikuti instruksi pemasangan PDFKIT & WKHTMLTOPDF di atas agar opsi ini berfungsi), tetapi Anda dapat menggunakan -p tanpa argumen untuk menggunakan <name>.pdf sebagai default nama file yang sensitif. mengekspor sebagai pdf :
Seperti disebutkan di atas, Anda dapat mengekspor file HTML yang dihasilkan sebagai PDF menggunakan --output-pdf -Option. Melakukan hal itu mengharuskan Anda untuk menginstal wkhtmltopdf (versi QT-Patched), untuk menambahkannya ke jalur (jika Anda berada di windows), dan untuk menginstal pdfkit (misalnya melalui pip3 install gh-md-to-html[offline_conversion] ), tetapi semua persyaratan ini sudah diuraikan di atas di bagian instalasi.
Ada beberapa hal yang patut dicatat di sini. Pertama -tama, jangan gunakan opsi ini jika Anda memiliki informasi berharga dalam file yang disebut {yourpdfexportdestination}.html , di mana {yourpdfexportdestination} adalah apa yang Anda pasang ke -p , karena file ini akan ditimpa sementara dalam proses tersebut; Selain itu, jangan gunakan -p sama sekali jika Anda menyediakan input yang tidak dipercaya ke -x -Option.
Ada juga beberapa opsi yang dirancang khusus untuk digunakan dengan -p ; Ini saat ini:
--style-pdf (atau -s ): Setel ini ke false untuk menonaktifkan gaya file PDF yang dihasilkan dengan CSS GitHub. Anda mungkin ingin melakukan ini karena perbatasan yang ditarik oleh CSS GitHub di sekitar halaman dapat terlihat berlawanan dengan intuisi dalam PDF, meskipun hal itu juga dapat mempengaruhi penampilan bagian lain secara negatif, jadi gunakan ini dengan sebutir garam. Mengubah konverter markdown inti mana yang akan digunakan :
GH-MD-to-HTML sebenarnya tidak melakukan banyak hal yang berat dalam hal penurunan harga dan mengubahnya menjadi PDF; Sebagai gantinya, ia membungkus apa yang disebut "konverter inti" yang melakukan konversi dasar sesuai dengan spesifikasi penurunan harga, dan membangun opsi, fitur, kustomisasi, dan gaya sendiri di atas itu. Secara default, API REST Markdown GitHub digunakan untuk itu, karena paling dekat dengan apa yang dilakukan GitHub dengan Readmes-nya, tetapi Anda juga dapat memberikan GH-MD-to-HTML konverter penurunan harga dasar lainnya untuk dikerjakan.
GH-MD-to-HTML juga hadir dengan dua konverter inti alternatif build-in untuk digunakan, yang meniru API REST GitHub sedekat mungkin sambil menambahkan sentuhan pribadi mereka sendiri.
Opsi untuk memutuskan konverter inti:
--core-converter (atau -o ): Anda dapat menggunakan opsi ini untuk memilih dari sejumlah konverter inti yang telah ditentukan sebelumnya (lihat di bawah) jika Anda ingin berbeda dari yang default.
Anda juga dapat menyediakan perintah bash (pada sistem unix/linux) untuk ini, atau perintah cmd.exe pada windows, di mana {md} berdiri sebagai placeholder di mana markdown input yang dikukuhkan shell akan dimasukkan oleh GH-MD-to-HTML. Misalnya,
gh-md-to-html inp.md -o "pandoc -f markdown -t html <<< {md}"
akan menggunakan Pandoc sebagai konverter intinya.
Anda juga dapat melakukannya dengan menggunakan beberapa perintah, seperti
gh-md-to-html -o "printf {md} >> temp.md; pandoc -f markdown -t html temp.md; rm temp.md" ,
Selama hasilnya dicetak ke stdout.
Jika Anda menggunakan interface python ke GH-MD-to-HTML, Anda juga dapat menyediakan fungsi apa pun yang mengubah string penurunan harga menjadi string HTML ke argumen ini.
Konverter inti yang telah ditentukan sebelumnya yang dapat dengan mudah Anda pasang --core-converter sebagai string:
OFFLINE : Meniru API REST Markdown GitHub, tetapi offline menggunakan Mistune. Ini membutuhkan dependensi opsional untuk "offline_conversion" untuk dipenuhi, dengan menggunakan pip3 install gh-md-to-html[offline_conversion] atau pip3 install mistune>=2.0.0rc1 .OFFLINE+ : Perilaku identik dengan offline, tetapi tidak menghapus konten yang berpotensi berbahaya seperti JavaScript dan CSS seperti biasanya API REST GITHUB. Jangan gunakan fitur ini kecuali Anda memerlukan cara untuk mengonversi file markdown yang diperiksa secara manual tanpa semua JS/styling inline Anda dilucuti! Dukungan untuk formula inline :
Dukungan gh-md-to-html , secara default, rumus inline (tidak peduli konverter inti mana, lihat di atas, Anda gunakan). Ini berarti bahwa Anda dapat menulis formula lateks antara dua tanda dolar pada baris yang sama, dan itu akan diganti dengan gambar SVG yang menampilkan formula tersebut. Misalnya,
$e = m cdot c^2$
Akan menambahkan formula Einstein yang terkenal sebagai gambar SVG, selaras dengan sisa teks di sekitarnya, ke dalam dokumen Anda.
gh-md-to-html selalu mencoba menggunakan instalasi lateks lokal Anda untuk melakukan konversi ini (keuntungan: cepat dan tidak memerlukan internet). Namun, jika LaTeX atau DVISVGM tidak diinstal atau tidak dapat menemukannya, ia menggunakan konverter online (keuntungan: tidak mengharuskan Anda menginstal 3 GB perpustakaan lateks) untuk mencapai ini.
Anda dapat menggunakan opsi berikut untuk memodifikasi perilaku ini:
--math (atau -m ): Atur ini ke false untuk menonaktifkan rendering rumus.--suppress-online-fallbacks : true ini untuk menonaktifkan fallback online untuk rendering rumus, meningkatkan kesalahan jika persyaratannya tidak dipasang secara lokal atau tidak dapat ditemukan karena beberapa alasan. Caching gambar dan kompresi gambar :
Seperti yang dijelaskan secara mendalam di atas, GH-MD-to-HTML menyimpan gambar sehingga semuanya dapat dimuat dari folder yang sama. Ini datang dengan keunggulan
Selain keunggulan ini, GH-MD-to-HTML juga memungkinkan Anda untuk mengatur tingkat kompresi gambar untuk digunakan untuk gambar-gambar ini. Jika Anda memutuskan untuk melakukannya, setiap gambar akan dikonversi ke JPEG (menggunakan warna latar belakang dan pengaturan kualitas yang Anda sukai), dan gambar akan diturunkan jika HTML yang dihasilkan menyatakan bahwa mereka tidak akan diperlukan pada ukuran penuh mereka (Anda dapat menggunakan EG ini dengan menggunakan <img> -tags langsung dalam dokumen Anda dan memasok mereka dengan width eksplisit atau height .
GH-MD-to-HTML juga merupakan satu-satunya konverter penurunan harga yang mampu memanfaatkan HTML srcset -Attribute, yang memungkinkan dokumen yang dihasilkan untuk merujuk beberapa versi skala yang berbeda dari gambar yang sama, di antaranya browser kemudian akan memuat satu yang terkecil. Mengaktifkan fitur ini dapat menyebabkan pengurangan waktu pemuatan lebih lanjut tanpa mengorbankan kualitas gambar yang terlihat, yang menjadikan GH-MD-to-HTML pilihan terbaik jika Anda ingin menghasilkan situs web pemuatan cepat dari file penurunan gambar yang berat gambar Anda.
Opsi untuk digunakan untuk semua ini adalah
--compress-images .
Dan itu menerima sepotong data JSON dengan atribut berikut:
bg-color : Warna yang akan digunakan sebagai warna latar belakang saat mengonversi gambar RGBA menjadi JPEG (format RGB). Default untuk " white " dan menerima hampir semua nilai warna html5 (" #FFFFFF ", " #ffffff ", " white " dan " rgb(255, 255, 255) " semuanya akan menjadi nilai yang valid).progressive : Simpan gambar sebagai JPEG progresif. Default salah.srcset : Simpan versi gambar skala yang berbeda dan berikan mereka pada gambar dalam atribut SRCSET -nya. Default ke false. Mengambil serangkaian lebar atau True , yang berfungsi sebagai jalan pintas untuk " [500, 800, 1200, 1500, 1800, 2000] ".quality : Nilai dari 0 hingga 100 menggambarkan kualitas gambar harus disimpan. Default ke 90. Jika ukuran tertentu ditentukan untuk gambar tertentu dalam HTML, gambar selalu dikonversi ke ukuran yang tepat sebelum mengurangi kualitas.Jika argumen ini dibiarkan kosong, tidak ada kompresi yang digunakan sama sekali. Jika argumen ini diatur ke true, semua nilai default digunakan. Jika diatur ke data JSON dan beberapa nilai dihilangkan, yang default digunakan untuk ini.
Anda juga dapat melewati dikte alih -alih string yang berisi data JSON jika Anda menggunakan opsi ini di frontend Python.
Kompresi gambar tidak akan berhasil, karena alasan yang jelas, jika Anda menggunakan -i untuk menonaktifkan caching gambar.
Pilihan pribadi saya :
Markdown dan Markdown GitHub secara umum membuat beberapa pilihan yang tidak populer, dan GH-MD-to-HTML, meniru, juga membuat banyak dari ini. Jika tujuan Anda tidak sedekat mungkin dengan markdown (rasa gitub), dan Anda ingin memanfaatkan kekuatan penuh yang ditawarkan GH-MD-to-HTML sepenuhnya, saya merekomendasikan daftar pengaturan dan opsi berikut (sangat berpendapat). Perhatikan bahwa beberapa di antaranya tidak aman saat mengonversi konten yang dibuat pengguna.
--math true : Ini sudah diaktifkan secara default, jadi tidak benar-benar rekomendasi, tetapi Anda kemungkinan besar ingin memiliki dukungan matematika lateks di file Anda.--core-converter OFFLINE+ : Ini mengonversi file-file markdown secara offline alih-alih menggunakan API REST GitHub, dan memungkinkan penggunaan hal-hal yang tidak aman seperti kode inline dan setiap HTML yang dapat Anda inginkan dalam file penurunan harga Anda.--compress-images : Ada banyak cara untuk memperbaiki opsi ini, tetapi memungkinkan untuk beberapa optimasi hebat pada gambar yang di-cache, termasuk penggunaan HTML srcset -Attribute, yang saat ini tidak ada konverter markdown lain yang mendukung AFAIK.--box-width 25cm : Anda kemungkinan besar ingin membatasi lebar kotak di mana konten situs web yang dihasilkan ditampilkan karena alasan keterbacaan, kecuali jika Anda berencana untuk menanamkan HTML yang dihasilkan ke dalam file HTML yang lebih besar.--toc true : Ini memungkinkan Anda untuk menggunakan [[_TOC_]] sebagai pintasan untuk daftar konten dalam file yang dihasilkan.--dont-make-images-links true : Secara default, GitHub membungkus setiap gambar ke tautan ke sumber gambar, kecuali jika gambar sudah dibungkus ke tautan yang berbeda. Opsi ini menonaktifkan perilaku ini untuk kontrol lebih lanjut atas tautan gambar Anda.--emoji-support 2 : GH-MD-to-HTML mendukung menggunakan shortcodes emoji, seperti :joy: , yang kemudian diganti dengan emoji dalam file html yang dihasilkan. --emoji-support 2 mengambil satu level ini lebih lanjut ini dengan memungkinkan Anda untuk menggunakan emoji kustom Anda sendiri, jadi :path/to/funny_image.png: akan menambahkan funny_image.png sebagai emoji berukuran emoji ke dalam teks.--soft-wrap-in-code-boxes true : Secara default, GitHub menampilkan kotak kode multilinnya dengan scrollbar horizontal jika mereka berisiko meluap. Gunakan opsi ini untuk memiliki (IMHO lebih masuk akal) Soft-Wrap dalam kotak kode sebagai gantinya. Harap dicatat bahwa opsi tersebut terdaftar dipesan berdasarkan relevansi, dan semuanya memiliki default yang masuk akal, jadi jangan merasa kewalahan dengan berapa banyak yang ada; Anda bisa membacanya sampai Anda menemukan apa yang Anda cari, dan abaikan dengan aman.
Sebagian besar opsi dimaksudkan untuk menyesuaikan perilaku default, jadi tidak ada yang wajib untuk sebagian besar kasus penggunaan.
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.
Seperti disebutkan di atas, gambar apa pun yang dirujuk dalam file Markdown disimpan secara lokal dan dirujuk menggunakan hyperlink root-relative dalam HTML yang dihasilkan. Bagaimana konverter menebak lokasi gambar ditunjukkan pada tabel berikut, dengan jenis imagelink dicatat di bagian atas dan jenis markdown input yang dicatat di sebelah kiri:
https:// atau http:// | abs. filepath | rel. filepath | Dimulai dengan / (misalnya /imagedir/image.png ) | tidak memulai dengan / (misalnya imagedir/image.png ) | |
|---|---|---|---|---|---|
-t file | dari alamat | abs. filepath | rel. filepath (dari mana .md -file terletak) | - | - |
-t string | dari alamat | abs.filepath, tetapi membutuhkan konfirmasi untuk alasan keamanan | rel. filepath (ke mana alat dipanggil), tetapi membutuhkan konfirmasi untuk alasan keamanan | - | - |
username/repo/dir/file.md -t repo | dari alamat | - | - | username/repo/imagedir/image.png | username/repo/dir/imagedir/image.png |
https://foo.com/bar/baz.md -t web | dari alamat | - | - | https://foo.com/image.png | https://foo.com/bar/image.png |
Seperti halnya semua proyek saya, umpan balik (bahkan jika itu adalah sesuatu yang kecil seperti memberi tahu saya kasus penggunaan Anda untuk proyek saya, atau mengatakan kepada saya bahwa Anda tidak menyukai struktur ReadMe, atau mengatakan kepada saya bahwa Anda secara khusus menyukai satu fitur tertentu) sangat dihargai, dan membantu saya membuat proyek ini lebih baik, bahkan jika itu sesuatu yang sangat kecil! Anda hanya dapat membatalkan masalah dengan umpan balik Anda, pendek dan tidak formal, atau bahkan mengirimi saya email jika Anda tidak ingin mengangkat masalah karena suatu alasan. Saya tidak berencana untuk menambahkan fitur di masa depan saat ini, tetapi saya selalu terbuka untuk memperbaiki dan mengutak -atik fitur yang ada, dokumentasi dan lain -lain, dan saya jelas ingin mendengar saran fitur Anda bahkan jika saya tidak berencana untuk menambahkannya dalam waktu dekat.
Saya umumnya sangat responsif dalam hal masalah GitHub, dan saya menganggapnya sangat serius dan mencoba menyelesaikannya secepatnya. Jika Anda mengalami bug, perilaku aneh, kesalahan instalasi dan sejenisnya saat menggunakan alat saya, jangan ragu untuk memberi tahu saya dalam masalah, jadi saya dapat memperbaiki masalahnya!
Jika Anda menemukan alat ini berguna, silakan pertimbangkan membintangi GitHub untuk menunjukkan penghargaan Anda! Saya juga akan menghargai jika Anda memberi tahu saya tentang masalah yang Anda temui bahkan jika Anda berhasil memperbaikinya dalam salinan kode Anda sendiri, jadi saya dapat memperbaikinya dalam repo ini juga.
gh-md-to-html untuk konversi MD-ke-PDF (di bawah GIST tentang konversi MD-ke-PDF): Tautangh-md-to-html dalam dokumentasi proyek lain: tautanIkon dibuat oleh
.md-file.icon: freepik dari flaticon.com
.md-file.icon: freepik dari flaticon.com
Arrow-Icon: Font Awesome oleh Dave Gandy, dilisensikan di bawah Creative Commons Attribution-Share Sama 3.0 Tidak Dipilih
Github-Icon: Ikon GitHub di Iconscout
Penafian : Modul ini tidak ditulis oleh GitHub, juga tidak didukung oleh GitHub, didukung oleh GitHub, ditenagai oleh GitHub atau berafiliasi dengan GitHub. Ini hanya menggunakan API publik yang disediakan oleh GitHub serta file .css yang dilisensikan oleh GitHub di bawah lisensi MIT.
