reStructuredText in vim. A personal Wiki for rst.
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 2 commits ahead, 151 commits behind gu-fan:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Riv: reStructuredText in Vim

Your Personal Wiki in RST, And More

Author:Rykka G.F
NOTE:Currently in rebuilding process.


Riv is short for 'reStructuredText in Vim'.

It is a plugin for the Vim text editor, which aims to provide better support for reStructuredText (a simple and powerful plain text markup) in Vim.

In Short, It can be your Personal Wiki, Also can be your Document Writer, Even with your code doc writer.

Riv will help you in the following ways:

  • Make the documents clearer to read and easier to navigate using folding, linking and providing extra syntax highlighting.
  • Enable you to write documents faster through improved indentation and inserting.
  • Easier management of documents through "Project", "File" and "Sphinx" support.
  • Enable you to document things using the "Todo" and "Scratch" features.


Reading and Writing

Vim Improved ;-)

Folding:Improved folding support, which helps overview the structure of a document.
Syntax:Extra syntax highlighting.
Indent:Smarter indentation.
Insert:Faster insertion of text, as well as easier navigation.

reST Documents

Sections:Easily create section titles. Sections are folded by default.
Lists:Auto numbered, auto leveled and auto indented.
Links:Highlight links, jump to link targets, create links.
Table:Auto formatting of tables, as well as commands to create tables.
Publish:Convert rst files to a number of different formats such as pdf, html, xml, latex, odt etc.

Document Managment

Sphinx:Support for Sphinx.
Project:You can group related documents under a central location called a project. Projects allow you to perform actions on all the member files at the same time.
File:Link support for local files in the document.
Scratch:Write notes and diaries.
Todos:Maintain Todo lists.
Helpers:Help work with documents and projects.

Riv in Action


  • Working with Sphinx



Using Vundle

This is the recommended method to install Riv. Using Vundle you can update to the latest Git version of Riv easily.

To manage Riv using Vundle, simply add this line to your .vimrc (after you have properly set up Vundle):

Bundle 'Rykka/riv.vim'

Using downloaded zip/tar.gz file

Just extract the contents of the archive to your .vim directory.


Make sure that your .vim directory is placed before $VIMRUNTIME in the runtimepath option of your .vimrc, otherwise Vim's built-in syntax/indent files will override the ones provided by Riv (for rst files).

By default it is present before $VIMRUNTIME.


Make sure the filetype plugin indent on and syntax on options are present in your .vimrc.


Riv is under active development, so things may change quickly.

You are advised to keep up-to-date.

You can get the latest version at

Related tools

  • Python: Docutils, required for converting reST files to other formats.
  • Python: Pygments, provides syntax highlighting for other formats.
  • Python: Sphinx for Sphinx users.
  • Vim: Syntastic for syntax checking. Requires Docutils.



  • If you are new to Vim, you can get a basic overview of Vim using vimtutor. To use it simply type vimtutor in your shell.
  • To view the quick reference of Vim, use :h quickref.



  • For getting started with Riv, read "QuickStart With Riv". You can also view it using :RivQuickStart in Vim.
  • Detailed instructions for Riv are available at "Instructions". Use :RivInstruction to read the same in Vim.

Todo and Changelog

Current Version

Things that need to be done in the following version.

  • 0.75:
    • #21: Fix section syntax to ignore :: and ...
    • #25: Fix tutor's document path.
    • #27: Add g:riv_default_path ('~/Documents/Riv')
    • #29: noremap for commands.
    • For html filetype, copy image for 'image/figure' directives.

Future Versions

See riv_todo (doc/riv_todo.rst)


See riv_log (doc/riv_log.rst)


The bug tracker for Riv is at You can use it to report bugs and open feature requests. Discussions related to Riv are welcome too.

Common Issues

  • If you get errors with folding in documents, you can try to force reload using :RivTestReload or <C-E>t`.

  • Windows:

    • Converting to other formats may fail.

      This could happen due to Docutils not working correctly with vimrun.exe.

  • Mac OS:

    • Lists don't act as expected.

      This could happen if the <C-Enter> key could not be mapped. Try some other mapping instead.


This project aims to provide better support for working with reStructuredText in Vim.

And there are many things that need to be done.

If you are willing to help improve this project, the following areas need contribution:

  1. Rewrite and merge the quickstart and intro, which could be used in Vim.
  2. A screencast for the quickstart.
  1. Support auto formatting for table with column/row span.

    The code of PATH-TO-Docutils/parsers/rst/tableparser can be referenced.

  2. Support for more plugins of reStructuredText.