GitHub-flavored Markdown to HTML Converter

Common errors

• FileNotFoundError: [Errno 2] No such file or directory: 'wkhtmltopdf'

  cause The `wkhtmltopdf` executable, required for PDF conversion, is not found in your system's PATH.
  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.

• requests.exceptions.ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))

  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.
  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.

• Images not displayed in the generated HTML, despite correct paths in Markdown.

  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.
  fix Rename the image files and their containing directories to remove any whitespaces. Ensure all image paths in your Markdown are updated accordingly.

• JavaScript or CSS embedded in Markdown is stripped from the final HTML output.

  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.
  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.

Warnings

• gotcha 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.
  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'`.
• gotcha 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.
  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.
• gotcha 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.
  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).
• gotcha 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.
  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.

Install

• pip install gh-md-to-html Standard installation
• pip install gh-md-to-html[offline_conversion] With offline conversion support
• pip install gh-md-to-html[pdf] With PDF conversion support (requires wkhtmltopdf)

Imports

• 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.

Quickstart

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)