github flavored markdown to html
1.0.0
Un module python convivial et un frontage de ligne de commande pour convertir Markdown en HTML. Il utilise GitHubs en ligne Markdown-to-HTML-API par défaut (qui nécessite une connexion Internet), mais est livré avec une option de conversion hors ligne (qui imite étroitement le comportement de GitHubs), et tout autre outil de ligne de python ou de commande peut également être branché. Tout ce que vous l'utilisez est automatiquement étendu avec une tonne de fonctionnalités, comme plus d'options en et de sortie, CSS à saveur de github, prise en charge de la formule, mise en cache et optimisation avancées, support de fichiers et d'image prêt pour l'hôte, conversion PDF, prise en charge des short-codes emoji, support TOC et plus encore.
Bien que son objectif principal soit la création de pages statiques à partir de fichiers Markdown, par exemple en conjonction avec un générateur de sites Web statique ou des actions GitHub Si vous hébergez sur GitHub, il peut être très bien utilisé à d'autres fins.
Voici une liste (pas nécessairement étendue) de ses avantages et fonctionnalités:
$ -formula- $ pour les utiliser), ce que GitHub ne le fait généralement pas. GH-MD-to-HTML utilise latex et DVISVGM s'ils sont tous deux installés (Avantage: rapide, ne nécessite pas d'Internet), et sinon le codetor de codecogs (Avantage: ne vous oblige pas à installer 3 Go de bibliothèques de latex) pour y parvenir.[[_TOC_]] , {:toc} et [toc] au début d'une ligne autrement vide pour créer un tableau de contenu pour le document, comme le Markdown à saveur de Gitlab, entre autres.Dans le cas où vous cherchez une alternative à Pandoc pour convertir la marque en PDF, voici une liste de raisons pour lesquelles vous pourriez vouloir utiliser GH-MD-To-HTML au lieu de Pandoc pour le travail:
Alors que l'utilisation de Pandoc pour convertir de Markdown en PDF donne généralement de plus beaux résultats (Pandoc utilise le latex, après tout), GH-MD-HTML a son propre ensemble d'avantages lorsqu'il s'agit de convertir rapidement des fichiers complexes pour une affectation de devoirs ou d'autres fins où la fiabilité pèche plus que la beauté:
$ et les caractères avec lesquels la formule peut commencer. Ces règles ne s'appliquent pas dans certains éditeurs de Markdown courants comme MarkText, ce qui conduit à beaucoup de frustration lorsque les formules qui fonctionnaient dans l'éditeur ne fonctionnent plus lors de la conversion avec Pandoc (la fonction d'exportation à pdf de MarkText échoue parfois sur des fichiers lourds de formule sans message d'erreur, ce qui le rend encore moins fiable). Le pire est que, chaque fois que Pandoc échoue à convertir .md en .pdf à cause de cela, il montre le numéro de ligne de l'erreur basée sur le fichier .tex intermédiaire au lieu du fichier .md d'entrée, ce qui rend difficile la recherche de la racine du problème. Comme vous l'avez peut-être deviné, GH-MD-To-HTML ne pouvait pas se soucier de la quantité d'espace avec vous commencer vos formules, laissant cette décision à vous.Pour résumer, la conversion MD-TO-PDF de Pandoc agit assez inhabituel en ce qui concerne les images, les listes imbriquées, les entrées de point de puces multilignes ou les formules, et GH-MD-to-HTML ne le fait pas.
Utilisez pip3 install gh-md-to-html pour installer directement à partir de l'index Python Package, ou python3 -m pip install gh-md-to-html si vous êtes sous Windows.
Les deux peuvent nécessiter sudo sur Linux, et vous pouvez éventuellement faire
python3 -m pip install gh-md-to-html[pdf_export]
et installer wkhtmltopdf (V0.12.6 ou plus) pour obtenir la fonction de conversion PDF en option et convertir les fichiers de démarrage en PDF, et / ou
python3 -m pip install gh-md-to-html[offline_conversion]
Pour obtenir la fonction de conversion hors ligne facultative opérationnelle.
Si vous êtes sous Windows , vous devrez peut-être ajouter wkhtmltopdf à votre chemin dans votre répertoire de travail actuel afin d'obtenir une conversion PDF en fonction, par exemple avec PATH=%PATH%;c:/program files/wkhtmltopdf/bin ou quelque chose de similaire, en fonction de votre emplacement d'installation.
Si vous souhaitez accéder à l'interface avec votre ligne de commande, vous pouvez simplement fournir gh-md-to-html avec les arguments documentés dans le texte d'aide (accessible avec gh-md-to-html -h et illustré ci-dessous). Sur Windows, vous devez fournir python3 -m gh_md_to_html avec les arguments correspondants.
Si vous souhaitez accéder à l'interface via Python, vous pouvez utiliser
import gh_md_to_html puis utilisez gh_md_to_html.main() avec les mêmes arguments (et valeurs par défaut) que vous fournissez à l'interface de ligne de commande.
Si vous voulez seulement imiter le rendement des résultats de conversion par l'API REST de GitHub, mais ne voulez pas la mise en cache d'image, le support de formule et le style CSS fantaisie, utilisez
html_as_a_string = gh_md_to_html.core_converter.markdown(your_markdown_as_a_string)
Dans Python.
Utilisation : gh-md-to-html <input_name> <optional_arguments>
Comportement par défaut :
Par défaut, GH-MD-To-HTML prend un nom de fichier Markdown comme argument et enregistre le HTML généré dans un fichier du même nom, avec .html au lieu de .md .
Quelques bizarreries:
github-markdown-css/github-css.css (Ajouter -c pour le faire en ligne à la place)../images (ajoutez -i pour désactiver cela).-w si vous souhaitez le visualiser directement dans un navigateur à la place).id S et File Internet sont préfacés par user-content- , vous pouvez donc intégrer le HTML généré dans un site Web plus grand sans risquer des affrontements d'identification. Quelques cas d'utilisation courants :
Grâce à des problèmes passés, j'ai réalisé qu'il y avait des cas d'utilisation très courants que la plupart des gens semblent avoir pour ce module. Voici les plus courants et les options et arguments à utiliser pour eux:
-i -w --math false --box-width 25cm , bien que Grip puisse être plus efficace à cet effet.--toc pour prendre en charge la syntaxe TOC de GitLab.--math true --emoji-support 0 --dont-make-images-links true .-i -c pour tout avoir dans un fichier. Conversion de fichiers de démarrage à partir du Web avec --origin-type :
Vous voudrez peut-être non seulement convertir un fichier de marque local, mais également un fichier d'un référentiel GitHub, un référentiel hébergé par le Web ou le contenu d'une chaîne. Le simple fait de les télécharger ou de les stocker dans un fichier ne suffit souvent pas, car leur emplacement sur le Web influence également la façon dont les liens vers les images qu'ils font référence doivent être résolus. Heureusement, GH-MD-To-HTML vous a le dos!
Il existe un certain nombre d'arguments différents que vous pouvez utiliser pour décrire quel type de fichier l'entrée que vous avez donnée références:
--origin-type file : la valeur par défaut; prend un chemin de fichier (relatif ou absolu)--origin-type repo : prend une PTH dans un fichier de marque dans un référentiel GitHub, dans le format <user_name>/<repo_name>/<branch-name>/<path_to_markdown>.md .md.--origin-type web : prend l'URL d'un fichier de marque hébergé par le Web.--origin-type string : prend une chaîne contenant Markdown. Certaines de ces options que vous utilisez influencent la façon dont les liens d'image dans le fichier Markdown sont résolus; Une section ultérieure de cette lecture décrit cela en détail. Affliger ce qui va où :
GH-MD-to-HTML est écrit dans le but de générer un site Web statique prêt pour l'hôte pour vous, avec votre répertoire de travail actuel comme racine. En plus d'utiliser -w pour désactiver ceci et vous permettre de visualiser le fichier généré directement dans un navigateur, il existe un certain nombre d'options qui vous permettent d'affiner ce qui se passe, et le plus populaire, modifiez la racine du site Web. Il n'est pas nécessaire de le faire à moins que vous ne le vouliez pour une raison quelconque, alors ne vous embêtez pas à lire ceci si vous n'en avez pas besoin!
--website-root (ou -w ): laisser cette option vide, comme discuté ci-dessus, vous permet de prévisualiser le fichier HTML généré directement dans un navigateur (sur la plupart des systèmes en le double-cliquant) au cas où vous ne souhaitez pas héberger le fichier HTML généré, mais vous pouvez également fournir un répertoire que vous souhaitez utiliser comme racine du site Web. Il est par défaut votre répertoire de travail actuel.--destination (ou -d ): le chemin, relatif à --website-root , dans lequel le fichier HTML généré est stocké. Par défaut, la racine du site Web est utilisée pour cela.--image-paths (ou -i ): Vous pouvez laisser ce vide pour désactiver la mise en cache d'images, comme décrit ci-dessus (bien que cela ne fonctionnera pas au cas où vous auriez modifié --origin-type ), ou fournir un chemin par rapport à la racine de site Web pour modifier où les images sont stockées. Il est par défaut images .image-paths -directory n'est pas automatiquement vidé entre plusieurs exécutions de gh-md-to-html pour cette raison, afin de garantir que cette optimisation peut être utilisée lors de la conversion de plusieurs fichiers en vrac.--css-paths (ou -c ): Vous pouvez laisser ce vide pour désactiver le stockage du CSS dans un fichier CSS externe (par exemple utile si vous souhaitez convertir un seul fichier), comme décrit ci-dessus, ou fournir un chemin par rapport au site Web pour modifier où le fichier CSS (appelé github-css.css ) sera stocké. La valeur par défaut est github-markdown-css .--output-name (ou -n ): le nom de fichier sous lequel stocker le fichier HTML généré dans le directeur de destination. Vous pouvez utiliser <name> n'importe où dans cette chaîne, et il sera automatiquement remplacé par le nom du fichier Markdown, donc, par exemple, gh-md-to-html inp.md -n "<name>-conv.html" stockera le résultat dans ino-conv.html (cela ne fonctionne pas avec --origin-type string Conv.-n print afin d'écrire la sortie sur STDOUT (l'imprimez-le sur la console) au lieu de l'enregistrer n'importe où. La valeur par défaut est <name>.html , donc elle s'adapte à votre nom de fichier d'entrée.--output-pdf (ou -p ): le fichier dans lequel stocker le PDF généré. Vous pouvez également utiliser le <name> -Syntax ici. Si le -p -ption n'est pas utilisé, aucun PDF ne sera généré (et vous devez avoir suivi les instructions d'installation PDFKIT & WKHTMLTOPDF ci-dessus pour que cette option fonctionne), mais vous pouvez utiliser -p sans aucun argument pour qu'il utilise <name>.pdf comme nom de fichier sensible à défaut. Exportation sous forme de PDF :
Comme mentionné ci-dessus, vous pouvez exporter le fichier HTML généré en tant que PDF à l'aide de la --output-pdf option -option. Cela vous oblige à installer wkhtmltopdf (la version par correspondance QT), pour l'ajouter au chemin (si vous êtes sous Windows), et à installer pdfkit (par exemple via pip3 install gh-md-to-html[offline_conversion] ), mais toutes ces exigences sont déjà décrites ci-dessus dans la section d'installation.
Cependant, il y a des choses à noter ici. Tout d'abord, n'utilisez pas cette option si vous avez des informations précieuses dans un fichier appelé {yourpdfexportdestination}.html , où {yourpdfexportdestination} est ce que vous avez fourni à -p , car ce fichier sera temporairement remplacé dans le processus; De plus, n'utilisez pas du tout -p si vous fournissez une entrée non fiable à l'OPTION -x .
Il existe également certaines options spécifiquement adaptées à une utilisation avec -p ; Ce sont actuellement:
--style-pdf (ou -s ): définissez-le sur false pour désactiver le style du fichier PDF généré avec CSS de GitHub. Vous voudrez peut-être le faire parce que la bordure que le CSS de GitHub entraîne autour de la page peut sembler contre-intuitive dans les PDF, bien que cela puisse également influencer négativement l'apparition d'autres parties, alors utilisez-le avec un grain de sel. Modification du convertisseur de marque de base à utiliser :
GH-MD-To-HTML ne fait pas autant de choses à l'emprise en ce qui concerne l'analyse de la marque et de la convertir en PDF; Au lieu de cela, il s'enroule autour d'un soi-disant "convertisseur de base" qui effectue la conversion de base en fonction de la spécification Markdown, et construit ses propres options, fonctionnalités, personnalisations et style en plus de cela. Par défaut, l'API GitHub Markdown REST est utilisé pour cela, car il se rapproche le plus de ce que Github fait avec ses Readmes, mais vous pouvez également donner à GH-MD-à-HTML tout autre convertisseur de marque de base avec qui fonctionne.
GH-MD-to-HTML est également livré avec deux convertisseurs de noyau alternatifs à utiliser, qui imitent l'API REST de GitHub le plus près possible de GitHub tout en y ajoutant leur propre touche personnelle.
Option pour décider du convertisseur de base:
--core-converter (ou -o ): Vous pouvez utiliser cette option pour choisir parmi un certain nombre de convertisseurs de base prédéfinis (voir ci-dessous) au cas où vous souhaitez différer de celui par défaut.
Vous pouvez également fournir une commande bash (sur les systèmes UNIX / Linux) à ceci, ou une commande cmd.exe sur Windows, dans laquelle {md} est un espace réservé à l'endroit où la marque d'entrée est insurée par le shell. Par exemple,
gh-md-to-html inp.md -o "pandoc -f markdown -t html <<< {md}"
utilisera pandoc comme convertisseur de base.
Vous pouvez également le faire en utilisant plusieurs commandes, comme
gh-md-to-html -o "printf {md} >> temp.md; pandoc -f markdown -t html temp.md; rm temp.md" ,
Tant que le résultat est imprimé à Stdout.
Si vous utilisez l'interface python pour gh-md-to-html, vous pouvez également fournir n'importe quelle fonction qui convertit une chaîne de marque en une chaîne HTML à cet argument.
Convertisseurs de noyau prédéfinis que vous pouvez facilement fournir - --core-converter comme des chaînes:
OFFLINE : imite l'API de repos de Markdown de GitHub, mais hors ligne à l'aide de MuTtune. Cela nécessite que les dépendances facultatives pour "Offline_Conversion" soient satisfaites, en utilisant pip3 install gh-md-to-html[offline_conversion] ou pip3 install mistune>=2.0.0rc1 .OFFLINE+ : se comporte identique à la ligne hors ligne, mais il ne supprime pas le contenu potentiellement nocif comme JavaScript et CSS comme l'API GitHub REST. N'utilisez pas cette fonctionnalité à moins que vous ayez besoin d'un moyen de convertir des fichiers Markdown sécurisés manuellement sans que tous vos JS / style en ligne soient supprimés! Support pour les formulas en ligne :
gh-md-to-html prend en charge, par défaut, des formules en ligne (peu importe le convertisseur de base, voir ci-dessus, vous utilisez). Cela signifie que vous pouvez écrire une formule en latex entre deux panneaux de dollars sur la même ligne, et il sera remplacé par une image SVG affichant cette formule. Par exemple,
$e = m cdot c^2$
Ajoutera la célèbre formule d'Einstein en tant qu'image SVG, bien alignée avec le reste du texte qui l'entoure, dans votre document.
gh-md-to-html essaie toujours d'utiliser votre installation de latex locale pour effectuer cette conversion (avantage: rapide et ne nécessite pas Internet). Cependant, si le latex ou le DVISVGM ne sont pas installés ou ne les trouvent pas, il utilise un convertisseur en ligne (Avantage: ne vous oblige pas à installer 3 Go de bibliothèques de latex) pour y parvenir.
Vous pouvez utiliser les options suivantes pour modifier ce comportement:
--math (ou -m ): définissez ceci sur false pour désactiver le rendu de formule.--suppress-online-fallbacks : définissez ceci sur true pour désactiver le rendement en ligne pour le rendu des formules, augmenter une erreur si ses exigences ne sont pas installées localement ou ne peuvent pas être trouvées pour une raison quelconque. Cache d'image et compression d'image :
Comme expliqué en profondeur ci-dessus, GH-MD-à-HTML enregistre les images afin qu'elles puissent toutes être chargées du même dossier. Cela vient avec les avantages de
En plus de ces avantages, GH-MD-à-HTML vous permet également de définir un niveau de compression d'images à utiliser pour ces images. Si vous décidez de le faire, chaque image sera convertie en JPEG (en utilisant une couleur d'arrière-plan et des paramètres de qualité de votre goût), et que les images seront réduites si le HTML généré indique qu'ils ne seront pas nécessaires à leur taille réelle de toute façon (vous pouvez utiliser cette width ou une valeur height <img> .
GH-MD-to-HTML est également le seul convertisseur de marques capable d'utiliser le HTML srcset -Attribute, ce qui permet au document généré de référencer plusieurs versions à l'échelle différemment de la même image, dont le navigateur chargera ensuite le plus petit plus grand sur des tailles d'écran plus petites, conduisant à de grandes réductions de chargement sur le mobile. L'activation de cette fonctionnalité peut conduire à du chargement de réductions de temps sans sacrifier une qualité d'image visible, ce qui fait de GH-MD-To-HTML le meilleur choix si vous souhaitez générer des sites Web à chargement rapide à partir de vos fichiers Markdown lourds de l'image.
L'option à utiliser pour tout cela est
--compress-images .
Et il accepte un élément de données JSON avec les attributs suivants:
bg-color : La couleur à utiliser comme couleur d'arrière-plan lors de la conversion de RGBA-images en JPEG (un format RGB). Par défaut " white " et accepte presque toutes les valeurs de couleur HTML5 (" #FFFFFF ", " #ffffff ", " white " et " rgb(255, 255, 255) " aurait toutes été des valeurs valides).progressive : Enregistrez les images sous forme de jpeg progressive. La valeur par défaut est fausse.srcset : Enregistrez les versions à échelle à l'échelle différemment de l'image et fournissez-les à l'image dans son attribut SRCSET. Par défaut est faux. Prend un tableau de différentes largeurs ou True , qui sert de raccourci pour " [500, 800, 1200, 1500, 1800, 2000] ".quality : une valeur de 0 à 100 décrivant à quelle qualité les images doivent être enregistrées. Par défaut à 90. Si une taille spécifique est spécifiée pour une image spécifique dans le HTML, l'image est toujours convertie à la bonne taille avant de réduire la qualité.Si cet argument est laissé vide, aucune compression n'est utilisée du tout. Si cet argument est défini sur true, toutes les valeurs par défaut sont utilisées. S'il est défini sur les données JSON et que certaines valeurs sont omises, les paramètres par défaut sont utilisés pour ceux-ci.
Vous pouvez également passer un dict au lieu d'une chaîne contenant des données JSON si vous utilisez cette option dans le frontend Python.
La compression de l'image ne fonctionnera pas, pour des raisons évidentes, si vous utilisez -i pour désactiver la mise en cache d'image.
Mes choix personnels :
La marque et la marque à saveur de GitHub en général font des choix impopulaires, et GH-MD-to-HTML, l'imiter, en fait également beaucoup. Si votre objectif n'est pas le plus proche que possible de la marque (à saveur de github), et que vous souhaitez utiliser la pleine puissance que GH-MD-HTML offre au maximum, je recommande la liste suivante (très avisée) des paramètres et des options. Notez que certains d'entre eux ne sont cependant pas sûrs lors de la conversion du contenu généré par l'utilisateur.
--math true : Ceci est déjà activé par défaut, donc pas vraiment une recommandation, mais vous voudrez probablement avoir une prise en charge mathématique de latex dans votre fichier.--core-converter OFFLINE+ : Cela convertit les fichiers Markdown hors ligne au lieu d'utiliser l'API REST de GitHub, et permet d'utiliser des choses dangereuses comme le code en ligne et chaque HTML que vous pourriez souhaiter dans votre fichier Markdown.--compress-images : Il existe de nombreuses façons de Finetune ces options, mais il permet de superbes optimisations sur les images mises en cache, y compris l'utilisation du HTML srcset -Attribute -attribut, qu'aucun autre convertisseur Markdown ne prend actuellement en charge AFAIK.--box-width 25cm : Vous voudrez très probablement limiter la largeur de la case dans laquelle le contenu du site Web généré est affiché pour des raisons de lisibilité, à moins que vous ne prévoyiez d'intégrer le HTML généré dans un fichier HTML plus grand.--toc true : Cela vous permet d'utiliser [[_TOC_]] comme raccourci pour une table des matières dans le fichier généré.--dont-make-images-links true : Par défaut, GitHub enveloppe chaque image en un lien vers la source d'image, sauf si l'image est déjà enveloppée dans un lien différent. Cette option désactive ce comportement pour plus de contrôle sur les liens de votre image.--emoji-support 2 : GH-MD-to-HTML Prise en charge en utilisant des shortcodes emoji, comme :joy: qui sont ensuite remplacés par des emojis dans le fichier HTML généré. --emoji-support 2 va plus loin ce niveau en vous permettant d'utiliser vos propres emojis personnalisés, donc :path/to/funny_image.png: ajoutera funny_image.png en tant qu'emoji de la taille des emoji dans le texte.--soft-wrap-in-code-boxes true : Par défaut, GitHub affiche ses boîtes de code multiline avec une barre de défilement horizontale si elles sont à risque de débordement. Utilisez cette option pour avoir (à mon humble avis plus raisonnable) des boîtes de code à la place. Veuillez noter que les options sont répertoriées commandées par pertinence, et toutes ont des valeurs par défaut raisonnables, alors ne vous sentez pas dépassé par le nombre il y en a; Vous pouvez simplement les lire jusqu'à ce que vous trouviez ce que vous recherchez et ignorez en toute sécurité le reste.
La plupart des options sont destinées à personnaliser le comportement par défaut, donc aucun d'entre eux n'est obligatoire pour la plupart des cas d'utilisation.
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.
Comme mentionné ci-dessus, toute image référencée dans le fichier Markdown est stockée localement et référencée à l'aide d'un lien hypertexte lié à la racine dans le HTML généré. Comment le convertisseur devine l'emplacement de l'image est affiché dans le tableau suivant, avec le type d'imageLink noté en haut et le type de démarque d'entrée noté à gauche:
https:// ou http:// | Abs. file d'attente | rel. file d'attente | en commençant par / (par exemple /imagedir/image.png ) | ne pas commencer par / (par exemple imagedir/image.png ) | |
|---|---|---|---|---|---|
-t file | de l'adresse | Abs. file d'attente | rel. filepath (d'où se trouve le fichier .md ) | - | - |
-t string | de l'adresse | ABS.FILEPATH, mais a besoin de confirmation pour des raisons de sécurité | rel. filepath (à l'origine de l'outil appelé), mais a besoin d'une confirmation pour des raisons de sécurité | - | - |
username/repo/dir/file.md -t repo | de l'adresse | - | - | username/repo/imagedir/image.png | username/repo/dir/imagedir/image.png |
https://foo.com/bar/baz.md -t web | de l'adresse | - | - | https://foo.com/image.png | https://foo.com/bar/image.png |
Comme pour tous mes projets, les commentaires (même si c'est juste quelque chose de petit comme me dire votre cas d'utilisation pour mon projet, ou me dire que vous n'aimiez pas la structure de ReadMe, ou me dire que vous avez spécifiquement aimé une fonctionnalité spécifique) est très apprécié et m'aide à améliorer ce projet, même si c'est quelque chose de très minuscule! Vous pouvez simplement supprimer un problème avec vos commentaires, courts et non formels, ou même m'envoyer un e-mail si vous ne voulez pas soulever un problème pour une raison quelconque. Je n'ai pas l'intention d'ajouter des fonctionnalités à l'avenir pour le moment, mais je suis toujours ouvert à la réparation et à la peaufinage des fonctionnalités existantes, la documentation et cetera, et j'aimerais évidemment entendre vos suggestions de fonctionnalités même si je ne prévois pas de les ajouter dans un avenir proche.
Je suis généralement très réactif en ce qui concerne les problèmes de github, et je les prends très au sérieux et j'essaie de les résoudre dès que possible. Si vous rencontrez des bogues, des comportements étranges, des erreurs d'installation et autres lors de l'utilisation de mon outil, n'hésitez pas à me le dire dans un problème, afin que je puisse résoudre le problème!
Si vous avez trouvé cet outil utile, pensez à le mettre en vedette sur GitHub pour me montrer votre appréciation! J'apprécierais également si vous m'avez parlé de problèmes que vous avez rencontrés même si vous avez réussi à les réparer dans votre propre copie du code, afin que je puisse les réparer dans ce référentiel également.
gh-md-to-html pour la conversion MD-TO-PDF (sous une conversion GIST sur MD-PDF): liengh-md-to-html dans la documentation d'un autre projet: LienLes icônes ont été faites par
.md-file.icon: freepik de flaticon.com
.md-file.icon: freepik de flaticon.com
Arrow-Icon: Font Awesome par Dave Gandy, sous licence sous Creative Commons Attribution-Share 3.0 Unportted
Github-icon: icône github sur iConscout
Avertissement : ce module n'est ni écrit par GitHub, ni approuvé avec Github, pris en charge par Github, alimenté par GitHub ou affilié à GitHub. Il utilise uniquement une API publique fournie par GitHub ainsi qu'un fichier .css sous licence GitHub sous la licence MIT.
