Quickmd

This project is a simple tool that solves a simple problem: I'd like to preview markdown files as they'll show up on Github, so I don't have to push my READMEs before I can tell whether they're formatted well enough.

It launches a simple QtWebEngine using PyQt that renders the compiled HTML of the given markdown file. It monitors this file for any changes and reloads. It uses a stylesheet that's literally copied off Github's markdown stylesheet.

Note: I have no idea if I'm allowed to use Github's stylesheet. The relevant file is in quickmd/resources/github.css, and if I am told I shouldn't be using it I'll go ahead and scrub it from git history.

Installation

You'll need the "markdown" command-line tool. Installation on Arch Linux goes like this:

# pacman -Sy markdown

It should be similar on other systems. After that, it should be enough to install dependencies like this:

# python3 setup.py install

Theoretically, this should install everything (pyqt5 and pyyaml) and place the binary in the right place.

Note: I am not a professional python developer. If you happen to be one and you see something horribly wrong, please open an issue or a PR and I'll gladly apply the fixes.

Usage

This command should do the trick:

$ quickmd <path-to-file.md>

Once the preview is open, pressing Esc will close it. Personally, I have a Vim keybinding that spawns it and detaches. There are no command-line flags, although I might add some in the future. There are, however, some ways you could configure the tool.

Configuration

General configuration can be applied with a yaml file, located in $HOME/.quickmd.yaml. Currently, there is only one setting, markdown_command, which is the command-line that compiles the markdown into HTML. By default, it uses markdown, as noted above. If you'd like to render fenced code blocks and other fancy stuff, you could use pandoc:

# in ~/.quickmd.yaml
markdown_command: "pandoc {filename}"

In order to customize the look of the preview, you can add CSS in $HOME/.quickmd.css. For instance, if you create the file and put this in it:

// in ~/.quickmd.css
body,
h1, h2, h3, h4, h5, h6
{
  background-color: #333 !important;
  color: #aaa !important;
}

pre, code
{
  background-color: #111 !important;
  color: #eee !important;
}

You should get a reasonable-looking "night mode" with a dark background and light text color.

Additional configuration may be added in the future. If you have a suggestion, please open a Github issue.

Internals

All this tool does is hook up a command-line to generate HTML, and then render that in an encapsulated QtWebEngine-based "browser". It's stupidly simple, about a 100 lines of code or so. It might get larger if I feel like adding configuration, or tests, or more options, but for now, it does a good job for my very limited usage scenarios.