github flavored markdown to html
1.0.0
Ein benutzerfreundlicher Python-Modul und eine Frontend für Befehlszeilen, um Markdown in HTML umzuwandeln. Es verwendet standardmäßig GitHubs Online-Markdown-to-HTML-API (die eine Internetverbindung erfordert), verfügt jedoch über eine Option für die Offline-Konvertierung (die das Verhalten von Githubs genau imitiert), und auch jedes andere Python- oder Befehlslinien-Tool kann an ihn angeschlossen werden. Was auch immer Sie verwenden, wird automatisch mit einer Menge Funktionalität erweitert, wie z.
Sein Hauptzweck ist die Erstellung von statischen Seiten aus Markdown-Dateien, beispielsweise in Verbindung mit einem statischen Website-Builder oder GitHub-Aktionen, wenn Sie auf GitHub hosten, aber für jeden anderen Zweck sehr gut verwendet werden.
Hier finden Sie eine (nicht unbedingt umfangreiche) Liste der Vorteile und Funktionen:
$ -formul- $ , um sie zu verwenden), was GitHub normalerweise nicht tut. GH-MD-to-HTML verwendet Latex und DVISVGM, wenn beide installiert sind (Vorteil: Fast, benötigt kein Internet), und ansonsten der Codecogs-Eqneditor (Vorteil: Sie müssen nicht 3 GB Latex-Bibliotheken installieren), um dies zu erreichen.[[_TOC_]] , {:toc} und [toc] zu Beginn einer ansonsten leeren Zeile, um eine Inhaltstabelle für das Dokument zu erstellen, wie es unter anderem der Markdown von GitLab-Geschmack betrifft.Falls Sie nach einer Alternative zu Pandoc für die Konvertierung von Markdown in PDF suchen, finden Sie hier eine Liste von Gründen, warum Sie für den Job GH-MD-to-HTML anstelle von PANDOC verwenden möchten:
Während die Verwendung von Pandoc, um von Markdown in PDF zu konvertieren, normalerweise schönere Ergebnisse erzielt (Pandoc verwendet schließlich Latex), hat GH-MD-to-HTML seine eigenen Vorteile, wenn es darum geht, komplexe Dateien für eine Hausaufgabe oder andere Zwecke, in denen die Zuverlässigkeit mehr als Schönheit gewichtet wird, schnell umzuwandeln als Schönheit:
$ -Ssigns in Kurven fassen und welche Zeichen die Formel möglicherweise beginnen. Diese Regeln gelten jedoch nicht in einigen gängigen Markdown-Editoren wie Marktext, was zu viel Frustration führt, wenn Formeln, die im Editor funktionierten, bei der Konvertierung mit Pandoc nicht mehr funktionieren (Marktext's Export-to-PDF-Function schlägt jedoch manchmal noch weniger zuverlässig. Das schlimmste Teil ist, dass Pandoc, wenn es nicht die Zeilennummer des Fehlers auf .Tex-Datei anstelle des Eingangs .MD-File basiert, was es schwierig macht, die Wurzel des Problems zu finden. Wie Sie vielleicht vermutet haben, könnte GH-MD-to-HTML nicht weniger für die Menge an Whitespace, mit der Sie Ihre Formeln starten, interessiert und diese Entscheidung Ihnen überlassen.Zusammenfassend lässt sich sagen, dass Pandocs MD-to-PDF-Konvertierung bei Bildern, verschachtelten Listen, Multiline-Bullet-Punkteinträgen oder Formeln und GH-MD-to-HTML-Einträgen nicht wirkt.
Verwenden Sie pip3 install gh-md-to-html , um direkt aus dem Python-Paketindex oder python3 -m pip install gh-md-to-html wenn Sie unter Windows sind.
Beide benötigen möglicherweise sudo unter Linux, und Sie können optional tun
python3 -m pip install gh-md-to-html[pdf_export]
und installieren Sie WKHTMLTOPDF (v0.12.6 oder höher
python3 -m pip install gh-md-to-html[offline_conversion]
Um die optionale Offline-Konversionsfunktion zu erhalten.
Wenn Sie unter Windows sind , müssen Sie möglicherweise in Ihrem aktuellen Arbeitsverzeichnis wkhtmltopdf in Ihrem Pfad hinzufügen, um die PDF -Konvertierung zum Arbeiten zu erhalten, z. B. mit PATH=%PATH%;c:/program files/wkhtmltopdf/bin
Wenn Sie mit Ihrer Befehlszeile auf die Schnittstelle zugreifen möchten, können Sie nur gh-md-to-html mit den Argumenten angeben, die im Hilftext dokumentiert sind (zugänglich mit gh-md-to-html -h und unten gezeigt). Unter Windows müssen Sie python3 -m gh_md_to_html mit den entsprechenden Argumenten anbieten.
Wenn Sie über Python auf die Benutzeroberfläche zugreifen möchten, können Sie verwenden
import gh_md_to_html und dann verwenden Sie gh_md_to_html.main() mit denselben Argumenten (und Standardwerten), die Sie der Befehlszeilenschnittstelle angeben würden.
Wenn Sie die Konvertierungsergebnisse nur nach Githubs REST -API offline nachahmen möchten, aber kein Bild zwischen Bild, Formelunterstützung und ausgefallenem CSS -Styling verwenden möchten, verwenden Sie nicht
html_as_a_string = gh_md_to_html.core_converter.markdown(your_markdown_as_a_string)
in Python.
Verwendung : gh-md-to-html <input_name> <optional_arguments>
Standardverhalten :
Standardmäßig nimmt GH-MD-to-HTML einen Markdown-Dateinamen als Argument an und speichert die generierte HTML in einer gleichnamigen Datei mit .html anstelle von .md .
Einige Macken:
github-markdown-css/github-css.css gespeichert (fügen Sie stattdessen -c , um es inline zu machen)../images zwischengespeichert, gespeichert und verwiesen (um -i zu deaktivieren).-w hinzu, wenn Sie sie stattdessen direkt in einem Browser anzeigen möchten).id und Datei-internationalen Links werden von user-content- vorgefertigt, sodass Sie die generierte HTML in eine größere Website einbetten können, ohne ID-Konflikte zu riskieren. Einige gemeinsame Anwendungsfälle :
In früheren Themen wurde mir klar, dass es einige sehr häufige Anwendungsfälle gibt, die die meisten Menschen für dieses Modul zu haben scheinen. Hier sind die häufigsten und welche Optionen und Argumente für sie verwendet werden:
-i -w --math false --box-width 25cm , obwohl der Griff für diesen Zweck möglicherweise effizienter ist.--toc hinzu, um die TOC -Syntax von Gitlab zu unterstützen.--math true --emoji-support 0 --dont-make-images-links true .-i -c um alles in einer Datei zu haben. Konvertieren von Markdown-Dateien aus dem Web mit --origin-type :
Vielleicht möchten Sie nicht nur eine lokale Markdown-Datei konvertieren, sondern auch eine Datei aus einem Github-Repository, einer Web-veranstalteten oder dem Inhalt einer Zeichenfolge. Das einfache Herunterladen dieser oder das Speichern in einer Datei reicht oft nicht aus, da ihr Standort im Web auch beeinflusst, wie die Links zu Bildern, auf die sie referenzieren, behoben werden müssen. Zum Glück hat GH-MD-to-HTML Ihren Rücken!
Es gibt eine Reihe verschiedener Argumente, mit denen Sie beschreiben können, welche Art von Datei die Eingabe, die Sie angegeben haben, Referenzen angegeben haben:
--origin-type file : Die Standardeinstellung; Nimmt einen (relativen oder absoluten) Dateipfad--origin-type repo : Bringt eine PTH zu einer Markdown-Datei in einem GitHub-Repository im Format <user_name>/<repo_name>/<branch-name>/<path_to_markdown>.md <branchname>/<path_to_markdown> .md.--origin-type web : Nimmt die URL einer Web-Hosted-Markdown-Datei an.--origin-type string : Nimmt eine Zeichenfolge mit Markdown. Einige dieser Optionen, die Sie verwenden, beeinflussen, wie Bildlinks in der Markdown -Datei behoben werden. In einem späteren Abschnitt dieses Readme werden dies ausführlich beschrieben. Feinabstimmung, was wohin geht :
GH-MD-to-HTML wird mit dem Ziel geschrieben, eine statische Website für Sie mit Host-fertig zu generieren, wobei Ihr aktuelles Arbeitsverzeichnis als Stamm ist. Abgesehen von der Verwendung -w , um dies zu deaktivieren und die generierte Datei direkt in einem Browser anzusehen, gibt es eine Reihe von Optionen, mit denen Sie das, wohin, wohin und am häufigsten die Wurzel der Website ändern können, Feinabstimmung ermöglichen. Es ist nicht erforderlich, dies zu tun, es sei denn, Sie wollen aus irgendeinem Grund. Lesen Sie dies also nicht, wenn Sie nicht müssen!
--website-root (oder -w ): Wenn Sie diese Option wie oben erläutert leer lassen, können Sie die generierte HTML-Datei direkt in einem Browser (auf den meisten Systemen durch Doppelklicken) in Anspruch nehmen, falls Sie die generierte HTML-Datei nicht hosten möchten, aber Sie können auch jedes Verzeichnis angeben, das Sie als Wurzel der Website für diese Website für diese Website verwenden möchten. Es ist standardmäßig Ihr aktuelles Arbeitsverzeichnis.--destination (oder -d ): Der Pfad relativ zu --website-root , in dem die generierte HTML-Datei gespeichert ist. Standardmäßig wird das Website -Root dafür verwendet.--image-paths (oder -i ): Sie können dieses leere lassen, um das Bild zwischen Bild zu deaktivieren, wie oben beschrieben (obwohl dies nicht funktioniert, falls Sie geändert werden --origin-type ) oder einen Pfad relativ zu Website-Root zur Änderung der Bilomiespeicherung liefern. Es ist standardmäßig images .image-paths -Verzeichnis wird aus diesem Grund nicht zwischen mehreren Läufen von GH-MD-zu-HTML-Läufen entleert, um sicherzustellen, dass diese Optimierung bei der Konvertierung mehrerer Dateien in einer Menge verwendet werden kann.--css-paths (oder -c ): Sie können dies leer lassen, um das Speichern der CSS in einer github-css.css CSS-Datei zu deaktivieren (nützliche z. Der Standardwert ist github-markdown-css .--output-name (oder -n ): Der Dateiname, unter dem die generierte HTML-Datei im Ziel-Verzeichnis gespeichert werden soll. Sie können <name> überall in dieser Zeichenfolge verwenden, und es wird automatisch durch den Namen der Markdown-Datei ersetzt. Zum Beispiel wird gh-md-to-html inp.md -n "<name>-conv.html" das Ergebnis in ino-conv.html (dies funktioniert nicht mit --origin-type string , natürlich).-n print verwenden, um die Ausgabe einfach an stdout zu schreiben (drucken Sie sie auf der Konsole), anstatt sie überall zu speichern. Der Standardwert ist <name>.html , sodass er sich Ihrem Namens -Dateinamen anpasst.--output-pdf (oder -p ): Die Datei, in der die generierte PDF gespeichert werden soll. Auch hier können Sie die <name> -Syntax verwenden. Wenn die -p -option nicht verwendet wird, wird kein PDF -p (und Sie müssen den oben genannten Installationsanweisungen von PDFKit & <name>.pdf befolgt haben, damit diese Option funktioniert). Exportieren als PDF :
Wie oben erwähnt, können Sie die generierte HTML -Datei als PDF unter Verwendung der --output-pdf -option exportieren. Wenn Sie dies tun, müssen Sie wkhtmltopdf installieren (die qt-angepatched-Version), um ihn dem Pfad hinzuzufügen (falls Sie unter Windows sind) und die Installation pdfkit ( pip3 install gh-md-to-html[offline_conversion]
Es gibt jedoch einige Dinge, die es wert sind, hier zu bemerken. Verwenden Sie diese Option zunächst nicht, wenn Sie wertvolle Informationen in einer Datei namens {yourpdfexportdestination}.html haben, wobei {yourpdfexportdestination} das ist, was Sie an -p geliefert haben, da diese Datei in diesem Prozess vorübergehend überschrieben wird. Verwenden Sie außerdem überhaupt nicht -p , wenn Sie die -x -Option nicht vertrauenswürdig eingeben.
Es gibt auch einige Optionen, die speziell für die Verwendung mit -p zugeschnitten sind. Diese sind derzeit:
--style-pdf (oder -s ): Stellen Sie dies auf false , um das Design der generierten PDF-Datei mit Githubs CSS zu deaktivieren. Möglicherweise möchten Sie dies tun, weil der Grenze, den Githubs CSS um die Seite zieht, in PDFs kontraintuitiv aussehen kann, obwohl dies auch das Erscheinungsbild anderer Teile negativ beeinflussen kann. Verwenden Sie dies also mit einem Salzkorn. Ändern des zu verwendenden Kern -Markdown -Konverters :
GH-MD-to-HTML macht selbst nicht so viel schweres Heben, wenn es darum geht, Markdown zu analysieren und in PDF umzuwandeln. Stattdessen wickelt es sich um einen sogenannten "Kernkonverter", der die grundlegende Konvertierung gemäß der Markdown-Spezifikation durchführt, und erstellt darüber hinaus eigene Optionen, Funktionen, Anpassungen und Styling. Standardmäßig wird die GitHub-Markdown-REST-API dafür verwendet, da sie dem, was Github mit seinen Readmes macht, am nächsten kommt, aber Sie können auch GH-MD-to-HTML-Konverter für einen anderen grundlegenden Markdown-Konverter geben, mit dem Sie arbeiten können.
GH-MD-to-HTML wird außerdem mit zwei zu verwendenden alternativen Kernkonvertern ausgestattet, die die REST-API von Github so nah wie möglich imitieren und gleichzeitig ihre persönliche Note hinzufügen.
Option, um den Kernkonverter zu entscheiden:
--core-converter (oder -o ): Mit dieser Option können Sie aus einer Reihe vordefinierter Kernkonverter (siehe unten) ausgewählt werden, falls Sie sich von der Standardeinstellung unterscheiden möchten.
Sie können auch einen BASH-Befehl (auf UNIX/Linux-Systemen) oder einen CMD.exe-Befehl unter Windows angeben, in dem {md} als Platzhalter für den Shell-Escaped-Eingabemarkdown steht, der von GH-MD-to-HTML eingefügt wird. Zum Beispiel,
gh-md-to-html inp.md -o "pandoc -f markdown -t html <<< {md}"
Verwendet Pandoc als Kernwandler.
Sie können dies auch mit mehreren Befehlen tun, wie wie
gh-md-to-html -o "printf {md} >> temp.md; pandoc -f markdown -t html temp.md; rm temp.md" ,
Solange das Ergebnis auf stdout gedruckt wird.
Wenn Sie die Python-Schnittstelle zu GH-MD-to-HTML verwenden, können Sie auch jede Funktion angeben, die eine Markdown-Zeichenfolge in eine HTML-Zeichenfolge in dieses Argument umwandelt.
Vordefinierte Kernkonverter, die Sie problemlos für --core-converter als Zeichenfolgen liefern können:
OFFLINE : Nachahmt Githubs Markdown -REST -API imitiert, aber offline mit Mistune. Dies erfordert, dass die optionalen Abhängigkeiten für "offline_conversion" erfüllt werden müssen, indem pip3 install gh-md-to-html[offline_conversion] oder pip3 install mistune>=2.0.0rc1 installieren.OFFLINE+ : Verhalten Sie sich mit Offline identisch, entfernen jedoch nicht potenziell schädliche Inhalte wie JavaScript und CSS wie die Github Rest -API normalerweise. Verwenden Sie diese Funktion nicht, es sei denn, Sie benötigen eine Möglichkeit, sichere, manuell überprüfte Markdown-Dateien zu konvertieren, ohne dass alle Ihre Inline-JS/Styling entfernt werden! Unterstützung für Inline-Formulas :
gh-md-to-html unterstützt standardmäßig Inline-Formeln (unabhängig davon, welcher Kernkonverter, siehe oben, Sie verwenden). Dies bedeutet, dass Sie eine Latexformel zwischen zwei Dollar -Schildern in derselben Zeile schreiben können und sie durch ein SVG -Bild ersetzt wird, das diese Formel anzeigt. Zum Beispiel,
$e = m cdot c^2$
Wird Einsteins berühmte Formel als SVG-Bild in Ihr Dokument hinzufügen, das mit dem Rest des Textes gut ausgerichtet ist.
gh-md-to-html versucht immer, Ihre lokale Latex-Installation zu verwenden, um diesen Conversion durchzuführen (Vorteil: schnell und kein Internet erforderlich). Wenn Latex oder DVISVGM jedoch nicht installiert sind oder sie nicht finden können, verwendet er einen Online -Konverter (Vorteil: Sie müssen nicht 3 GB Latex -Bibliotheken installieren), um dies zu erreichen.
Sie können die folgenden Optionen verwenden, um dieses Verhalten zu ändern:
--math (oder -m ): Setzen Sie dies auf false , um die Formel -Rendering zu deaktivieren.--suppress-online-fallbacks : Setzen Sie dies auf true , um den Online-Fallback für das Formel-Rendering zu deaktivieren, und erhöhen Sie einen Fehler, wenn seine Anforderungen nicht lokal installiert sind oder aus irgendeinem Grund nicht gefunden werden können. Bilddachung und Bildkomprimierung :
Wie oben erläutert, speichert GH-MD-to-HTML Bilder, sodass sie alle aus demselben Ordner geladen werden können. Dies kommt mit den Vorteilen von
Zusätzlich zu diesen Vorteilen können Sie mit GH-MD-to-HTML auch eine für diese Bilder verwendete Bildkomprimierung festlegen. Wenn Sie sich dafür entscheiden, wird jedes Bild in JPEG konvertiert (unter Verwendung einer Hintergrundfarbe und Qualitätseinstellungen Ihres Geschmacks), und die Bilder werden heruntergezogen, wenn der generierte HTML feststellt, dass sie sowieso nicht in voller Größe benötigt werden (Sie können diesen EG -Wert verwenden, indem Sie <img> -Tags direkt in Ihrem Dokument verwenden und sie mit einem expliziten width oder height versorgen).
GH-MD-to-HTML ist auch der einzige Markdown-Konverter, der die HTML srcset -attribute verwenden kann, mit der das generierte Dokument auf verschiedene unterschiedlich skalierte Versionen desselben Bildes verweisen kann, von denen der Browser dann die kleinste Ladungsgrößen auf kleinere Bildschirmgrößen lädt, was auf eine große Lastreduktion von EG auf Mobilgeräte führt. Das Aktivieren dieser Funktion kann zu einer weiteren Ladezeitreduzierungen führen, ohne sichtbare Bildqualität zu beeinträchtigen, was GH-MD-HTML zur besten Wahl macht, wenn Sie schnellladende Websites aus Ihren bildlebigen Markdown-Dateien generieren möchten.
Die Option für all dies ist die Möglichkeit
--compress-images .
und es akzeptiert ein Stück JSON -Daten mit den folgenden Attributen:
bg-color : Die Farbe, die als Hintergrundfarbe bei der Konvertierung von RGBA-Images in JPEG (ein RGB-Format) verwendet wird. Standardmäßig " white " und akzeptiert fast jeden HTML5-Farbwert (" #FFFFFF ", " #ffffff ", " white " und " rgb(255, 255, 255) " wären alle gültigen Werte gewesen).progressive : Bilder als progressive JPEGs speichern. Standard ist falsch.srcset : Speichern Sie unterschiedlich skalierte Versionen des Bildes und geben Sie es dem Bild in seinem SRCSet -Attribut an. Standardmäßig falsch. Nimmt eine Reihe verschiedener Breiten oder True , die als Abkürzung für " [500, 800, 1200, 1500, 1800, 2000] dient.quality : Ein Wert von 0 bis 100 beschreibt, in welcher Qualität die Bilder gespeichert werden sollten. Standardeinstellungen zu 90. Wenn eine bestimmte Größe für ein bestimmtes Bild im HTML angegeben wird, wird das Bild immer auf die richtige Größe konvertiert, bevor die Qualität reduziert wird.Wenn dieses Argument leer bleibt, wird überhaupt keine Komprimierung verwendet. Wenn dieses Argument auf True eingestellt ist, werden alle Standardwerte verwendet. Wenn es auf JSON -Daten eingestellt ist und einige Werte weggelassen werden, werden die Standards für diese verwendet.
Sie können auch ein Diktat anstelle einer Zeichenfolge übergeben, die JSON -Daten enthält, wenn Sie diese Option in der Python -Frontend verwenden.
Die Bildkomprimierung funktioniert aus offensichtlichen Gründen nicht, wenn Sie -i verwenden, um das Bild zwischen Bild zu deaktivieren.
Meine persönlichen Entscheidungen :
Der Markdown und Markdown im Allgemeinen sind mit Github-Flora einige unpopuläre Entscheidungen, und GH-MD-to-HTML, das es imitiert, macht auch viele davon. Wenn Ihr Ziel nicht so nah wie möglich zu sein ist, um (Github-Flaired) zu markieren, und Sie die volle Leistung, die GH-MD-to-HTML in vollem Umfang bietet, in vollem Umfang anwenden möchten, empfehle ich die folgende (sehr Meinung) Liste von Einstellungen und Optionen. Beachten Sie jedoch, dass einige davon bei der Konvertierung benutzergenerierter Inhalte nicht sicher sind.
--math true : Dies ist standardmäßig bereits aktiviert, daher nicht wirklich eine Empfehlung, aber Sie möchten höchstwahrscheinlich Latex-Mathematikunterstützung in Ihrer Datei haben.--core-converter OFFLINE+ : Dies konvertiert die Markdown-Dateien offline, anstatt die REST-API von Github zu verwenden, und ermöglicht die Verwendung unsicherer Dinge wie Inline-Code und jeder HTML, die Sie in Ihrer Markdown-Datei wünschen.--compress-images : Es gibt viele Möglichkeiten, diese Optionen zu beenden, aber es ermöglicht einige großartige Optimierungen für die zwischengespeicherten Bilder, einschließlich der Verwendung des HTML srcset -attribute, den kein anderer Markdown-Konverter AFAIK unterstützt.--box-width 25cm : Sie möchten höchstwahrscheinlich die Breite des Box einschränken, in dem der Inhalt der generierten Website aus Lesbarkeitsgründen angezeigt wird, es sei denn, Sie planen, die generierte HTML in eine größere HTML-Datei einzubetten.--toc true : Dadurch können Sie [[_TOC_]] als Verknüpfung für ein Inhaltsverzeichnis in der generierten Datei verwenden.--dont-make-images-links true : Standardmäßig wickelt GitHub jedes Bild in einen Link zur Bildquelle um, es sei denn, das Bild ist bereits in einen anderen Link umwickelt. Diese Option deaktiviert dieses Verhalten, um mehr Kontrolle über die Links Ihres Bildes zu erhalten.--emoji-support 2 : GH-MD-to-HTML unterstützt die Verwendung von Emoji-Shortcodes wie :joy: die dann in der generierten HTML-Datei durch Emojis ersetzt werden. --emoji-support 2 führt diese eine Ebene weiter, indem Sie Ihre eigenen benutzerdefinierten Emojis verwenden, also :path/to/funny_image.png: Wird funny_image.png als Emoji-Größe-Emoji in den Text hinzufügen.--soft-wrap-in-code-boxes true : Standardmäßig zeigt GitHub seine Multiline-Code-Boxen mit einer horizontalen Bildlaufleiste an, wenn sie das Risiko eines Überflusses haben. Verwenden Sie diese Option, um stattdessen (IMHO vernünftiger) Soft-Wrap in Codeboxen zu haben. Bitte beachten Sie, dass die Optionen nach Relevanz aufgelistet sind und alle vernünftige Standardeinstellungen haben. Fühlen Sie sich also nicht von der Anzahl, wie viele es gibt. Sie können sie einfach durchlesen, bis Sie das finden, wonach Sie suchen, und den Rest sicher ignorieren.
Die meisten Optionen sollen das Standardverhalten anpassen, daher ist keiner von ihnen für die meisten Anwendungsfälle obligatorisch.
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.
Wie oben erwähnt, wird jedes Bild, auf das in der Markdown-Datei verwiesen wird, lokal gespeichert und unter Verwendung eines root-relativen Hyperlinks in der generierten HTML referenziert. Wie der Konverter die Position des Bildes erraten, wird in der folgenden Tabelle angezeigt, wobei der Typ des Imagelink oben angegeben ist und die Art des Eingangsmarkens links angegeben ist:
https:// oder http:// | ABS. Filepath | rel. Filepath | Beginnend mit / (z. B. /imagedir/image.png ) | nicht beginnen mit / (zB imagedir/image.png ) | |
|---|---|---|---|---|---|
-t file | Aus der Adresse | ABS. Filepath | rel. Filepath (von wo aus der .md -Datei liegt) | - - | - - |
-t string | Aus der Adresse | Abs.filepath, muss jedoch aus Sicherheitsgründen bestätigt werden | rel. Filepath (wo das Tool aufgerufen wird), muss jedoch aus Sicherheitsgründen bestätigt werden | - - | - - |
username/repo/dir/file.md -t repo | Aus der Adresse | - - | - - | username/repo/imagedir/image.png | username/repo/dir/imagedir/image.png |
https://foo.com/bar/baz.md -t web | Aus der Adresse | - - | - - | https://foo.com/image.png | https://foo.com/bar/image.png |
Wie bei allen meinen Projekten ist das Feedback (auch wenn es nur etwas Kleines ist, wie Sie Ihren Anwendungsfall für mein Projekt sagen oder mir sagen, dass Ihnen die Struktur des Readmes nicht gefallen hat, oder dass Sie mir ein bestimmtes Feature ausdrücklich gemocht haben) sehr geschätzt und hilft mir, dieses Projekt besser zu machen, selbst wenn es etwas sehr kleines ist! Sie können einfach ein Problem mit Ihrem Feedback, kurz und nicht formal, oder mir sogar eine E-Mail an mich senden, wenn Sie aus irgendeinem Grund kein Problem ansprechen möchten. Ich habe im Moment nicht vor, in Zukunft Funktionen hinzuzufügen, aber ich bin immer offen für die Behebung und Optimierung vorhandener Funktionen, Dokumentation und Cetera, und ich würde natürlich gerne Ihre Feature -Vorschläge hören, auch wenn ich nicht vorhabe, sie in naher Zukunft hinzuzufügen.
Ich bin im Allgemeinen sehr aufmerksam, wenn es um Github -Probleme geht, und ich nehme sie sehr ernst und versuche sie so schnell wie möglich zu lösen. Wenn Sie auf Fehler, seltsame Verhaltensweisen, Installationsfehler und dergleichen während der Verwendung meines Tools stoßen, zögern Sie nicht, mir in einem Problem zu sagen, damit ich das Problem beheben kann!
Wenn Sie dieses Tool nützlich fanden, sollten Sie es in GitHub in Betracht ziehen, um mir Ihre Wertschätzung zu zeigen! Ich würde mich auch freuen, wenn Sie mir von Problemen erzählen, die Sie begegnen, auch wenn Sie es geschafft haben, sie in Ihrer eigenen Kopie des Codes zu beheben, damit ich sie auch in diesem Repo beheben kann.
gh-md-to-html für die MD-to-PDF-Konvertierung verwenden (unter einem GIST über MD-to-PDF-Konvertierung): Linkgh-md-to-html in der Dokumentation eines anderen Projekts: LinkDie Ikonen wurden von gemacht von
.md-file.icon: freepik von flaticon.com
.md-file.icon: freepik von flaticon.com
Arrow-Icon: Schriftart großartig von Dave Gandy, lizenziert unter Creative Commons Attribution-Share gleichermaßen 3.0 Unported
Github-Icon: Github-Symbol auf iConscout
Haftungsausschluss : Dieses Modul wird weder von Github geschrieben, noch wird es mit Github unterstützt, von Github unterstützt, von Github angetrieben oder mit GitHub verbunden. Es verwendet nur eine von Github bereitgestellte öffentliche API sowie eine von Github unter der MIT-Lizenz lizenzierte CSS-Datei.
