github flavored markdown to html
1.0.0
Um Frontend Python-Module e linha de comando amigável para converter o Markdown em HTML. Ele usa os githubs on-line markdown para html-api por padrão (que requer conexão com a Internet), mas vem com uma opção para conversão offline (que imita de perto o comportamento dos githubs), e qualquer outra ferramenta de Python ou comando também pode ser conectada a ele. Tudo o que você o usa é estendido automaticamente com uma tonelada de funcionalidade, como mais opções de saída, CSS com sabor de Github, suporte de fórmula, cache e otimização avançados de imagens, posto de arquivo e imagem para hospedeiro, conversão de PDF, suporte ao shortcode emoji, suporte a TOC e muito mais.
Embora seu principal objetivo seja a criação de páginas estáticas a partir de arquivos de marcação, por exemplo, em conjunto com um construtor de sites estáticos ou ações do GitHub, se você hospeda no Github, ele pode ser muito utilizado para qualquer outro objetivo.
Aqui está uma lista (não necessariamente extensa) de suas vantagens e recursos:
$ -formula- $ para usá-las), que o Github normalmente não o faz. GH-MD-TO-HTML usa LATEX e DVISVGM Se ambos estiverem instalados (vantagem: FAST, não requer Internet) e, de outra forma, o codecogs eqneditor (vantagem: não exige que você instale 3 GB de bibliotecas de látex) para conseguir isso.[[_TOC_]] , {:toc} e [toc] no início de uma linha vazia para criar uma tabela de conteúdo para o documento, como o Markdown com sabor de Gitlab, entre outros.Caso você esteja procurando uma alternativa ao Pandoc para converter o Markdown em PDF, aqui está uma lista de razões pelas quais você pode querer usar GH-MD-HTML em vez de Pandoc para o trabalho:
Embora o uso do pandoc para converter de Markdown para PDF geralmente produz resultados mais bonitos (afinal, o pandoc usa o LATEX), o GH-MD-para-HTML tem seu próprio conjunto de vantagens quando se trata de converter rapidamente arquivos complexos para uma tarefa de casa ou outros propósitos onde a confiabilidade pesam mais que a beleza:
$ -SIGNS e com quais caracteres a fórmula pode começar. Porém, essas regras não se aplicam em alguns editores comuns de marcação, como o MarkText, o que leva a muita frustração quando fórmulas que funcionavam no editor não funcionam mais ao converter com o pandoc (porém, a própria função de exportação para PDF do PDF às vezes falha nos arquivos pesados de fórmula sem uma mensagem de erro, o que o torna ainda menos confiável). A pior parte é que, sempre que o pandoc falha na conversão de .md em .pdf por causa disso, mostra o número da linha do erro baseado no arquivo .tex intermediário em vez do arquivo .md de entrada, o que dificulta a localização da raiz do problema. Como você deve ter adivinhado, o GH-MD-HTML não poderia se importar menos com a quantidade de espaço em branco com quem você inicia suas fórmulas, deixando essa decisão para você.Para resumir, a conversão MD-PDF do Pandoc atua bastante incomum quando se trata de imagens, listas aninhadas, entradas de bullet de multilina ou fórmulas e GH-MD-para-HTML não.
Use pip3 install gh-md-to-html para instalar diretamente a partir do índice de pacote Python, ou python3 -m pip install gh-md-to-html se estiver no Windows.
Ambos podem exigir sudo no Linux, e você pode opcionalmente fazer
python3 -m pip install gh-md-to-html[pdf_export]
e instalar wkhtmltopdf (v0.12.6 ou maior) para obter o recurso opcional de conversão em PDF e converter arquivos de marcação em pdf e/ou
python3 -m pip install gh-md-to-html[offline_conversion]
Para colocar o recurso opcional de conversão offline em funcionamento.
Se você estiver no Windows , talvez seja necessário adicionar wkhtmltopdf ao seu caminho no seu diretório de trabalho atual para obter a conversão em PDF para o trabalho, por exemplo, com PATH=%PATH%;c:/program files/wkhtmltopdf/bin ou algo semelhante, dependendo do local da instalação.
Se você deseja acessar a interface com sua linha de comando, basta fornecer gh-md-to-html com os argumentos documentados no texto de ajuda (acessível com gh-md-to-html -h e mostrado abaixo). No Windows, você deve fornecer python3 -m gh_md_to_html com os argumentos correspondentes.
Se você deseja acessar a interface via python, você pode usar
import gh_md_to_html e use gh_md_to_html.main() com os mesmos argumentos (e valores padrão) que você forneceria para a interface da linha de comando.
Se você deseja apenas imitar os resultados da conversão rendem pela API REST Offline do Github, mas não quer cache de imagem, suporte de fórmula e estilo CSS sofisticado, use
html_as_a_string = gh_md_to_html.core_converter.markdown(your_markdown_as_a_string)
em Python.
Uso : gh-md-to-html <input_name> <optional_arguments>
Comportamento padrão :
Por padrão, GH-MD-TO-HTML toma um nome de arquivo de marcação como argumento e salva o HTML gerado em um arquivo com o mesmo nome, com .html em vez de .md .
Algumas peculiaridades:
github-markdown-css/github-css.css (add -c para fazer isso em linha)../images (adicione -i para desativar isso).-w se você deseja visualizá -lo diretamente em um navegador).id e links internos de arquivo são precedidos por user-content- para que você possa incorporar o HTML gerado em um site maior sem arriscar confrontos de ID. Alguns casos de uso comuns :
Através de questões anteriores, percebi que existem alguns casos de uso muito comuns que a maioria das pessoas parece ter para este módulo. Aqui estão os mais comuns e quais opções e argumentos usarem para eles:
-i -w --math false --box-width 25cm , embora a aderência possa ser mais eficiente para esse fim.--toc para apoiar a sintaxe do TOC do GitLab.--math true --emoji-support 0 --dont-make-images-links true .-i -c para ter tudo em um arquivo. Convertendo arquivos de remarca da web com --origin-type :
Você pode não apenas converter um arquivo de marcação local, mas também um arquivo de um repositório do GitHub, um hospedado na Web ou o conteúdo de uma string. Simplesmente baixar isso ou armazená -los em um arquivo geralmente não é suficiente, pois sua localização na Web também influencia como os links para as imagens que eles fazem referência devem ser resolvidos. Felizmente, GH-MD-TO-HTML está de costas!
Há vários argumentos diferentes que você pode usar para descrever que tipo de arquivo da entrada você deu referências:
--origin-type file : o padrão; Tomar um caminho de arquivo (relativo ou absoluto)--origin-type repo : leva um PTH para um arquivo de marcação em um repositório do GitHub, no formato <user_name>/<repo_name>/<branch-name>/<path_to_markdown>.md <name>/<TACH_TO_Markdown> .md.--origin-type web : pega o URL de um arquivo de marcação hospedado na Web.--origin-type string : pega uma string contendo o Markdown. Algumas dessas opções que você usa influenciam como os links de imagem dentro do arquivo de marcação são resolvidos; Uma seção posterior deste ReadMe descreve isso em detalhes. Ajuste fino o que vai onde :
GH-MD-TO-HTML é escrito com o objetivo de gerar um site estático pronto para você, com seu diretório de trabalho atual como raiz. Além de usar -w para desativar isso e permitir que você visualize o arquivo gerado diretamente em um navegador, há várias opções que permitem ajustar o que vai aonde e, mais popularmente, alterar a raiz do site. Não há necessidade de fazê -lo, a menos que você queira por algum motivo, então não se preocupe em ler isso se não precisar!
--website-root (ou -w ): Deixando esta opção vazia, como discutido acima, permite visualizar o arquivo HTML gerado diretamente em um navegador (na maioria dos sistemas clicando-o), caso não desejem hospedar o arquivo HTML gerado, mas também pode fornecer qualquer diretório que deseje usar o Root do site. Padrões do seu diretório de trabalho atual.--destination (ou -d ): O caminho, em relação a --website-root , no qual o arquivo HTML gerado é armazenado. Por padrão, a raiz do site é usada para isso.--image-paths (ou -i ): você pode deixar isso vazio para desativar o cache de imagens, como descrito acima (embora isso não funcione caso você modifique --origin-type ) ou forneça um caminho em relação ao site-raiz para modificar onde as imagens são armazenadas. Padrão para images .image-paths não é esvaziado automaticamente entre várias execuções de GH-MD-para-HTML por esse motivo, para garantir que essa otimização possa ser usada em arquivo cruzado ao converter vários arquivos em um volume.--css-paths (ou -c ): você pode deixar isso vazio para desativar o armazenamento do CSS em um arquivo CSS externo (útil, por exemplo, se desejar converter apenas um arquivo), conforme descrito acima, ou fornecer um caminho em relação ao site-raízes para modificar onde o arquivo CSS (chamado github-css.css ) será armazenado. O padrão é github-markdown-css .--output-name (ou -n ): o nome do arquivo sob o qual armazenar o arquivo HTML gerado no diretório de destino. Você pode usar <name> em qualquer lugar desta string e ela será substituída automaticamente pelo nome do arquivo de marcação; portanto, por exemplo, gh-md-to-html inp.md -n "<name>-conv.html" armazenará o resultado em ino-conv.html (isso não funciona com --origin-type string .-n print para simplesmente escrever a saída para Stdout (imprima -o no console) em vez de salvá -lo em qualquer lugar. O valor padrão é <name>.html , por isso se adapta ao nome do arquivo de entrada.--output-pdf (ou -p ): o arquivo para armazenar o PDF gerado. Você também pode usar o <name> -syntax aqui. Se a opção -p -opção não for usada, nenhum PDF será gerado (e você precisará ter seguido as instruções de instalação PDFKIT & WKHTMLTOPDF acima para ter esse trabalho de opção), mas você pode usar -p sem argumentos para que ele use <name>.pdf como um nome de arquivo sensível. Exportando como PDF :
Como mencionado acima, você pode exportar o arquivo HTML gerado como um PDF usando a opção --output-pdf -Option. Isso exige que você tenha instalado wkhtmltopdf (a versão do QT), para adicioná-lo ao caminho (se você estiver no Windows) e para que pdfkit seja instalado (por exemplo, através do pip3 install gh-md-to-html[offline_conversion] ), mas todos esses requisitos já estão descritos acima na seção de instalação.
Há algumas coisas que valem a pena notar aqui, no entanto. Primeiro de tudo, não use esta opção se tiver informações valiosas em um arquivo chamado {yourpdfexportdestination}.html , onde {yourpdfexportdestination} é o que você forneceu ao -p , pois esse arquivo será temporariamente sobrescrito no processo; Além disso, não use -p se estiver fornecendo entrada não confiável para a -x -eption.
Existem também algumas opções especificamente adaptadas para uso com -p ; Estes são atualmente:
--style-pdf (ou -s ): defina-o como false para desativar o estilo do arquivo PDF gerado com o CSS do GitHub. Você pode querer fazer isso porque a fronteira que o CSS do Github atrai ao redor da página pode parecer contra -intuitiva nos PDFs, embora isso também possa influenciar negativamente a aparência de outras partes; portanto, use isso com um grão de sal. Alterando qual conversor principal de marcação para uso :
GH-MD-TO-HTML na verdade não faz tanto levantando-se tão pesado quando se trata de analisar o Markdown e convertê-lo em PDF; Em vez disso, envolve o chamado "conversor principal" que faz a conversão básica de acordo com as especificações do Markdown e cria suas próprias opções, recursos, personalizações e estilo sobre isso. Por padrão, a API REST do Github Markdown é usada para isso, pois chega mais próximo do que o Github faz com seus ReadMes, mas você também pode dar a GH-MD-TO-HTML qualquer outro conversor básico de Markdown para trabalhar.
GH-MD-TO-HTML também vem com dois conversores de núcleo alternativos de construção, que imitam a API REST do Github o mais próximo possível, além de adicionar seu próprio toque pessoal a ele.
Opção para decidir o conversor principal:
--core-converter (ou -o ): você pode usar esta opção para escolher entre vários conversores de núcleo predefinidos (veja abaixo), caso você queira diferir do padrão.
Você também pode fornecer um comando bash (nos sistemas UNIX/Linux) para isso, ou um comando cmd.exe no Windows, no qual {md} se destaca como um espaço reservado para onde a marcação de entrada com gh-gh-md-to-html será inserida por gh-md-html. Por exemplo,
gh-md-to-html inp.md -o "pandoc -f markdown -t html <<< {md}"
usará o Pandoc como seu conversor principal.
Você também pode fazer isso usando vários comandos, como
gh-md-to-html -o "printf {md} >> temp.md; pandoc -f markdown -t html temp.md; rm temp.md" ,
Enquanto o resultado for impresso para o stdout.
Se você usar a interface Python para GH-MD-para-HTML, também poderá fornecer qualquer função que converte uma sequência de marcação em uma sequência HTML para esse argumento.
Conversores de núcleo predefinidos para os quais você pode fornecer facilmente --core-converter como strings:
OFFLINE : imita a API REST de Marydown do Github, mas offline usando o Mistune. Isso requer que as dependências opcionais para "offline_conversion" sejam satisfeitas, usando pip3 install gh-md-to-html[offline_conversion] ou pip3 install mistune>=2.0.0rc1 .OFFLINE+ : se comporta idêntico ao offline, mas não remove conteúdo potencialmente prejudicial, como JavaScript e CSS, como a API REST GitHub normalmente. Não use esse recurso, a menos que precise de uma maneira de converter arquivos de marcação seguros, verificados manualmente, sem ter todo o seu JS inline/estilo retirado! Suporte para formulários embutidos :
Os suportes de gh-md-to-html , por padrão, fórmulas embutidas (independentemente do conversor do núcleo, veja acima, você usa). Isso significa que você pode escrever uma fórmula de látex entre sinais de dois dólares na mesma linha e será substituída por uma imagem SVG exibindo a referida fórmula. Por exemplo,
$e = m cdot c^2$
Adicionará a famosa fórmula de Einstein como uma imagem SVG, bem alinhada com o restante do texto ao seu redor, em seu documento.
gh-md-to-html sempre tenta usar sua instalação de látex local para fazer essa conversão (vantagem: FAST e não requer Internet). No entanto, se o LATEX ou o DVISVGM não estiverem instalados ou não conseguir encontrá -los, ele usa um conversor on -line (vantagem: não exige que você instale 3 GB de bibliotecas de látex) para conseguir isso.
Você pode usar as seguintes opções para modificar esse comportamento:
--math (ou -m ): defina isso como false para desativar a renderização de fórmula.--suppress-online-fallbacks : Defina isso como true para desativar o fallback on-line para renderização de fórmula, levantando um erro se seus requisitos não forem instalados localmente ou não puderem ser encontrados por algum motivo. cache de imagem e compactação de imagem :
Conforme explicado em profundidade acima, Gh-md-to-html salva imagens para que todas possam ser carregadas da mesma pasta. Isso vem com as vantagens de
Além dessas vantagens, o GH-MD-HTML também permite definir um nível de compactação de imagem para essas imagens. Se você decidir fazer isso, todas as imagens serão convertidas em JPEG (usando uma cor de fundo e configurações de qualidade do seu gosto), e as imagens serão reduzidas se o HTML gerado afirmar que não será necessário em seu tamanho completo (você pode fazer uso desse EG usando <img> -TAGS diretamente em seu documento e fornecindo -os com uma width explícita ou height ).
O GH-MD-para-HTML também é o único conversor de marcação capaz de usar o atributo HTML srcset , que permite que o documento gerado faça referência a várias versões em escala diferentes da mesma imagem, das quais o navegador carregará o menor o máximo em menores em tamanho de tela, levando a uma grande carga redução de cargas no EG no Mobile. Habilitar esse recurso pode levar a reduções de tempo de carregamento adicionais sem sacrificar qualquer qualidade de imagem visível, o que torna o GH-MD-HTML a melhor opção se você deseja gerar sites de carregamento rápido a partir de seus arquivos de marcação pesados.
A opção de usar para tudo isso é
--compress-images .
E aceita um pedaço de dados JSON com os seguintes atributos:
bg-color : a cor a ser usada como uma cor de fundo ao converter as imagens RGBA em JPEG (um formato RGB). Padrão para " white " e aceita quase qualquer valor de cores HTML5 (" #FFFFFF ", " #ffffff ", " white " e " rgb(255, 255, 255) " teria sido valores válidos).progressive : salve as imagens como JPEGs progressivos. O padrão é falso.srcset : salve versões em escala de maneira diferente da imagem e forneça -as à imagem em seu atributo srcset. Padrões para false. Leva uma variedade de larguras diferentes ou True , que serve como atalho para " [500, 800, 1200, 1500, 1800, 2000] ".quality : um valor de 0 a 100 descrevendo em que qualidade as imagens devem ser salvas. Padrão para 90. Se um tamanho específico for especificado para uma imagem específica no HTML, a imagem é sempre convertida no tamanho certo antes de reduzir a qualidade.Se esse argumento for deixado vazio, nenhuma compressão será usada. Se esse argumento for definido como true, todos os valores padrão serão usados. Se estiver definido como dados JSON e alguns valores forem omitidos, os padrões serão usados para eles.
Você também pode passar um ditado em vez de uma string contendo dados JSON se estiver usando esta opção no front -end do Python.
A compactação de imagem não funcionará, por razões óbvias, se você usar -i para desativar o cache de imagens.
minhas escolhas pessoais :
O Markdown e o Markdown com sabor de Github fazem algumas escolhas impopulares, e GH-MD-para-HTML, imitando-o, também faz muitos deles. Se o seu objetivo não for o mais próximo possível do markdown (com sabor de Github) e você deseja utilizar todo o poder que o GH-MD-TO-HTML oferece ao máximo, recomendo o seguinte (muito opinativo) de configurações e opções. Observe que alguns deles não são seguros ao converter conteúdo gerado pelo usuário.
--math true : isso já está ativado por padrão, portanto, não é realmente uma recomendação, mas você provavelmente desejará ter suporte matemático no látex no seu arquivo.--core-converter OFFLINE+ : Isso converte os arquivos de marcação offline, em vez de usar a API REST do Github, e permite o uso de coisas inseguras, como código embutido e todos os HTML que você poderia desejar em seu arquivo de marcação.--compress-images : Existem muitas maneiras de definir essas opções, mas permite algumas ótimas otimizações nas imagens em cache, incluindo o uso do HTML srcset -ATRIBUTION, que nenhum outro conversor de Markdown atualmente suporta AFAIK.--box-width 25cm : você provavelmente desejará limitar a largura da caixa em que o conteúdo do site gerado é exibido por razões de legibilidade, a menos que você planeje incorporar o HTML gerado em um arquivo HTML maior.--toc true : isso permite que você use [[_TOC_]] como um atalho para um índice no arquivo gerado.--dont-make-images-links true : Por padrão, o GitHub envolve cada imagem em um link para a fonte da imagem, a menos que a imagem já esteja envolvida em um link diferente. Esta opção desativa esse comportamento para obter mais controle sobre os links da sua imagem.--emoji-support 2 : GH-MD-TO-HTML suporta usando códigos de curtas emoji, como :joy: que são substituídos por emojis no arquivo HTML gerado. --emoji-support 2 leva esse nível ainda mais, permitindo que você use seus próprios emojis personalizados, então :path/to/funny_image.png: adicionará funny_image.png como um emoji do tamanho de emoji ao texto.--soft-wrap-in-code-boxes true : Por padrão, o GitHub exibe suas caixas de código multilina com uma barra de rolagem horizontal se elas correrem o risco de transbordar. Use esta opção para ter (IMHO mais razoável) Brilhão Soft em caixas de código. Observe que as opções são listadas ordenadas por relevância e todas elas têm padrões sensatos, portanto, não se sinta sobrecarregado com o quantos existem; Você pode apenas lê -los até encontrar o que está procurando e ignorar com segurança o resto.
A maioria das opções destina -se a personalizar o comportamento padrão, para que nenhum deles seja obrigatório para a maioria dos 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 mencionado acima, qualquer imagem referenciada no arquivo de marcação é armazenada localmente e referenciada usando um hiperlinks de raiz no HTML gerado. Como o conversor adivinha a localização da imagem é mostrada na tabela a seguir, com o tipo de imagelink observado na parte superior e o tipo de marcação de entrada observada à esquerda:
https:// ou http:// | Abs. filepath | rel. filepath | Começando com / (por exemplo, /imagedir/image.png ) | não começando com / (por exemplo, imagedir/image.png ) | |
|---|---|---|---|---|---|
-t file | do endereço | Abs. filepath | rel. filepath (de onde está o .md -file) | - | - |
-t string | do endereço | Abs.FilePath, mas precisa de confirmação por razões de segurança | rel. filepath (para onde a ferramenta é chamada), mas precisa de confirmação por razões de segurança | - | - |
username/repo/dir/file.md -t repo | do endereço | - | - | username/repo/imagedir/image.png | username/repo/dir/imagedir/image.png |
https://foo.com/bar/baz.md -t web | do endereço | - | - | https://foo.com/image.png | https://foo.com/bar/image.png |
Como em todos os meus projetos, o feedback (mesmo que seja apenas algo pequeno como me dizer seu caso de uso para o meu projeto ou me dizer que você não gostou da estrutura do ReadMe, ou me dizendo que você gostou especificamente de um recurso específico) é muito apreciado e me ajuda a melhorar esse projeto, mesmo que seja algo muito pequeno! Você pode simplesmente abandonar um problema com seu feedback, curto e não formal, ou até me enviar um e-mail se não quiser levantar um problema por algum motivo. Não planejo adicionar recursos no futuro no momento, mas estou sempre aberto a consertar e ajustar os recursos existentes, a documentação etc.
Geralmente, sou muito receptiva quando se trata de problemas do GitHub, e os leva muito a sério e tento resolvê -los o mais rápido possível. Se você se deparar com bugs, comportamentos estranhos, erros de instalação e afins enquanto estiver usando minha ferramenta, não hesite em me dizer em um problema, para que eu possa resolver o problema!
Se você achou essa ferramenta útil, considere estrelando -a no Github para me mostrar sua apreciação! Eu também apreciaria se você me contasse sobre os problemas que encontrou, mesmo que você conseguisse corrigi -los em sua própria cópia do código, para que eu possa corrigi -los neste repositório também.
gh-md-to-html para MD para PDF (sob uma essência sobre conversão MD para PDF): Linkgh-md-to-html na documentação de outro projeto: linkOs ícones foram feitos por
.md-file.icon: Freepik de Flaticon.com
.md-file.icon: Freepik de Flaticon.com
Arrow-icon: Fonte Awesome de Dave Gandy, licenciado sob Creative Commons Attribution-Share 3.0
Github-icon: ícone do github no íconscout
Isenção de responsabilidade : Este módulo não é escrito pelo Github, nem é endossado com o Github, apoiado pelo GitHub, alimentado pelo GitHub ou afiliado ao GitHub. Ele usa apenas uma API pública fornecida pelo GitHub, bem como um .CSS-File licenciado pelo GitHub sob a licença do MIT.
