A Markdown to GitHub-style HTML file conversion utility

Overview

ghmdlib (GitHub Markdown Library) is a light-weight and simple command line utility (and back-end library) designed to convert Markdown files into GitHub Flavoured HTML. It does so by using the GitHub Markdown API in combination with GitHub Markdown CSS.

As an aside, the ghmdlib command line utility was used for proofing this README.md file, using the following command:

$ ./ghmd.py ../README.md --preview 

Quickstart

Installation

To install ghmdlib, first activate your target virtual environment, then use pip:

pip install ghmdlib

This will install both the library and the command line utility.

For older releases, visit PyPI or the GitHub Releases page.

Command Line Utility Usage

Simply run ghmdlib with the path to the markdown file(s) you want to convert. An HTML file will be created in the same directory as the original markdown file with the same filename, using an .html file extension.

For example:

ghmd /path/to/my-file.md

Library Usage

To integrate the Markdown to HTML converter into a Python project, the library can be called as:

from ghmdlib import converter

# Convert a Markdown file with auto-open preview.
converter.convert(path='/path/to/my-file.md', preview=True)

Command Line Utility Options

Help Menu: --help

The help menu can be accessed at any time using the following. This provides an overview of the tool's capabilities and available options.

ghmd --help

Offline Mode: --offline

If using ghmdlib in a sensitive environment, or without internet connectivity, the CLI utility and library can be used offline, making use of the pre-downloaded CSS files (for both the dark and light themes), and the mdtex2html library for Markdown to HTML conversions, rather than calling the GitHub API.

Themes: --dark and --light

The default CSS styles adapt to the system's dark mode setting of the reader. If you want to force the CSS to be light or dark, you can use the --light or --dark options.

For example, to render the Markdown file in dark mode, you can use:

ghmd /path/to/my-file.md --dark

Both --light and --dark can be used in combination with --embed-css.

Embedded CSS: --embed-css

By default, ghmdlib will add the remote CSS as a <link> tag in the HTML file. If you want to embed the CSS directly into the HTML file so that, for example, you can send the HTML file to someone else and they can view it without an internet connection, you can use the --embed-css option.

ghmd /path/to/my-file.md --embed-css

Plain Markdown: --no-gfm

The tool offers two modes: GitHub Flavored Markdown (gfm by default) and plain Markdown. To use the latter, the --no-gfm option can be used:

ghmd /path/to/my-file.md --no-gfm

GitHub API Token

By default, ghmdlib uses unauthenticated requests to the GitHub API, which has a rate limit of 60 requests per hour. To increase this limit to 5000 requests per hour, you can set the GITHUB_TOKEN environment variable with a GitHub personal access token:

export GITHUB_TOKEN=your_github_token_here

To create a personal access token, visit your GitHub Settings > Developer Settings > Personal access tokens and create a new token (no specific scopes are required).

Using the Library

The documentation suite provides detailed explanations and usage examples for each importable module. For in-depth documentation, code examples, and source links, refer to the Library API page.

A search field is available in the left navigation bar to help you quickly locate specific modules or methods.

Troubleshooting

No troubleshooting guidance is available at this time.

For questions not covered here, or to report bugs, issues, or suggestions, please open an issue on GitHub.