reStructuredText ftplugin : Navigation and section handling for reStructuredText
| script karma
Downloaded by 233
Comments, bugs, improvements
script versions (upload new version)
|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.
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
[[ - 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
4. Adding Sections *rst-add*
<LocalLeader>o - add a sibling above/below current section
<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>> - promote/demote current section making it one level higher or
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: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.
Also available from https://bitbucket.org/khorser/vim-rst-ftplugin and https://github.com/khorser/vim-rst-ftplugin
Click on the package to download.
ip used for rating: 22.214.171.124