sponsor Vim development Vim logo Vim Book Ad

reStructuredText ftplugin : Navigation and section handling for reStructuredText

 script karma  Rating 0/0, Downloaded by 887  Comments, bugs, improvements  Vim wiki

created by
Sergey Khorev
 
script type
ftplugin
 
description
This is a lightweight filetype plugin for reStructuredText files.
It features folding, navigation, and simple operations to manage sections.

1. Folding *rst-folding*

The functionality of the plugin heavily depends on |folding| enabled
(|'foldexpr'| is utilised to continuously inspect and cache definitions of
section decorations). As an extra bonus, folding allows you easily examine
the structure of the document.

If you prefer not to have any text folded set g:rst_fold_level or
b:rst_fold_level variable in your |vimrc| to a substantially high value like 100.

*:RstReset*
I tried to reach a compromise between correctness and performance so the
plugin relies on Vim to be notified on relevant changes. Section adornment
styles are cached internally so if you see something messed up, use :RstReset
command to reinitialise internal plugin structures and parse text from scratch.

2. Navigating Sections *rst-navigation*

The plugin overrides and enriches Vim standard navigation keys:

]] - go forward to the start of the next sibling section

<N>]] - search for the start of the next section which is N levels above the
current section

[[ - go backward to the start of the section. If the cursor is already at
the start, go upwards to the next sibling section.

<N>[[ - go up to the start of the parent section level N (in other words, 2[[
will navigate to the grandparent of the current section)

][ - search forward to the end of the current section or, if the cursors is
there already, its prior sibling

<N>][ - same as ][ but go to the end of the parent section which is N levels
above the current section.

[] - search backward to the end of the previous sibling

<N>[] - same as [] but look for the parent N levels above

3. Navigating References *rst-references*

The plugin also creates normal mode mappings to follow references (section
names, citations, substitutions, hyperlinks)

<LocalLeader>CTRL-] tries to follow a link under the cursor.
<LocalLeader>] can be used to search for another matching target for last
processed reference. Default value for <LocalLeader> is backslash.

NOTE To avoid full-scale parsing, the plugin uses groups defined in rst |syntax|
highliting plugin shipped with Vim.

Also it is able to use some simple heuristics, the behaviour can be tuned via
g:rstsearch_order variable.

4. Adding Sections     *rst-add*

<LocalLeader>O
<LocalLeader>o - add a sibling above/below current section

<LocalLeader>A
<LocalLeader>a - add a first/last child for the current section. If the plugin
has not seen any adornments of this level, it invents one on its own.

See also |LocalLeader|

5. Modifying sections     *rst-modify*

<LocalLeader><
<LocalLeader>> - promote/demote current section making it one level higher or
lower

6. Customisation     *rst-customise*

The behaviour of the plugin can be customised through the following global
variables, please see ftplugin/rst.vim for details: >

    g:rsttitle_marks

    g:rstfolding_alltitles

    g:rstfolding_rxtitle
    g:rstfolding_rxprintable
    g:rstfolding_rxempty

    g:rstfolding_rxtext

    g:rstnav_rx

    g:rstsearch_order - the list of methods used to follow links. Valid
    entries are 'syntax', 'heuristics', 'user'. In the latter case you need to
    define function g:RstUserSearch.
 
install details
:so ft_rst.vmb

Also available from https://bitbucket.org/khorser/vim-rst-ftplugin and https://github.com/khorser/vim-rst-ftplugin
 

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
ft_rst.vmb 1.0 2012-12-12 7.3 Sergey Khorev Initial upload
ip used for rating: 18.97.14.85

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
   
Vim at Github