Riv: reStructuredText in Vim

Author: Rykka G.F
Version: 0.75


Riv, short for 'reStructuredText in Vim'.

Aim to provide better support of reStructuredText (a simple and powerful plain text markup) in vim.

It's for you to:

Read documents clearer. (Folding, Linking and Extra highlight)
Write documents faster. (Indent and Insert improvement)
Manage documents easier. (Project,File and Sphinx support)
Make things documented. (Todo and Scratch)


Reading and Writing

Vim Improved

Folding:Overview the structure.
Syntax:Extra highlighting.
Indent:Smarter indent.
Insert:Speed up the input!

RST Documents

Sections:Easy create, easy view.
Lists:Auto numbered, auto leveled and auto indented.
Links:Jumping and Highlighting.
Table:Auto formatted.
Publish:Convert to html/xml/latex/odt...

Document Managment

Sphinx:Working with Sphinx.
Project:A workspace for your documents.
File:Link local file in the document.
Scratch:Writing notes and diaries.
Helpers:Help work with document/project.
Todos:Keep track of todo things.

On Screen

ScreenShot: Work with Sphinx



Where To Go

  • Index : Index of Document

Gettings Start

About This Projcet


  • Using Vundle (Recommended)

    Add this line to your vimrc:

    Bundle 'Rykka/riv.vim'
  • Using downloaded zip/tar.gz file. Just extract it to your .vim folder .


Make sure your .vim folder in option runtimepath is before the $VIMRUNTIME, otherwise the syntax/indent files for rst files will use vim's built-in one.

Default is before $VIMRUNTIME.


Make sure filetype plugin indent on and syntax on is in your vimrc


It's a developing version. So things may change quickly.

Keep up-to-date.

You can get the latest version at https://github.com/Rykka/riv.vim

  • Related tools:

    • python: docutils , required for converting to other format.

    • python: pygments for syntax highlighting in other format.

    • python: Sphinx for Sphinx users.

    • vim: Syntastic for syntax checking. docutils required.

      But if you are using Sphinx's tools set, you'd better not using it. Cause it could not recognize the sphinx's markups.



  • To get a tutor for vim. Use vimtutor in your shell.
  • To view the quick reference of vim. Use :h quickref.



  • Quick Start With Riv.

    Read QuickStart With Riv , Use :RivQuickStart in vim.

  • Detailed Instruction for Riv:

    Read Instructions , Use :RivInstruction in vim.

Todo and Done


Things todo in this version.

  • 0.75:
    • #21: Fix section syntax to ignore '::' and '..'.
    • #25: Fix tutor's document path.
    • #27: Add g:riv_default_path ('~/Documents/Riv')


See riv_todo (doc/riv_todo.rst)


See riv_log (doc/riv_log.rst)


  • If the document folding showing some error. You can try force reload :RivTestReload <C-E>t`

  • Windows:

    • Converting to other format may fail.

      This may due to docutils could not executing correctly with vimrun.exe.

  • Mac OS:

    • The List don't act as expected.

      Maybe Caused the <C-Enter> Could not be mapped. Use other map instead.

  • Post issues at https://github.com/Rykka/riv.vim/issues Both bug reports and feature request and discussions are welcome.


This project aims to provide better working with reStructuredText in vim.

And there are many things need to do.

If you are willing to improve this project, You can do something for it.

  1. This README document need review and rewrite. It is also the helpdoc in vim.
  2. Rewrite and merge the quickstart and quick intro. Which could be used in vim.
  3. A screencast for 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 more other plugins of reStructuredText