Skip to main content

Live preview Markdown and reStructuredText files as HTML in a web browser

Project description

The preview-markup program takes a text file with lightweight markup (Markdown and reStructuredText are supported) and shows a live preview of the markup rendered to HTML in your web browser. When you save your text file the preview is automatically updated within a couple of seconds. That’s all there is to it!


The preview-markup program is written in Python and is available on PyPI which means installation should be as simple as:

$ pip install preview-markup

There’s actually a multitude of ways to install Python packages (e.g. the per user site-packages directory, virtual environments or just installing system wide) and I have no intention of getting into that discussion here, so if this intimidates you then read up on your options before returning to these instructions ;-).

Required system packages

The preview-markup program uses the Misaka package for Markdown parsing because it’s compatible with GitHub Flavored Markdown. This may require you to ensure that the libffi development files are installed before you attempt to install preview-markup. On Debian and Ubuntu based systems this can be accomplished as follows:

$ sudo apt-get install libffi-dev

Getting started

To get started you simply run the command preview-markup. If you give it a filename as an argument then that file will be previewed, otherwise the or README.rst file in the current working directory is previewed.

If you want to run preview-markup in the background then you probably won’t appreciate the logging to the terminal that is enabled by default. In this case I suggest you use the following command line:

$ preview-markup -q &

The -q is short for --quiet and the & instructs your shell to run the program in the background. If you want to kill the program later on just run the fg command (this will bring the program back to the foreground) and then press Control-C (this will kill the program).

Future improvements

Some random ideas for future improvements (I may implement these as time permits or when I feel like programming but don’t feel like picking up one of my many other projects):

Automatically close orphaned windows
When the command line program is terminated the browser window or tab page that was previously opened should be closed automatically. This can probably be implemented using a JavaScript call to the server to check if the server is still alive, if not then just call window.close().
Instant updates instead of meta refresh
Right now there’s a hard coded 10 second meta refresh in the HTML template. It would be a lot more elegant if the server used inotify or something similar to instantly detect changes and push those to the browser client. For now the meta refresh achieves the main goal though :-).

Why this project?

Different variations of preview-markup have lived in my private dotfiles repository for years now (I track ~/bin in my dotfiles repository). Over those years the program has had several names and very similar yet slightly different purposes. By the time I decided to clean up these “variations on a similar theme” I was using several different shell and Python scripts working together to do the same things that preview-markup now does. I decided to merge, cleanup, document and publish that mess of Python and shell scripts for multiple reasons:

  1. I wanted to merge all of the features that I’d grown to appreciate into a single coherent piece of software that was easy and intuitive to use (and written in Python so I could more easily maintain it :-).
  2. I wanted to manage the installation of that software as a Python package with properly specified dependencies where a single pip install was enough to get things going.
  3. Last but not least: Given the effort I’d already put into it, it seemed a shame not to share my work with the world.

Similar projects

I created preview-markup because I couldn’t find a tool that provided live previews of Markdown and reStructuredText markup and just because it was fun to work on, however this is clearly an itch that dozens of developers have scratched over the years :-). Here are some similar projects that I’ve run into and/or used in the past:

Live preview of reStructuredText files. A personal favorite of mine, simple and sweet, does exactly what is promises. Written in Python.
Provides local previews of Markdown files exactly as GitHub renders them by using the GitHub API to render the Markdown to HTML. Written in Python.
Live preview of Markdown files. Written in JavaScript (using Node.js).
Live preview of Markdown files. Makes it an explicit goal to render things just like GitHub does. Written in Ruby.


The latest version of preview-markup is available on PyPI and GitHub. For bug reports please create an issue on GitHub. If you have questions, suggestions, etc. feel free to send me an e-mail at


This software is licensed under the MIT license.

© 2018 Peter Odding.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

preview-markup-0.3.3.tar.gz (11.5 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page