This plugin adds advanced reST document section folding.
Supercharge your notetaking and recordkeeping!
Install this plugin to make it easier to manage notes in Vim using reStructuredText markup.
If you like to use Vim to organize your life (I do!), see how this plugin makes it easier to manage your notes.
Consider the following document:
@@@@@@@@@@@@@@ reSTfold Notes @@@@@@@@@@@@@@ #################################### FIXME: Update reSTfold plugin README #################################### 2021-07-12 21:39: Update reSTfold README with latest enhancements. ####################################################### MAYBE: Publish Medium article to promote reSTfold usage ####################################################### 2021-07-13 12:04: Get some claps. - Research what makes a good tech article. - Devise a better example than this readme. - Find a copy editor to review your work. ###################### NOTES: Some more notes ###################### Foo bar baz bat.
This plugin lets you fold the reST headers, collapsing everything into essentially a high-level Table of Contents. You can then open individual sections to read or work on their contents.
E.g., press <F5> to collapse all folds, and Vim will show:
1 @@@@@@@@@@@@@@ 2 reSTfold Notes 3 @@@@@@@@@@@@@@ 4 5 ┌─ FIXME: Update reSTfold plugin README ──┤ 6 ll. ├─ 11 ├─ MAYBE: Publish Medium article to promote reSTfold usage ──┤ 8 ll. ├─ 19 └─ NOTES: Some more notes ──┤ 6 ll. ├─
You can then use the normal Vim fold commands to open and close folds.
For example, position the cursor over a fold title and type za to open it.
Generally, reST lets you choose any delimiters (ASCII punctuation) to use for the different heading levels, and the reST parser will infer the levels from their usage order within the document.
You indicate a heading by underlining with the same punctuation character. The reST specification also lets you add an overline.
For instance, both of these documents render the same:
Document 1:
Level 1 Heading ############### =============== Level 2 Heading ===============
and Document 2:
=============== Level 1 Heading =============== Level 2 Heading ---------------
But this plugin is not as flexible.
To use vim-reSTfold, you'll need to follow a few guidelines.
(These rules make the plugin less complex, and probably faster.)
Use a double-bordered reST heading for sections you want folded.
E.g., this header with both an overscore and an underscore will be folded:
########################### This Section Will Be Folded ###########################
but this header, with only an underscore, will not be folded:
This Section Will Not Be Folded ###############################
Use an underline and overline around the heading for each section you want folded.
- Use the following characters for the heading levels indicated:
- Level 1:
@ - Level 2:
# - Level 3:
= - Level 4:
-
- Level 1:
(Note that characters used for the higher levels use more pixels per character than those in lower levels. So, visually, higher level headings appear darker.)
Note that each document must only have one Level 1 heading, at the top.
This section is never folded.
Use the normal Vim fold commands to open and close folds.
E.g., type
zr(in Normal mode) to collapse one level of folds.Or type
zmto open one level of folds, orzato toggle the current fold open and closed.As an example, this document has two Level 2 sections:
@@@@@@@@@@@@@@ Document Title @@@@@@@@@@@@@@ ############### Level 2 Section ############### =============== Level 3 Section =============== ####################### Another Level 2 Section ####################### ======================= Another Level 3 Section ======================= Another Level 3 section, but ignored by folder ============================================== -------------------------- A Foldable Level 4 Section --------------------------
Use the 4 characters (@, #, =, and -) to signify the different heading levels.
By default, Vim enables reST folding.
But this can cause performance issues, e.g., every time you insert or remove a character from a buffer, Vim has to recalculate folds.
To prevent performance issues, the user must explicitly generate folds.
Press <F5> to generate (and collapse all) folds.
In normal mode, with the cursor over a folded reST section,
press <Ctrl-Up> to swap the fold under the cursor with the
fold under the line above the cursor; press <Ctrl-Down> to
swap with the fold on the line following the current fold.
Swap reST Sections (Transpose Folds) using ``<C-Up>`` and ``<C-Down>``.
The reST section title that's sandwiched between the section delimiter lines is used for the folded view title.
Because of this, you can design section titles that look good folded, too.
For instance, consider the following, unfolded document:
@@@@@ NOTES @@@@@ ########################################################### ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ########################################################### ########################################################### ┣━━ // * TABLE_OF_CONTENTS * // ━━━━━━━━━━━━━━━━━━━━━━━━━━┨ ########################################################### ########################################################### ┃ ┏━━━━━━━━━━━━━┓ ┃ ########################################################### ########################################################### ┃ ┃ ☼ FOO BAR ☼ ┃ ┃ ########################################################### ########################################################### ┃ ┏━┻━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ ########################################################### ########################################################### ┃ ┃ SECTION X: Blah blah blah ┃ ┃ ########################################################### Blah blah blah ########################################################### ┃ ┃ SECTION Y: Blasé blasé blasé ┃ ┃ ########################################################### Blasé blasé blasé ########################################################### ┃ ┃ SECTION Z: Patati Patata ┃ ┃ ########################################################### Patati Patata ########################################################### ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ┃ ########################################################### ########################################################### ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ###########################################################
Once folded (e.g., press <F5>), it'll look like this:
1 @@@@@ 2 NOTES 3 @@@@@ 4 5 │ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ │ 4 ll. │ 9 │ ┣━━ // * TABLE_OF_CONTENTS * // ━━━━━━━━━━━━━━━━━━━━━━━━━━┨ │ 4 ll. │ 13 │ ┃ ┏━━━━━━━━━━━━━┓ ┃ │ 4 ll. │ 17 │ ┃ ┃ ☼ FOO BAR ☼ ┃ ┃ │ 4 ll. │ 21 │ ┃ ┏━┻━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ │ 4 ll. │ 25 ├─ ┃ ┃ SECTION X: Blah blah blah ┃ ┃ ──┤ 6 ll. ├─ 31 ├─ ┃ ┃ SECTION Y: Blasé blasé blasé ┃ ┃ ──┤ 6 ll. ├─ 37 ├─ ┃ ┃ SECTION Z: Patati Patata ┃ ┃ ──┤ 6 ll. ├─ 43 │ ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ┃ │ 4 ll. │ 47 │ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ │ 4 ll. │
Vim's default redrawtime (:echo &rdt) is "2000", or 2 seconds.
If Vim runs longer than this during syntax matching, it cancels the operation and logs the message, "'redrawtime' exceeded, syntax highlighting disabled".
You can set this value larger to tell Vim to run the parser longer,
e.g., :set redrawtime=10000, or, better yet, you can add a modeline
(such as one read by https://github.com/landonb/dubs_style_guard)
to any reST document that needs extra parsing time. E.g., at the top
of a reST document, you could add:
.. vim:rdt=10000
Consider these complementary reST highlights plugins that pair well with this plugin to help you take notes in Vim:
Additional syntax highlight rules.
https://github.com/landonb/vim-reST-highdefs#🎨
Colorize email addresses and host names, and disable spell checking on emails, hosts, and acronyms (all-capital words).
Special so-called FIVER syntax rules.
https://github.com/landonb/vim-reST-highfive#🖐
Highlight action words.
E.g., "FIXME" is emphasized (in bright, bold yellow), and so is "FIXED" (crossed-out and purple), and so are "MAYBE", "LEARN", "ORDER", and "CHORE", and a few other choice five-letter words.
Why five letters? So that you can use action words in section headers, and then the heading titles align nicely when folded. (Really, it's only important that each action word is the same width, and not necessarily that it's five long — but FIXME is the ultimate developer action word, so might as well be five.)
Simple horizontal rule highlight.
https://github.com/landonb/vim-reST-highline#➖
Repeat the same punctuation character 8 or more times on a line, and it'll be highlighted.
Useful for adding a visual separation to your notes without using a reST section heading.
Installation is easy using the packages feature (see :help packages).
To install the package so that it will automatically load on Vim startup,
use a start directory, e.g.,
mkdir -p ~/.vim/pack/landonb/start
cd ~/.vim/pack/landonb/startIf you want to test the package first, make it optional instead
(see :help pack-add):
mkdir -p ~/.vim/pack/landonb/opt
cd ~/.vim/pack/landonb/optClone the project to the desired path:
git clone https://github.com/landonb/vim-reSTfold.gitIf you installed to the optional path, tell Vim to load the package:
:packadd! vim-reSTfoldJust once, tell Vim to build the online help:
:HelptagsThen whenever you want to reference the help from Vim, run:
:help vim-reSTfold