github flavored markdown to html
1.0.0
Un frontend de la línea de comandos y una línea de comandos fácil de usar para convertir Markdown en HTML. Utiliza GitHubs en línea Markdown a HTML-API de forma predeterminada (que requiere conexión a Internet), pero viene con una opción para la conversión fuera de línea (que imita de cerca el comportamiento de GitHubs), y cualquier otra herramienta de línea de comandos o línea de comandos también se puede conectar a ella. Lo que sea que lo use se extiende automáticamente con una tonelada de funcionalidad, como opciones de más información y salida, CSS con sabor a GitHub, soporte de fórmula, almacenamiento en caché y optimización de imágenes avanzados, colocación de archivos e imágenes listos para host, conversión a PDF, soporte de código cortos de emoji, soporte de TOC y más.
Si bien su objetivo principal es la creación de páginas estáticas de los archivos de Markdown, por ejemplo, junto con un constructor de sitios web estático o acciones de GitHub si aloja en GitHub, puede ser muy bien utilizado para cualquier otro propósito.
Aquí hay una lista (no necesariamente extensa) de sus ventajas y características:
$ -Formula- $ para usarlas), lo que GitHub generalmente no. GH-MD-TO-HTML usa látex y dVISVGM si ambos están instalados (ventaja: rápido, no requiere Internet), y de lo contrario el CodeCogs Eqneditor (ventaja: no requiere que instale 3 GB de bibliotecas de látex) para lograr esto.[[_TOC_]] , {:toc} y [toc] al comienzo de una línea vacía para crear una tabla de contenido para el documento, como lo hace Markdown con sabor a GitLab, entre otros.En caso de que esté buscando una alternativa a PANDOC para convertir Markdown en PDF, aquí hay una lista de razones por las cuales podría desear usar GH-MD-TO HTML en lugar de Pandoc para el trabajo:
Mientras que el uso de PANDOC para convertir de Markdown a PDF generalmente produce resultados más hermosos (PANDOC usa látex, después de todo), GH-MD-TO-HTML tiene su propio conjunto de ventajas cuando se trata de convertir rápidamente archivos complejos para una tarea o otros fines donde la fiabilidad pesa más que la belleza::
$ y con qué caracteres puede comenzar la fórmula. Sin embargo, estas reglas no se aplican en algunos editores de Markdown comunes como MarkText, lo que lleva a mucha frustración cuando las fórmulas que funcionan en el editor ya no funcionan al convertir con PANDOC (sin embargo, la propia función de exportación a PDF de MarkText a veces falla en archivos pesados de fórmula sin un mensaje de error, lo que hace que sea aún menos confiable). La peor parte es que, cada vez que PANDOC falla convirtiendo .md a .pdf debido a esto, muestra el número de línea del error basado en el archivo .tex intermedio en lugar de la entrada .md-file, lo que dificulta encontrar la raíz del problema. Como habrá adivinado, GH-MD-TO HTML no podría importarle menos la cantidad de espacio en blanco con los que comienza sus fórmulas, dejando esta decisión para usted.Para resumir, la conversión MD-to PDF de PANDOC actúa bastante inusual cuando se trata de imágenes, listas anidadas, entradas de bala multilínea o fórmulas, y GH-MD-TO HTML no lo hace.
Use pip3 install gh-md-to-html para instalar directamente desde el índice de paquetes de Python, o python3 -m pip install gh-md-to-html si está en Windows.
Ambos pueden requerir sudo en Linux, y opcionalmente puede hacerlo
python3 -m pip install gh-md-to-html[pdf_export]
e instale wkhtmltopdf (v0.12.6 o más) para obtener la función opcional de conversión PDF y convertir archivos de markdown en PDF, y/o
python3 -m pip install gh-md-to-html[offline_conversion]
Para obtener la función opcional de conversión fuera de línea en funcionamiento.
Si está en Windows , es posible que deba agregar wkhtmltopdf a su ruta en su directorio de trabajo actual para que la conversión de PDF funcione, por ejemplo, con PATH=%PATH%;c:/program files/wkhtmltopdf/bin o algo similar, dependiendo de su ubicación de instalación.
Si desea acceder a la interfaz con su línea de comando, puede proporcionar gh-md-to-html con los argumentos documentados en el texto de ayuda (accesible con gh-md-to-html -h y a continuación). En Windows, debe suministrar python3 -m gh_md_to_html con los argumentos correspondientes.
Si desea acceder a la interfaz a través de Python, puede usar
import gh_md_to_html y luego use gh_md_to_html.main() con los mismos argumentos (y valores predeterminados) que suministraría a la interfaz de línea de comandos.
Si solo desea imitar el rendimiento de los resultados de conversión por la API REST de GitHub fuera de línea, pero no quiere almacenamiento en caché de imágenes, soporte de fórmulas y estilo CSS elegante, use, use
html_as_a_string = gh_md_to_html.core_converter.markdown(your_markdown_as_a_string)
en Python.
Uso : gh-md-to-html <input_name> <optional_arguments>
Comportamiento predeterminado :
Por defecto, GH-MD-TO-HTML toma un nombre de archivo de Markdown como argumento y guarda el HTML generado en un archivo del mismo nombre, con .html en lugar de .md .
Algunas peculiaridades:
github-markdown-css/github-css.css (Agregar -c para hacerlo en línea)../images (agregue -i para deshabilitar esto).-w si desea verlo directamente en un navegador).id y los enlaces de archivo interno están precedidos por user-content- , por lo que puede incrustar el HTML generado en un sitio web más grande sin arriesgar los enfrentamientos de ID. Algunos casos de uso comunes :
A través de temas pasados, me di cuenta de que hay algunos casos de uso muy comunes que la mayoría de las personas parecen tener para este módulo. Aquí están los más comunes y qué opciones y argumentos usar para ellos:
-i -w --math false --box-width 25cm , aunque el agarre podría ser más eficiente para este propósito.--toc para admitir la sintaxis TOC de GitLab.--math true --emoji-support 0 --dont-make-images-links true .-i -c para tener todo en un archivo. Convertir archivos de Markdown desde la web con --origin-type :
Es posible que desee no solo convertir un archivo de Markdown local, sino también un archivo de un repositorio de GitHub, uno alojado en la web o el contenido de una cadena. Simplemente descargarlos o almacenarlos en un archivo a menudo no es suficiente, ya que su ubicación en la web también influye en cómo se deben resolver los enlaces a las imágenes a las que hacen referencia. ¡Afortunadamente, GH-MD-TO-HTML te ha respaldado!
Hay varios argumentos diferentes que puede usar para describir qué tipo de archivo es la entrada que dio referencias:
--origin-type file : el valor predeterminado; toma una ruta de archivo (relativa o absoluta)--origin-type repo : lleva una PTH a un archivo de Markdown en un repositorio de GitHub, en el formato <user_name>/<repo_name>/<branch-name>/<path_to_markdown>.md <Path_to_markdown> .md.--origin-type web : toma la URL de un archivo de Markdown alojado en la web.--origin-type string : toma una cadena que contiene markdown. Algunas de estas opciones que utiliza influye en cómo se resuelven los enlaces de imagen dentro del archivo de Markdown; Una sección posterior de este ReadMe describe esto en detalle. Ajuste de lo que va donde :
GH-MD-TO-HTML está escrito con el objetivo de generar un sitio web estático listo para el host para usted, con su directorio de trabajo actual como raíz. Además de usar -w para deshabilitar esto y permitirle ver el archivo generado directamente en un navegador, hay una serie de opciones que le permiten ajustar qué va y más popularmente cambia la raíz del sitio web. No hay necesidad de hacerlo a menos que desee por alguna razón, ¡así que no se moleste en leer esto si no es necesario!
--website-root (o -w ): dejar esta opción vacía, como se discutió anteriormente, le permite obtener una vista previa del archivo HTML generado directamente en un navegador (en la mayoría de los sistemas haciendo doble clic) en caso de que no desee alojar el archivo HTML generado, pero también puede proporcionar cualquier directorio que desee usar como raíz del sitio web. El valor predeterminado es su directorio de trabajo actual.--destination (o -d ): la ruta, en relación con --website-root , en la que se almacena el archivo HTML generado. Por defecto, la raíz del sitio web se usa para esto.--image-paths (o -i ): puede dejar este vacío para deshabilitar el almacenamiento en caché de imágenes, como se describió anteriormente (aunque esto no funcionará en caso de que se modifique --origin-type ), o suministre una ruta en relación con la raíz del sitio web para modificar dónde se almacenan las imágenes. El valor predeterminado es de images .image-paths no se vacía automáticamente entre múltiples ejecuciones de GH-MD a HTML por este motivo, para garantizar que esta optimización se pueda utilizar cruzando al convertir múltiples archivos en una masa.--css-paths (o -c ): puede dejar esto vacío para deshabilitar el almacenamiento del CSS en un archivo CSS externo (por ejemplo, útil, por ejemplo, si desea convertir solo un archivo), como se describe anteriormente, o suministrar una ruta relativa a la raíz del sitio web para modificar dónde se almacenará el archivo CSS (llamado github-css.css ). El valor predeterminado es github-markdown-css .--output-name (o -n ): el nombre del archivo bajo el cual almacenar el archivo HTML generado en el directorio de destino. Puede usar <name> en cualquier lugar de esta cadena, y se reemplazará automáticamente con el nombre del archivo de Markdown, por lo que, por ejemplo, gh-md-to-html inp.md -n "<name>-conv.html" almacenará el resultado en ino-conv.html (esto no funciona con --origin-type string , por supuesto).-n print para simplemente escribir la salida a stdout (imprima en la consola) en lugar de guardarla en cualquier lugar. El valor predeterminado es <name>.html , por lo que se adapta al nombre de su archivo de entrada.--output-pdf (o -p ): el archivo para almacenar el PDF generado. También puede usar el <name> -Syntax aquí. Si no se usa la opción -p , no se generará PDF (y debe haber seguido las instrucciones de instalación PDFKIT y WKHTMLTOPDF anteriores para que esta opción funcione), pero puede usar -p sin ningún argumento para que use <name>.pdf como un nombre de archivo sensible predeterminado. Exportar como PDF :
Como se mencionó anteriormente, puede exportar el archivo HTML generado como un PDF utilizando la opción --output-pdf . Hacerlo requiere que tenga wkhtmltopdf instalado (la versión parchada de Qt), para agregarla a la ruta (si está en Windows) y que tenga instalado pdfkit (por ejemplo, a través de pip3 install gh-md-to-html[offline_conversion] ), pero todos estos requisitos ya están superados por encima de la sección de instalación.
Sin embargo, hay algunas cosas que vale la pena señalar aquí. En primer lugar, no use esta opción si tiene información valiosa en un archivo llamado {yourpdfexportdestination}.html , donde {yourpdfexportdestination} es lo que suministró a -p , ya que este archivo se sobrescribirá temporalmente en el proceso; Además, no use -p en absoluto si está suministrando entrada no confiable a la opción -x .
También hay algunas opciones específicamente adaptadas para su uso con -p ; Estos son actualmente:
--style-pdf (o -s ): configure esto en false para deshabilitar el estilo del archivo PDF generado con el CSS de GitHub. Es posible que desee hacer esto porque el borde de que el CSS de GitHub dibuja alrededor de la página puede parecer contradictorio en los PDF, aunque hacerlo también puede influir negativamente en la apariencia de otras partes, así que use esto con un grano de sal. Cambiar qué convertidor de markdown de núcleo usar :
GH-MD-TO-HTML en realidad no hace tanto trabajo pesado cuando se trata de analizar la reducción y convertirlo en PDF; En cambio, envuelve un llamado "convertidor central" que hace la conversión básica de acuerdo con la especificación de Markdown, y desarrolla sus propias opciones, características, personalizaciones y estilo además de eso. De manera predeterminada, la API de REST de GitHub Markdown se usa para eso, ya que se acerca más a lo que hace Github con sus READMES, pero también puede darle a GH-MD-a HTML cualquier otro convertidor básico de Markdown para trabajar.
GH-MD-TO-HTML también viene con dos convertidores de núcleo alternativos incorporados para usar, que imitan la API REST de GitHub lo más cerca posible mientras agregan su propio toque personal.
Opción para decidir el convertidor de núcleo:
--core-converter (o -o ): puede usar esta opción para elegir entre varios convertidores de núcleo predefinidos (ver más abajo) en caso de que desee diferir del predeterminado.
También puede suministrar un comando bash (en sistemas UNIX/Linux) a esto, o un comando cmd.exe en Windows, en el que {md} se erige como un marcador de posición para el lugar donde la marca de entrada con shell se insertará mediante GH-MD-a HTML. Por ejemplo,
gh-md-to-html inp.md -o "pandoc -f markdown -t html <<< {md}"
Utilizará pandoc como convertidor de núcleo.
También puede hacerlo usando múltiples comandos, como
gh-md-to-html -o "printf {md} >> temp.md; pandoc -f markdown -t html temp.md; rm temp.md" ,
Mientras el resultado se imprima a Stdout.
Si usa la interfaz python en GH-MD-TO-HTML, también puede suministrar cualquier función que convierta una cadena Markdown en una cadena HTML en este argumento.
Convertidores de núcleo predefinidos a los que puede suministrar fácilmente --core-converter como cadenas:
OFFLINE : imita la API de REST Markdown de GitHub, pero fuera de línea usando Mistune. Esto requiere que se satisfagan las dependencias opcionales para "Offline_Conversion", utilizando pip3 install gh-md-to-html[offline_conversion] o pip3 install mistune>=2.0.0rc1 .OFFLINE+ : se comporta idéntico a fuera de línea, pero no elimina el contenido potencialmente dañino como JavaScript y CSS como la API REST GitHub generalmente lo hace. ¡No use esta función a menos que necesite una forma de convertir archivos de Markdown verificados seguros sin tener todos sus JS/estilo en línea despojados! Soporte para formulas en línea :
gh-md-to-html admite, por defecto, fórmulas en línea (sin importar qué convertidor central, ver arriba, use). Esto significa que puede escribir una fórmula de látex entre dos señales de dólar en la misma línea, y se reemplazará con una imagen SVG que muestra dicha fórmula. Por ejemplo,
$e = m cdot c^2$
Agregará la famosa fórmula de Einstein como una imagen SVG, bien alineada con el resto del texto que lo rodea, en su documento.
gh-md-to-html siempre intenta usar su instalación local de látex para hacer esta conversión (ventaja: rápido y no requiere internet). Sin embargo, si el látex o DVISVGM no están instalados o no los puede encontrar, utiliza un convertidor en línea (ventaja: no requiere que instale 3 GB de bibliotecas de látex) para lograr esto.
Puede usar las siguientes opciones para modificar este comportamiento:
--math (o -m ): Establezca esto en false para deshabilitar la representación de fórmula.--suppress-online-fallbacks : Establezca esto en true para deshabilitar el retroceso en línea para la representación de fórmulas, planteando un error si sus requisitos no están instalados localmente o no se pueden encontrar por alguna razón. almacenamiento en caché de imágenes y compresión de imágenes :
Como se explicó en profundidad arriba, GH-MD-a HTML guarda imágenes para que todas puedan cargarse desde la misma carpeta. Esto viene con las ventajas de
Además de estas ventajas, GH-MD-TO HTML también le permite establecer un nivel de compresión de imágenes para usar para estas imágenes. Si decide hacerlo, cada imagen se convertirá a JPEG (utilizando un color de fondo y una configuración de calidad de su gusto), y las imágenes se reducirán si el HTML generado establece que no serán necesarios en su tamaño completo de todos modos (puede usar este EG utilizando <img> -Tags directamente en su documento y que los suministra con un valor width o height ).
GH-MD-TO-HTML también es el único convertidor de markdown capaz de utilizar el attribido srcset HTML, que permite que el documento generado haga referencia a varias versiones a escala de manera diferente de la misma imagen, de las cuales el navegador cargará el más pequeño y grande en pantalla de pantalla más pequeña, lo que lleva a grandes reducciones de carga, por ejemplo, en el móvil. Habilitar esta característica puede conducir a mayores reducciones de tiempo de carga sin sacrificar ninguna calidad de imagen visible, lo que hace que GH-MD-TO-HTML sea la mejor opción si desea generar sitios web de carga rápida desde sus archivos de Markdown pesados de imagen.
La opción de usar para todo esto es
--compress-images .
y acepta una pieza de datos JSON con los siguientes atributos:
bg-color : el color que se usa como color de fondo al convertir las imágenes RGBA en JPEG (un formato RGB). El valor predeterminado es " white " y acepta casi cualquier valor de color HTML5 (" #FFFFFF ", " #ffffff ", " white " y " rgb(255, 255, 255) " habrían sido valores válidos).progressive : Guardar imágenes como JPEG progresivos. El valor predeterminado es falso.srcset : guarde las versiones a escala de la imagen de manera diferente y las proporcione a la imagen en su atributo SRCSET. El valor predeterminado es falso. Toma una variedad de diferentes anchos o True , que sirve como un atajo para " [500, 800, 1200, 1500, 1800, 2000] ".quality : un valor de 0 a 100 que describe a qué calidad se deben guardar las imágenes. El valor predeterminado a 90. Si se especifica un tamaño específico para una imagen específica en el HTML, la imagen siempre se convierte al tamaño correcto antes de reducir la calidad.Si este argumento se deja vacío, no se usa ninguna compresión en absoluto. Si este argumento se establece en True, se utilizan todos los valores predeterminados. Si se establece en datos JSON y se omiten algunos valores, los valores predeterminados se usan para estos.
También puede pasar un dict en lugar de una cadena que contiene datos JSON si está utilizando esta opción en Python Frontend.
La compresión de la imagen no funcionará, por razones obvias, si usa -i para deshabilitar el almacenamiento en caché de imágenes.
mis elecciones personales :
Markdown y Markdown con sabor a GitHub en general toman algunas decisiones impopulares, y GH-MD-TO HTML, imitándolo, también hace muchos de estas. Si su objetivo no es lo más cercano posible a Markdown (con sabor a GitHub), y desea utilizar la potencia completa que GH-MD-a HTML ofrece al máximo, recomiendo la siguiente lista de configuraciones y opciones. Sin embargo, tenga en cuenta que algunos de estos no son seguros al convertir contenido generado por el usuario.
--math true : esto ya está habilitado de forma predeterminada, por lo que no es realmente una recomendación, pero lo más probable es que desee tener soporte de matemáticas de látex en su archivo.--core-converter OFFLINE+ : esto convierte los archivos de Markdown fuera de línea en lugar de usar la API REST de GitHub, y permite el uso de cosas inseguras como el código en línea y cada HTML que pueda desear en su archivo de Markdown.--compress-images : hay muchas maneras de financiar estas opciones, pero permite algunas optimizaciones excelentes en las imágenes en caché, incluido el uso de HTML srcset -Attribute, que ningún otro convertidor de Markdown actualmente admite AFAIK.--box-width 25cm : lo más probable es que desee limitar el ancho del cuadro en el que se muestra el contenido del sitio web generado por razones de legibilidad, a menos que planee incrustar el HTML generado en un archivo HTML más grande.--toc true : esto le permite usar [[_TOC_]] como un atajo para una tabla de contenido en el archivo generado.--dont-make-images-links true : de forma predeterminada, GitHub envuelve cada imagen en un enlace a la fuente de la imagen, a menos que la imagen ya esté envuelta en un enlace diferente. Esta opción deshabilita este comportamiento para un mayor control sobre los enlaces de su imagen.--emoji-support 2 : GH-MD-TO-HTML es compatible con códigos cortos de emoji, como :joy: que luego se reemplazan con emojis en el archivo HTML generado. --emoji-support 2 lleva este nivel más allá al permitirle usar sus propios emojis personalizados, así que :path/to/funny_image.png: agregará funny_image.png como un emoji del tamaño de un emoji en el texto.--soft-wrap-in-code-boxes true : por defecto, GitHub muestra sus cuadros de código multilínea con una barra de desplazamiento horizontal si corren el riesgo de desbordarse. Use esta opción para tener (en mi humilde opinión) soft-wrap en los cuadros de código. Tenga en cuenta que las opciones se enumeran por relevancia, y todas ellas tienen valores predeterminados sensatos, así que no se sientan abrumados por cuántos hay; Puede leerlos hasta que encuentre lo que está buscando e ignorar de forma segura el resto.
La mayoría de las opciones están destinadas a personalizar el comportamiento predeterminado, por lo que ninguna de ellas es obligatoria para la mayoría de los casos de uso.
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.
Como se mencionó anteriormente, cualquier imagen mencionada en el archivo Markdown se almacena localmente y se hace referencia utilizando un hipervínculos relativos a la raíz en el HTML generado. Cómo el convertidor adivina la ubicación de la imagen se muestra en la siguiente tabla, con el tipo de imageink observado en la parte superior y el tipo de marca de entrada observada a la izquierda:
https:// o http:// | abordcado filepático | rel. filepático | Comenzando con / (por ejemplo , /imagedir/image.png ) | no comenzando con / (por ejemplo, imagedir/image.png ) | |
|---|---|---|---|---|---|
-t file | de la dirección | abordcado filepático | rel. FilePath (desde donde se encuentra el .md -file) | - | - |
-t string | de la dirección | ABS. Filepath, pero necesita confirmación por razones de seguridad | rel. FilePath (a donde se llama la herramienta), pero necesita confirmación por razones de seguridad | - | - |
username/repo/dir/file.md -t repo | de la dirección | - | - | username/repo/imagedir/image.png | username/repo/dir/imagedir/image.png |
https://foo.com/bar/baz.md -t web | de la dirección | - | - | https://foo.com/image.png | https://foo.com/bar/image.png |
Al igual que con todos mis proyectos, los comentarios (incluso si es algo pequeño como decirme que su caso de uso para mi proyecto, o decirme que no le gustó la estructura del ReadMe, o decirme que le gustó específicamente una característica específica) es muy apreciado, y me ayuda a mejorar este proyecto, ¡incluso si es algo muy pequeño! Puede soltar un problema con sus comentarios, breves y no formales, o incluso enviarme un correo electrónico si no desea plantear un problema por alguna razón. No planeo agregar funciones en el futuro en este momento, pero siempre estoy abierto a arreglar y ajustar las características existentes, la documentación, etc., y obviamente me encantaría escuchar sus sugerencias de características, incluso si no planeo agregarlas en el futuro cercano.
En general, soy muy receptivo cuando se trata de problemas de GitHub, y los tomo muy en serio y trato de resolverlos lo antes posible. Si se encuentra con errores, comportamientos extraños, errores de instalación y similares, al mismo tiempo que usa mi herramienta, no dude en decirme en un problema, ¡para que pueda solucionar el problema!
Si encontró esta herramienta útil, ¡considere protagonizarla en Github para mostrarme su agradecimiento! También agradecería que me hubiera contado sobre los problemas que encontró incluso si logró arreglarlos en su propia copia del código, por lo que también puedo solucionarlos en este repositorio.
gh-md-to-html para la conversión MD-a PDF (bajo una esencia sobre la conversión MD-to PDF): enlacegh-md-to-html en la documentación de otro proyecto: enlaceLos íconos fueron hechos por
.md-file.icon: Freepik de Flaticon.com
.md-file.icon: Freepik de Flaticon.com
Arrow-icon: Font Awesome by Dave Gandy, con licencia bajo Creative Commons Attribution-Share por igual 3.0 Unported
Github-icon: ícono de Github en iconscout
Descargo de responsabilidad : este módulo no está escrito por GitHub, ni está respaldado con GitHub, con el apoyo de GitHub, alimentado por GitHub o afiliado a GitHub. Solo utiliza una API pública proporcionada por GitHub, así como un archivo .css con licencia por GitHub bajo la licencia MIT.
