{"id":9010,"library":"gh-md-to-html","title":"GitHub-flavored Markdown to HTML Converter","description":"gh-md-to-html is a feature-rich Python module and command-line interface for converting GitHub-flavored Markdown to HTML. It leverages GitHub's online API by default for conversion but also offers robust offline capabilities. The library extends basic Markdown conversion with features like GitHub-flavored CSS, formula support, advanced image caching and optimization, host-ready file placement, PDF conversion, emoji shortcode support, and Table of Contents generation. The current version is 1.21.3, with PyPI releases occurring on a feature-driven, irregular cadence, complemented by frequent internal 'test-releases' on GitHub.","status":"active","version":"1.21.3","language":"en","source_language":"en","source_url":"https://github.com/phseiff/github-flavored-markdown-to-html/","tags":["markdown","html","github-flavored-markdown","converter","pdf","static-site-generator","offline-conversion"],"install":[{"cmd":"pip install gh-md-to-html","lang":"bash","label":"Standard installation"},{"cmd":"pip install gh-md-to-html[offline_conversion]","lang":"bash","label":"With offline conversion support"},{"cmd":"pip install gh-md-to-html[pdf]","lang":"bash","label":"With PDF conversion support (requires wkhtmltopdf)"}],"dependencies":[{"reason":"Required for offline Markdown conversion.","package":"mistune","optional":true},{"reason":"Required for PDF output generation, in conjunction with wkhtmltopdf.","package":"pdfkit","optional":true},{"reason":"External dependency (not Python package) required for PDF conversion. Must be installed separately and available in system PATH.","package":"wkhtmltopdf","optional":true}],"imports":[{"note":"The primary function for programmatic conversion. Other utilities may be directly accessible under the `gh_md_to_html` module.","symbol":"main_workflow","correct":"from gh_md_to_html import main_workflow"}],"quickstart":{"code":"import os\nfrom gh_md_to_html import main_workflow\n\nmarkdown_content = \"\"\"\n# Hello, gh-md-to-html!\n\nThis is **GitHub-flavored Markdown** with $\\LaTeX$ formulas.\n\n- Feature 1\n- Feature 2\n\n```python\nprint('Code blocks are awesome!')\n```\n\"\"\"\n\n# Convert markdown string to HTML and save to a file\noutput_html_file = 'output.html'\nmain_workflow(\n    md_origin=markdown_content,\n    origin_type='string',\n    output_name=output_html_file,\n    destination_directory='.'\n)\nprint(f\"Converted markdown saved to {output_html_file}\")\n\n# Example of printing directly to console (without saving to file)\n# html_output_string = main_workflow(\n#     md_origin=markdown_content,\n#     origin_type='string',\n#     output_name='print'\n# )\n# print(html_output_string)","lang":"python","description":"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."},"warnings":[{"fix":"For 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'`.","message":"By 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install `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.","message":"PDF 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Rename 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).","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review 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.","message":"Markdown 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.","severity":"gotcha","affected_versions":"All versions when using `pandoc` or similar strict converters."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `wkhtmltopdf` on your system and add its installation directory (specifically the directory containing the `wkhtmltopdf` executable) to your system's PATH environment variable. Verify installation by running `wkhtmltopdf --version` in your terminal.","cause":"The `wkhtmltopdf` executable, required for PDF conversion, is not found in your system's PATH.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'wkhtmltopdf'"},{"fix":"Check your internet connection. If the issue persists, consider using the offline conversion feature by installing `gh-md-to-html[offline_conversion]` and specifying `core_converter='offline'` in your Python code or CLI command.","cause":"The default GitHub Markdown REST API is unreachable due to network issues, rate limiting, or the service being down. This prevents online Markdown conversion.","error":"requests.exceptions.ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))"},{"fix":"Rename the image files and their containing directories to remove any whitespaces. Ensure all image paths in your Markdown are updated accordingly.","cause":"Images referenced from local disk have paths containing whitespaces, which `gh-md-to-html` or the underlying HTML rendering engine might not handle correctly, leading to broken links.","error":"Images not displayed in the generated HTML, despite correct paths in Markdown."},{"fix":"If you need to preserve custom JavaScript or CSS, use the `offline+` core converter option. Install with `pip install gh-md-to-html[offline_conversion]` and then specify `core_converter='offline+'`. **Caution:** Only use `offline+` for trusted Markdown sources, as it bypasses security filters.","cause":"When using the default (GitHub API) core converter, `gh-md-to-html` applies GitHub's security filters, which strip `<script>` and `<style>` tags to prevent XSS vulnerabilities.","error":"JavaScript or CSS embedded in Markdown is stripped from the final HTML output."}]}