jiancheng / riv.vim

Take Notes in rst.

Riv: Take Notes in rst

The Internet is just a world passing around notes in a classroom.

—Jon Stewart

Last Update:	2014-07-12
Version:	0.76

Intro

Riv is short for 'reStructuredText in Vim'.

It is a vim plugin for writing notes with reStructuredText.

Comparion

First things first, Why using this plugin?

There are some other note plugins in vim. (Also org-mode if you are a Emacs fan)

like vimwiki, vim-notes, etc.

In comparition, the most advantage of Riv.vim is it support reStructuredText for your note.

And reStructuredText's syntax are markdown alike, but are more powerful and extensible, support like table, LaTex, ect. (This post have a comparions between them https://gist.github.com/dupuy/1855764)

It's used in many places like Sphinx (www.readthedocs.org) and have many relevent plugins(Pygments, Nikola).

And it's using sofish's typo.css for better preview.

Features

Wiki

Write rst document as a wiki with project and local file support. Also TODO syntax is added.

Editing

Faster typing, easier navigation, clear intending, auto formatting lists/tables etc.

Reading

Improved syntax highlighting and folding support for you to read document in vim more clearly.

Publish

Convert rst files to a number of different formats such as pdf, html, xml, latex, odt etc.

Sphinx

Sphinx syntax support.

Installation

Using Vundle

Recommended, Add this line to your .vimrc (after you have properly set up Vundle):

Bundle 'Rykka/riv.vim'

Downloaded zip/tar.gz file

Extract the contents of the archive to your .vim directory.

Config

You can add projects with g:riv_projects:

let proj1 = { 'path': '~/Dropbox/rst',}
let g:riv_projects = [proj1]

More options see the :RivInstruction

Make sure your .vim directory is before $VIMRUNTIME in runtimepath. By default it IS present before $VIMRUNTIME.

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

Related tools

• Python: InstantRst for preview rst document instantly.
• 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.
• Python: Nikola for static blogging with rst syntax.
• Python: HoverCraft for writing presentation from rst.

Tutorials

You can start with :RivQuickStart.

Here is the Screencast:

• Riv: QuickStart (HD)

Vim newbie

• 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.

reST newbie

• To get a quick overview of reStructuredText, some of the available options are:

  Read "A ReStructuredText Primer". You can use :RivPrimer to open it in Vim. Or, you can read "Quick reStructuredText".

• For a detailed look at reStructuredText's specifications, take a look at "reStructuredText Specification". You can use :RivSpecification to open it in Vim.

• Finally, you can use "reStructuredText cheatsheet" for a quick review. Use :RivCheatSheet to open it in Vim.

Riv

• 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.

Issues

The bug tracker for Riv is at https://github.com/Rykka/riv.vim/issues. You can use it to report bugs and open feature requests. Discussions related to Riv are welcome too.

You can follow my twitter @rykkaf and notice me there too.

Common Issues

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

  Or just :w as it will auto refolding after saving.

• 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.