personal web log written by izabeera and dryobates

vim instantrst reStructuredText

Realtime reStructuredText preview in browser with Vim and InstantRst

by dryobates

Most of my projects documentation is written in reStructuredText with riv in vim. Same is for all those blog entries here. Until up recently my workflow was traditional: write, save, generate html, preview. Now it has changed...


reStructuredText [1] is de facto standard in Python's community for writing documentation. It's easily readable as plain text. You can use any text editor and be happy to see that generated document will be similar to what you see. Of course you have to use some imagination. E.g. text in **double stars** will render as bold text.

riv - reStructuredText in Vim

To make it easier to visualize and easier to edit some text editors have special syntax highlighting and shortcuts. I use vim with riv [2] extension.

Riv has a lot of shortcuts and built-in features that help editing RST. It has even some features that help managing todos or projects.

In case of visualizing results riv has shortcuts that are able to generate document and start it in browser to preview result.

Now the author of Riv made something even better...


InstantRST allows preview RST document in browser in real time. It has two parts: script written in vim and server written in python.

When you run :InstantRst from vim it will start browser and real time preview of your file.

To see what I mean go for project page [3] and see animated gif.

One short note: I wasn't able to install instantrst-py (the python part) from zip file as it was described on the project's page. On the other hand simple pip install instantrst-py did the thing.

[2]riv - reStructuredText in Vim
Jakub Stolarski. Software engineer. I work professionally as programmer since 2005. Speeding up software development with Test Driven Development, task automation and optimization for performance are things that focus my mind from my early career up to now. If you ask me for my religion: Python, Vim and FreeBSD are my trinity ;) Email: