A user-friendly python-module and command-line frontend to convert markdown to html. It uses GitHubs online Markdown-to-html-API by default (which requires internet connection), but comes with an option for offline conversion (which closely imitates GitHubs behavior), and any other python- or commandline tool can be plugged into it as well. Whatever you use it with is automatically extended with a ton of functionality, like more in- and output options, github-flavored CSS, formula support, image downloading, host-ready file- and image-placement, pdf-conversion, and more.
Whilst its main purpose is the creation of static pages from markdown files, for example in conjunction with a static website builder or github actions if you host on Github, it can be very well-used for any other purpose.
- Lets you specify the markdown to convert as a string, as a repository path, as a local
file name or as a hyperlink.
- Pulls any images referenced in the markdown files from the web/ your local storage and
places them in a directory relative to your specified website root, so the resulting file structure is host-ready for
static sites. Multiple arguments allow the customization of the saving locations, but the images will always be
referenced correctly in the resulting html files. This is especially useful since it reflects GitHub's behavior to serve cached copies of README-images instead of linking to them directly, reducing tracking and possibly downscaling overlarge images in the process.
- Creates all links as root-relative hyperlinks and lets you specify the root directory
as well as the locations for css and images, but uses smart standard values for
- Supports inline LaTeX-formulas (use
$to use them), which GitHub usually doesn't. gh-md-to-html uses
LaTeX and dvisvgm if they are both installed (advantage: fast,
requires no internet), and otherwise the Codecogs EqnEditor (advantage: doesn't require
you to install 3 GB of LaTeX libraries) to achieve this.
- Supports exporting to pdf with or without Github styling, using the
pdfkit python module (if it is installed).
- Tested and optimized to look good when using DarkReader (the
.js-module as well as the browser extension). This is especially relevant considering that DarkReader doesn't usually
shift the colors of svg images, and the formulas added by gh-md-to-html's formula support are embedded as inline svg.
gh-md-to-html ensured that the formulas are the same color as the text, shifted in accordance with DarkReader's
- Supports umlauts and other non-ascii-characters in plain text as well as in multiline code blocks, which the github
REST api usually doesn't.
- Allows you to choose which tool or module to use at its core for the basic markdown to html conversion.
- Styles its output with github's README-css (can be turned off).
- Allows you to choose a width for the box surrounding the text; this can increase readability if you intend to host the
markdown file stand-alone rather than embedded into a different html file (see
- Comes with an optional support for the use of
[toc]at the beginning of an otherwise empty
line to create a table of content for the document, like GitLab-flavored markdown does, among others.
- Comes with an option to compress and downscale all images referenced in the markdown file (does not affect the
original images) with a specified background color (default is white) for converting RGBA to RGB, and a specified
compression rate (default is 90). Images with a specified width or height attribute in pixels get scaled down to that
size to reduce loading time. This helps severely reduce the size of generated pages for markdown files with lots of
images. There is also an option to save all images in multiple sizes and let the html viewer/browser pick the one
fitting for the viewport size (using the img srcset attribute), thus making gh-md-to-html the only md-to-html
converter with builtin srcset support for image load reduction.
- If two equal images from equal or different sources are referenced in the given markdown file, and both would be saved
in the same resolution et cetera, both are pointed to the same copy in the generated html to minimize loading
- Comes with an option to closely imitate GitHub's markdown-to-html-conversion behavior offline!
Whilst using pandoc to convert from markdown to pdf usually yields more beautiful results (pandoc uses LaTeX, after
all), gh-md-to-html has its own set of advantages when it comes to quickly converting complex files for a homework
assignment or other purposes where reliability weights more than beauty:
- pandoc converts .md to LaTeX and then renders it to pdf, which means that images embedded in the .md are shown where
they fit best in the .pdf and not, as one would expect it from a .md-file, exactly where they were embedded.
- pandoc's pandoc-flavored markdown supports formulas; however, some specific rules apply regarding the amount of
whitespace cornering the
$-signs and what characters the formula may start with. These rules do not apply in some
common markdown editors like MarkText, though, which leads to lots of frustration when formulas that worked in the
editor don't work anymore when converting with pandoc (MarkText's own export-to-pdf-function sometimes fails on
formula-heavy files without an error message, though, which makes it even less reliable). The worst part is that,
whenever pandoc fails converting .md to .pdf because of this, it shows the line number of the error based on the
intermediate .tex-file instead of the input .md-file, which makes it difficult to find the problem's root.
As you might have guessed, gh-md-to-html couldn't care less about the amount of whitespace you start your formulas
with, leaving the decision up to you.
- pandoc supports multiple markdown flavors. The sole formula-supporting one of these is pandoc-flavored markdown, which
comes with some quite specific requirements regarding the amount of trailing whitespace before a sub-list in a nested
list, and other requirements to create multi-line bullet point entries. These requirements are not fulfilled my many
markdown-editors (such as MarkText) and not required by many other markdown flavors, causing pandoc to not render
multiline bullet point entries and nestled lists correctly in many cases.
gh-md-to-html, on the other hand, supports both nested lists like you would expect it, and formulas, releasing
the burden of having to edit entire markdown files to make then work with pandoc's md-to-html-conversion from your
To sum it up, pandoc's md-to-pdf-conversion acts quite unusual when it comes to images, nested lists, multiline bullet
point entries, or formulas, and gh-md-to-html does not.
pip3 install gh-md-to-html to install directly from the python package index, or
python3 -m pip install ... if
you are on windows.
git clone https://github.com/phseiff/github-flavored-markdown-to-html.git cd github-flavored-markdown-to-html pip3 install .
to clone from master and add changes before installing.
Both might require
sudo on Linux, and you can optionally do
sudo apt-get install wkhtmltopdf python3 -m pip install pdfkit
(if you want to use the optional pdf features) to include pdf support into your installation.
If you want to access the interface with your command line, you can just supply
gh-md-to-html with the arguments documented in the help text (accessible with
gh-md-to-html -h and shown below). On windows, you must supply
python3 -m gh_md_to_html with the corresponding
If you want to access the interface via python, you can use
and then use
gh_md_to_html.main() with the same arguments (and default values) you would
supply to the command line interface.
If you only want to imitate the conversion results yield by GitHub's REST API offline, but don't want image caching,
formula support and fancy CSS styling, use
html_as_a_string = gh_md_to_html.core_converter.markdown(your_markdown_as_a_string)
All arguments and how they work are documented in the help text of the program, which looks
As mentioned above, any image referenced in the markdown file is stored locally and
referenced using a root-relative hyperlinks in the generated html. How the converter
guesses the location of the image is shown in the following table, with the type of imagelink noted on the top and the type of input markdown noted on the left:
||abs. filepath||rel. filepath||starting with
||not starting with
||from the address||abs. filepath||rel. filepath (from where the
||from the address||abs.filepath, but needs confirmation for security reasons||rel. filepath (to where the tool is called from), but needs confirmation for security reasons||-||-|
||from the address||-||-||
||from the address||-||-||