skip to navigation
skip to content


Preview Rst Document Instantly


  1. static files are served, the file in the same dir can be get with _static/file
  2. The index file will always show from remote’s main file
  3. Improved Style: Using mars.css
  4. add debug to stop open browser
  5. add error log and error page

This is a server for preview rst document instantly.

You can use it with instantRst.vim

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


# Got some issue on pypi
# sudo pip install instant-rst
sudo pip 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}

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

curl -d file='' -d p='0.3' 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
File Type Py Version Uploaded on Size
instant-rst- (md5) Source 2016-01-12 14KB