Preview Rst Document Instantly

rst, docutils, preview
pip install instant-rst==


InstantRst Server



TOTALLY REWRITED, now python 3.0 only #22. and support local image #13

will be a stable version.

only tested on Mac OS, please post issues and PR if have problems.


This is project will no more adding new features

Future project update will be found in

This is a local server for preview rst document instantly.

You can use it with instantRst.vim

riv.vim (vim) + InstantRst (web server) + mars.css (theme)


# Got some issue on pypi
# sudo pip install instant-rst

sudo pip3 install


usage: instantRst [-h] [-f FILENAME] [-b BROWSER] [-p PORT] [-s STATIC_DIR] [-t TEMPLATE_DIR]

optional arguments:

-h, --help show this help message and exit
  The local filename for Converting
-b BROWSER, --browser BROWSER
  The browser command for viewing Default is '' for using system default
-p PORT, --port PORT
  The port for server to use Default is '5676'
-t TEMPLATE_DIR, --template-dir TEMPLATE_DIR
  Directory containing a template to be used when rendering the output. Defaults to a bundled rhythm.css_
-s STATIC_DIR, --static-dir STATIC_DIR
  The directory containing static files used by the template. Defaults to a bundled rhythm.css_
-l, --localhost-only
  Only use localhost, disable lan ip default: False
-d, --additional-dir
  Additional directories to serve. One time per directory.
--debug-dir Debug mode, Do not open browser
To convert a rst document

You can start with instantRst -f file.rst

Then the brower will opened the converted file at http://localhost:<port>


Action Http Method Request Body or Param Curl Command
Show Converted file GET


When file is omitted, Then a default index page will be opened.

curl http://localhost:5676?file=/tmp/test.rst

Refresh window with

a file and scroll to a position(a float)


or PUT

{file:file.rst, p:pos, dir:dir}

file: the file to show

dir: the static dir

p: the cursor position

When file/dir is omitted, Then will only scroll to that pos

curl -d file='' -d p='0.3' -p dir='test' http://localhost:5676
Close Server DELETE   curl -X DELETE http://localhost:5676


for debian user, you may need to install gevent manually

sudo apt-get install libevent-dev
sudo apt-get install python-all-dev
sudo pip install greenlet
sudo pip install gevent


  1. Default Static file:

    the static/main.css|js is served there

    The instant rst's default theme is set there.

    You can pass the -s for default static directory.

  2. Additional Static file:

    You can pass the -d for additional static directory.

    The basename of the directory is used as the static file's STATIC URL


    You have a file named test/test.jpg

    You can start instantRst with instantRst -f test/test.rst -d test

    then the file is served with localhost:5676/test/test.jpg

  3. Dynamic static file:

    When using with dynamic files, you can post with '-dir=DYN_DIR_NAME' to update the DYN_STATIC_DIR


    You have a file named test/test.jpg

    When you start instantRst instantRst -f test/test.rst

    The file is served with localhost:5676/_static/test.jpg

    When you switch to another file like test1/test.rst Then you can post with dir=test1 or dir=~/rst/test1 to change the static dir.


Contribution are welcomed.

git clone the project:

git clone

install local package:

sudo pip install . --upgrade

start test with local package:

# localhost:5676
python scripts/instantRst --debug -f test/test.rst

change to static/template file should change and

publish to pypi:

# register
# python register -r pypi

python sdist upload -r pypi


  1. the template_dir option is not working