Install & Compatibility
Where this runs
tested against v1.21.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.930 runs
installs and imports cleanly · install 0.0s · import 0.000s · 55.8MB
glibcpy 3.10–3.930 runs
installs and imports cleanly · install 3.3s · import 0.000s · 57MB
55MB installed
● package 55MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
main_workflow
✓ from gh_md_to_html import main_workflow
The primary function for programmatic conversion. Other utilities may be directly accessible under the `gh_md_to_html` module.
This quickstart demonstrates how to convert a Markdown string to an HTML file using the `main_workflow` function. It showcases basic GitHub-flavored Markdown features including headers, bold text, lists, and code blocks. For more complex use cases, such as converting local files, repository paths, or hyperlinks, or to leverage features like PDF export and offline conversion, consult the library's full documentation and optional arguments.
import os
from gh_md_to_html import main_workflow
markdown_content = """
# Hello, gh-md-to-html!
This is **GitHub-flavored Markdown** with $\LaTeX$ formulas.
- Feature 1
- Feature 2
```python
print('Code blocks are awesome!')
```
"""
# Convert markdown string to HTML and save to a file
output_html_file = 'output.html'
main_workflow(
md_origin=markdown_content,
origin_type='string',
output_name=output_html_file,
destination_directory='.'
)
print(f"Converted markdown saved to {output_html_file}")
# Example of printing directly to console (without saving to file)
# html_output_string = main_workflow(
# md_origin=markdown_content,
# origin_type='string',
# output_name='print'
# )
# print(html_output_string)
gh-md-to-html --version
Debug
Known issues
gotchaBy default, `gh-md-to-html` uses GitHub's online Markdown REST API for conversion, which requires an internet connection and strips potentially harmful content like `<script>` and `<style>` tags for security. If you need offline conversion or want to retain such content, use the `offline` or `offline+` core converter options.fixFor offline conversion, install with `pip install gh-md-to-html[offline_conversion]` and use `core_converter='offline'` or `core_converter='offline+'` in `main_workflow` or via the CLI flag `--core-converter 'offline'`.
affects: All versions
gotchaPDF conversion requires the external tool `wkhtmltopdf` to be installed on your system and accessible via the system PATH, in addition to the Python `pdfkit` library (installed with `gh-md-to-html[pdf]`). Without `wkhtmltopdf`, PDF output will fail silently or with an error related to its absence.fixInstall `wkhtmltopdf` (e.g., from its official website) and ensure its executable is in your system's PATH. For Windows, this might involve manually adding `c:/program files/wkhtmltopdf/bin` to your PATH environment variable.
affects: All versions
gotchaWhen embedding images from local disk (i.e., not via a URL) into your Markdown, ensure that the file paths to these images do not contain whitespaces. Whitespaces in local image paths can lead to broken image links in the generated HTML.fixRename image files and their containing directories to remove any whitespaces, or ensure paths are properly escaped if your operating system or specific converter can handle it (though avoiding spaces is safer).
affects: All versions
gotchaMarkdown syntax for formulas can be sensitive to whitespace or specific characters when using certain core converters (like `pandoc`) which have strict rules. Formulas that work in some Markdown editors might not render correctly.fixReview the specific Markdown flavor's rules for formula syntax, especially around `$` delimiters. Consider using `gh-md-to-html`'s default (GitHub API) or `offline` converters which are more forgiving, or properly escape dollar signs.
affects: All versions when using `pandoc` or similar strict converters.
Upgrade
Version history
1.21.3latest on PyPI · released Jun 17, 2024
Audit
Dependencies
mistuneoptionalRequired for offline Markdown conversion.
pdfkitoptionalRequired for PDF output generation, in conjunction with wkhtmltopdf.
wkhtmltopdfoptionalExternal dependency (not Python package) required for PDF conversion. Must be installed separately and available in system PATH.