`vim-reSTfold` — reST Document Folder 🙏

About This Plugin

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.

Why You Might Want to Use This Plugin

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.

Usage: Signify Fold Levels using Specific Punctuation

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

Rule #1: Only double-bordered headers will be folded

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.

Rule #2: Use these 4 characters for your headings

Use the following characters for the heading levels indicated:
- Level 1: @
- Level 2: #
- Level 3: =
- Level 4: -

(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 zm to open one level of folds, or za to 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.

Usage: Press `<F5>` to Manually Recalculate Folds

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.

Usage: Use `<C-Up>` and `<C-Down>` to Transpose 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>``.

Tip: You Can Beautify Titles When Collapsed

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

Tips: Change `redrawtime` for Very Large Documents

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

Tips: Related supercharged reST plugins

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.

Other note-taking-related plugins

Other note-taking and personal CMS type plugins:

Neorg is an all-encompassing tool based around structured note taking, project and task management, time tracking, slideshows, writing typeset documents and much more.

https://github.com/nvim-neorg/neorg

Installation

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/start

If 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/opt

Clone the project to the desired path:

git clone https://github.com/landonb/vim-reSTfold.git

If you installed to the optional path, tell Vim to load the package:

:packadd! vim-reSTfold

Just once, tell Vim to build the online help:

:Helptags

Then whenever you want to reference the help from Vim, run:

:help vim-reSTfold

License

landonb/vim-reSTfold

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages