masukomi / vim-markdown-folding

Fold markdown documents by section.

[ Looking for new maintainer see note at end. ]

This plugin enables folding by section headings in markdown documents.

Features

This plugin adds the ability to fold the following markdown elements:

• Headings and everything under them
• Fenced code blocks

Usage

By default this plugin will use "Stacked" folding which looks like this when everything is folded.

  1 ##    Topmost heading                         [3 lines]---------------------------
  5 ###   Second level heading                    [3 lines]---------------------------
  9 ####  Third level heading                     [3 lines]---------------------------
 13 ####  Another third level heading             [2 lines]---------------------------

You can use "Nested" folding, where folding the "Topmost heading" will also nest all the deeper sections under it.

  1 ##    Topmost heading                         [14 lines]--------------------------

To toggle between the two folding styles use :FoldToggle

If you'd like to have it default to "Nested" folding add this to your ~/.vim/filetype.vim

autocmd FileType markdown set foldexpr=NestedMarkdownFolds()

Installation

After installing markdown-folding using a Vim package manager ( vim-plug, pathogen, Vundle, or Vim 8's native plugin system ). You will need to add the following lines to your ~/.vimrc file or ~/.config/nvim/init.vim for NeoVim:

    set nocompatible
    if has("autocmd")
      filetype plugin indent on
    endif

The markdown-folding plugin provides nothing more than a foldexpr for markdown files. If you want syntax highlighting and other niceties, then go and get tpope's vim-markdown plugin.

Troubleshooting

First, Vim must recognize the file you are in as a Markdown file. set filetype? should return filetype=markdown. If it doesn't you may want to tweak your filetype.vim to make sure it knows to associate your current file extension with Markdown. In the short term you can :set filetype=markdown

There are a variety of ways Vim can be instructed to "fold" things. When you add a plugin to support a new language / format the plugin will tell Vim "Hey here's the method to use for figuring out the start and end of a fold with this language". This plugin uses a foldmethod of expr. Running :set foldmethod? should return foldmethod=expr. If you see something else then you've likely got some other Vim configuration overriding the setting in the plugin. If, after running :set foldmethod=expr, things still aren't working, then something is most likely amiss in your ~/.vimrc (or ~/.config/nvim/init.vim if you use NeoVim).

Contributing

PRs are always a welcome thing, but it should be noted that the current intent is to keep this plugin pretty focused on folding Markdown.

All new PRs should include tests. If you're fixing a bug please add a test to make sure it never comes back. If you're adding a new feature please add tests to make sure we never break it with future changes.

The tests are currently all contained in t/folding.vim

Running Tests

The test setup requires Ruby. For those unfamiliar with Ruby development you'll want to cd into the vim-markdown-folding directory and run the following commands in the terminal.

Install bundler if you don't have it already.

gem install bundler

Tell bundler to install the required dependencies

bundle install

Tell bundler to run the tests

bundle exec rake test

The end of the output should look something like this

t/folding.vim .. ok
All tests successful.
Files=1, Tests=41,  1 wallclock secs ( 0.03 usr  0.01 sys +  0.57 cusr  0.12 csys =  0.73 CPU)
Result: PASS

License

Created by Drew Neil. Copyright Drew Niel and all the contributors. Distributed under the same terms as Vim itself. See :help license.

With community improvements by:

• Aaron O'Leary
• masukomi
• Pierrick Roger
• thawk

Maintained by masukomi

Looking for New Maintainer

This works fine, but there are improvements that can be made, and PRs that need addressing. If you've familiar with vim-script and have some vim-script stuff you can point at, gimme a holler @[email protected] on mastodon or @masukomi on twitter. I use Doom Emacs these days so vim-script isn't where my head is.

vim-markdown-folding's Issues

Setup indentexpr?

I came across vim-markdown once again.

When looking into issues (preservim/vim-markdown#126) with its indent expression (https://github.com/plasticboy/vim-markdown/blob/master/indent/mkd.vim), I've wondered if vim-markdown-folding couldn't also provide this, given that it knows a lot about sections already?

markdown folding not working if I open a non-markdown file first

I'm using MacVim 8.2.261. I have installed folding.vim so that it is found by vim. (vim 8 packages) I have verified that it is found by running :scriptnames. I have verified that foldmethod=expr.

If I choose to edit a markdown file first thing on opening vim, it folds properly - it opens in a completely folded state and I can open and close the folds as expected using the vim keys.

However, if I open .vimrc first (for instance) and then open a markdown file, it opens completely unfolded and fold command are ignored.

I have discovered, though, that if I source folding.vim after that, then folding works again.

I'm reasonably certain I have set everything up as stated in the GitHub site. Do you have any idea what might be going on?

Folding breaks on particular .md file

Hi! I just encountered a problem when folding, if I have the following markdown
in a file:

# First

```
1
2
3
4
5

7
```

first

* first
* second
* third

# Second

second

Then when I close the fold it 'eats' the second heading. So it goes from

to

Let me know if you can reproduce it. I tried only loading this plugin but
the issue persists. I'm using nvim if that helps.

NVIM v0.4.3
Build type: RelWithDebInfo
LuaJIT 2.0.5
Compilation: /usr/bin/gcc-5 -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=1 -O2 -g -DMIN_LOG_LEVEL=3 -Og -g -Wall -Wextra -pedantic -Wno-unused-parameter -Wstrict-prototypes -std=gnu99 -Wshadow -Wconversion -Wmissing-prototypes -Wvla -fstack-protector-strong -fdiagnostics-color=auto -DINCLUDE_GENERATED_DECLARATIONS -D_GNU_SOURCE -DNVIM_MSGPACK_HAS_FLOAT32 -DNVIM_UNIBI_HAS_VAR_FROM -I/home/travis/build/neovim/bot-ci/build/neovim/build/config -I/home/travis/build/neovim/bot-ci/build/neovim/src -I/home/travis/build/neovim/bot-ci/build/neovim/.deps/usr/include -I/usr/include -I/home/travis/build/neovim/bot-ci/build/neovim/build/src/nvim/auto -I/home/travis/build/neovim/bot-ci/build/neovim/build/include
Compiled by travis@travis-job-9a287301-34f2-4b86-92e3-462594f51f36

Features: +acl +iconv +tui
See ":help feature-compile"

   system vimrc file: "$VIM/sysinit.vim"
  fall-back for $VIM: "/home/travis/build/neovim/bot-ci/build/neovim/build/nvim.AppDir/usr/share/nvim"

Run :checkhealth for more info

how to fold

it's not clear from the readme if this uses vim default controls for folding:

• zf for fold
• zo for open
• zc for close

can anyone shed some light?

GitHub style code blocks break folding

I mostly use markdown with a lot of the GitHub style code blocks:
https://help.github.com/articles/github-flavored-markdown#syntax-highlighting

E.g.:

```
code here
```

but these appear to break the way this plugin folds the headings.

Here's some screen shot examples...

The file contents that breaks folding:

How the plugin does the folding:

What I'd expect:

Want to just fold the fenced code

I'm looking for a way to just fold up the fenced code blocks, i.e. without folding any of the heading levels. The use case for this is for adding emphasis for various strings in paragraphs, but not when they occur in fenced code. I known that there is a way to limit searches to text outside of folds, so being able to fold just the fenced code should let me do what I need.

None of the markdown folding available seems to do this, and most are way too complex to try to hack into, yours looks simple enough that I might have a chance to add this in.

Enjoyed your class by the way.

Stacked folding - content does not fold into the heading

I am having trouble getting Stacked Folding to work correctly.

Here is a sample doc:

## Heading 1
This is the content for my first heading.
 
## Heading 2
This is the content for my second heading.

When I fold it, this is what I get. Notice the content under each heading appears on its own line:

##   Heading 1
                       [3 lines]---------------------------
##   Heading 2
                       [3 lines]---------------------------

But, this is what I want (and what Masukomi's readme says the stacked folds should look like):

##  Heading 1                   [3 lines]---------------------------
## Heading 2                    [3 lines]---------------------------

How can I get my stacked folds to look like this?

Lines inside fenced code blocks that start with an octothorpe are interpreted as headers and break folding

This looks very much along the lines of #1. Possibly related to #6 also (but I kinda doubt it).

Using vim-markdown-folding with vim-plug, on 3f35acf. I'm observing a problem when editing this file I'm working on.

Looks like this:

#     Pre-OS prep                             [17 lines]-----------------------------------------------------------------------------------
##    Installation media                      [13 lines]-----------------------------------------------------------------------------------
##    Create partitions                       [4 lines]------------------------------------------------------------------------------------
#     gdisk /dev/nvme0n1                      [7 lines]------------------------------------------------------------------------------------
##    Create LUKS container                   [4 lines]------------------------------------------------------------------------------------
#     cryptsetup luksFormat --type luks1 --use-random --hash whirlpool --iter-time 5000 /dev/nvme0n1p2 [4 lines]---------------------------
##    O/S Filesystem                          [7 lines]------------------------------------------------------------------------------------
###   Create and mount LVM volumes            [6 lines]------------------------------------------------------------------------------------
# vgcreate volgroup0 /dev/mapper/cryptlvm
# lvcreate volgroup0 -L 32G -n lvswap
#     lvcreate volgroup0 -l 100%FREE -n lvroot [5 lines]-----------------------------------------------------------------------------------
###   Create btrfs filesystem                 [4 lines]------------------------------------------------------------------------------------
# mkfs.btrfs -L root /dev/volgroup0/lvroot
# mkswap -L swap /dev/volgroup0/lvswap
#     swapon -L swap                          [56 lines]-----------------------------------------------------------------------------------
##    O/S                                     [4 lines]------------------------------------------------------------------------------------

I would expect something more like this (maybe with different counts of folded lines):

#     Pre-OS prep                             [17 lines]-----------------------------------------------------------------------------------
##    Installation media                      [13 lines]-----------------------------------------------------------------------------------
##    Create partitions                       [4 lines]------------------------------------------------------------------------------------
##    Create LUKS container                   [4 lines]------------------------------------------------------------------------------------
##    O/S Filesystem                          [7 lines]------------------------------------------------------------------------------------
###   Create and mount LVM volumes            [6 lines]------------------------------------------------------------------------------------
###   Create btrfs filesystem                 [4 lines]------------------------------------------------------------------------------------
##    O/S                                     [4 lines]------------------------------------------------------------------------------------

Unsolicited folds in fenced code blocks

Hi, thanks for the great plugin!
I have noticed that it does not treat fenced code blocks properly though. Consider the following document:

# Minimal C++ program

Here is a minimal C++ program which prints "Hello world!":

```cpp
#include <iostream>
void main()
{
  std::cout << "Hello world!";
}
```

The plugin treats #include directive as a section header and produces two folds:

1 # Minimal C++ program [4 lines]------------------------------------------
6 # include <iostream> [5 lines]-------------------------------------------

Python's metadata extension breaks vim-folding

The python markdown extension supports YAML-like frontmatter for storing meta-data in markdown documents (ref). I just encountered this with pelican, which unfortunately doesn't support YAML frontmatter (which vim-markdown-folding does seem to work with).

Having the metadata tags at the start of the document is just like YAML, but without the dashes:

Title: Dangit
slug: vim-markdown-folding-is-awesome
Date: 2015-02-10
Author: @nfarrar

## It broke
:(

Any chance it'd be possible to add support? It is the primary python markdown library. :)

EDIT: I did finally get YAML frontmatter implimented and after using it for a bit - I realized that while it doesn't completely break vim-markdown-folding, it creates a fold in the middle of the YAML front matter. For example:

---
Title:    Its Going Down
Date:     2015-02-10
Status:   Published

---

will fold to:

---
Title:    Its Going Down
Date:     2015-02-10
## Status:   Published [# lines] ---------------------------------------

Slow when syntax is off

The plugin adds more than 2000ms to start up when syntax if off. This, I believe, is due to the lineisfenced() function that uses an `hassurroundingmarks()' that has slow regex parsing (well, slower than the syntax highlighter).

fold fenced latex blocks

I think that the way of indicating latex blocks in markdown can vary depending on what you're interpretting it with, but I run mine through a jekyll plugin and they are deliminated with two dollar signs like so:

$$
\text{latex goes here!}
e^{i\pi}=-1
$$

would be great if folding these blocks was supported, pretty much the same deal as fenced code blocks!

Add support for info headers

@nelstrom Lately static site generators have gotten into using a header inside a Markdown file to give the static site generator the file's metadata.

So something like this:

---
title: Contact
layout: page
headline: Contact
subHeadline: Drop me a line or two
menuShow: true
isPage: true
menuOrder: 2

---

Of course this causes problems with this plugin, where it thinks the last line is a header.

You think you could fix this because it's a little bit annoying. :)

Undefined variable: b:undo_ftplugin

This error displays at bottom of gVim when I open a markdown file:
Error detected while processing C:\Users\wolf\vimfiles\bundle\vim-markdown-folding\after\ftplugin\markdown\folding.vim
line:20
E121: Undefined variable: b:undo_ftplugin
E121: Undefined variable: b:undo_ftplugin

I press Enter to continue and folding works fine.
I am running Vim 7.4 with Vundle on Windows 7.
This is in my _vimrc file:

set nocompatible
if has("autocmd")
filetype plugin indent on
endif
Plugin 'nelstrom/vim-markdown-folding'

E184: No such user-defined command: FoldToggle

I'm getting the following error when I open a markdown file:

Error detected while processing function <SNR>11_LoadFTPlugin:
line    4:
E184: No such user-defined command: FoldToggle 

I can reproduce the error reliably with my standard configuration, but the circumstances in which it occurs seem to be complicated: it occurs when a BufRead autocommand opens and modifies the contents of a scratch window, but so far I haven't managed to create a smaller test config that still displays the bug. Also, weirdly, the error first appeared immediately after I moved all my plugins from /bundle into /pack/bundle/start (with no other changes made).

Having done some debugging, I can see that shortly before the error is displayed, the value for b:undo_ftplugin is set incorrectly—note the repetition of the final line, which is the immediate cause of the error:

setlocal commentstring< matchpairs< omnifunc< comments< formatoptions<
| unlet! b:match_ignorecase b:match_skip b:match_words b:browsefilter
|setl cms< com< fo< flp< 
| setlocal foldmethod< foldtext< foldexpr< | delcommand FoldToggle  
| setlocal foldmethod< foldtext< foldexpr< | delcommand FoldToggle

(linebreaks added for clarity)

This issue is therefore related to issue 15. Fixing that by replacing .= with = as you suggest would also fix this, but the root cause would still be unknown, and you'd also be blowing away the existing value, which may not be desired.

Less greedy fold?

Hi and thank you for this plugin which worked out-of-the-box! :)

How hard would it be to prevent blank lines before sections to be folded? For instance, in:

1.     # Section 1
2.  
3.     ## Subsection A
4.  
5.     Here is a
6.     long
7.     long
8.     text, uh?
9.  
10.    ## Subsection B
11.
12.    Here is
13.    another one
14.
15.
16.
17.    # Section 2
18.
19.    Here is my conclusion 

.. I would like line 9. not to be folded with A, and 14. 15. 16. not to be folded with B nor 1. In this fashion, When everything is folded, we would still see the vertical white space between the sections.

SimpylFold, which folds python code based on (mostly) indentation, works this way.

This could be optional of course ;)

Option to turn of folding for headline tags mark with ---

Hi Drew I really love your plugin and I'm using it on my daily basis for writing articles in markdown. Since I'm using Jekyll for running my blog, I'm also using the YAML settings at the beginning of each markdown file.

---
layout: post
title: here goes the article of a new post
meta-description: <---- Here begins the first fold level because of the special headline marks 

---


## The kitchen timer <-- here should be the first level of the folding level

...

If you have problems with following the example above, please consult the example below:

  1 ---
  2 layout: post
  3 title: On My Way On Becoming a Self-Certified Pomodoro Master
  4 ## meta-description: Motivation for the ongoing series of becoming a Self-Certiefied Pomodoro Master [12 lines]-----------
 17 ## Why? [22 lines]--------------------------------------------------------------------------------------------------------
 40 ## The First Pomodoro [36 lines]------------------------------------------------------------------------------------------
 77 ## Following the six objectives [17 lines]--------------------------------------------------------------------------------
 95 ## Conclusion [9 lines]---------------------------------------------------------------------------------------------------

Cheers

Matthias

Mention in the readme that overriding user's foldtext is a configurable option

I was frustrated to see that this plugin set the foldtext on behalf of the user (not expected since the readme says this plugin only consists of fold expressions) but after a quick look at the source was pleased to see that an option exists to disable this functionality - it would probably save some confusion for others if this behaviour, and the option itself was mentioned in the readme.

the option is:
let g:markdown_fold_override_foldtext=0

Folds open on save

Is there any way to prevent the folds to open on save?

Incompatibility with plasticboy/vim-markdown

vim-markdown requires filetype=mkd. I believe this plugin requires filetype=markdown. Is there a way to change the filetype that markdown-folding is looking for?

Stacked folding - content does not fold into the heading

I am having trouble getting Stacked Folding to work correctly.

Here is a sample doc:

## Heading 1
This is the content for my first heading.
 
## Heading 2
This is the content for my second heading.

When I fold it, this is what I get. Notice the content under each heading appears on its own line:

##   Heading 1
                       [3 lines]---------------------------
##   Heading 2
                       [3 lines]---------------------------

But, this is what I want (and what Masukomi's readme says the stacked folds should look like):

##  Heading 1                   [3 lines]---------------------------
## Heading 2                    [3 lines]---------------------------
```

How can I get my stacked folds to look like this? 

Stacked folding - content does not fold into the heading

I am having trouble getting Stacked Folding to work correctly.

Here is a sample doc:

## Heading 1
This is the content for my first heading.
 
## Heading 2
This is the content for my second heading.

When I fold it, this is what I get. Notice the content under each heading appears on its own line:

## Heading 1
                       [3 lines]---------------------------
## Heading 2
                       [3 lines]---------------------------

But, this is what I want (and what Masukomi's readme says the stacked folds should look like):

## Heading 1                   [3 lines]---------------------------
## Heading 2                   [3 lines]---------------------------

How can I get my stacked folds to look like this?

Folded heading text not showing in latest vim 8.2 version

I created a simple markdown file to show the differences between vim versions.
test.md:

# Section 1

a

# Section 2

b

Old vim - version

:version
VIM - Vi IMproved 8.2 (2019 Dec 12, compiled Jun 21 2020 16:11:23)
Included patches: 1-814
Compiled by Arch Linux

Old vim - folded buffer shows heading text properly

  1 #     Section 1                               [3 lines]---------------------------------------------------------
5   #     Section 2                               [2 lines]---------------------------------------------------------

New vim - version

:version
VIM - Vi IMproved 8.2 (2019 Dec 12, compiled Aug 24 2020 19:37:58)
Included patches: 1-1522
Compiled by Arch Linux

New vim - folded buffer doesn't show heading text

  1 +--  4 lines folded --------------------------------------------------------------------------------------------
5   +--  3 lines folded --------------------------------------------------------------------------------------------

Hopefully this is an easy fix. Thanks!

:FoldToggle folding not working

For some reason markdown folding is not working. I have installed the plugin bundle via bundle but my markdown file does not fold. I have the following plugins installed:

vim-flavored-markdown;
vim-markdown-preview
vim-marked; and
vim-markdown-folding

Could these be conflicting in some way?

Many Thanks

Paul

add support for lists

this commit by @lucponnau shows a possible solution for supporting bullet lists but doesn't account for the fact that you can also make a bullet list with - (not just *) or that you can nest lists. Then there's the handling of <number>. lists (e.g. 1.)

We should

• be able to fold lists of all types
• be able to fold nested lists separately from their parents.

Nesting of header levels?

Consider the following document:

# H1

stuff

## H2

stuff

### H3

stuff

Currently I get these folds:

# H1 [3 lines]
## H2 [3 lines]
### H3 [2 lines]

But I really want nested folds:

# H1 [8 lines]

Expanded:

# H1

stuff

## H2 [5 lines]

Etc.

Thoughts?

E121: Undefined variable: b:undo_ftplugin

I get the following whenever I edit a markdown file:

Error detected while processing /home/John/dotfiles/.vim/bundle/vim-markdown-folding/after/ftplugin/markdown/folding.vim:
line  121:
E121: Undefined variable: b:undo_ftplugin

Might I suggest that you check if b:undo_ftplugin exists before appending to it ?

The following fixes the problem for me:

--- folding.vim.old     2014-11-24 11:38:31.562848600 +0000
+++ folding.vim 2014-11-24 11:38:43.174823200 +0000
@@ -114,6 +114,7 @@
   \ : 'StackedMarkdownFolds()'

 " Teardown {{{1
+if !exists("b:undo_ftplugin") | let b:undo_ftplugin = '' | endif
 let b:undo_ftplugin .= '
   \ | setlocal foldmethod< foldtext< foldexpr<
   \ | delcommand FoldToggle

folded areas should not print

When printing from vim (i know, i know, nobody prints, BUT), when there are regions folded and hence hidden, it's unexpected that printing the file should show the folded regions to unfold and appear again.

Any suggestions on how to tackle this in a PR?

Add support for markdown variants such as API Blueprint

:set filetype=markdown may be a workaround, but I wonder if there is a better way to do that.

vspec test runner doesn't conform to recommended style

Follow this guide. Need vim-markdown to tag a release so that this plugin can depend on it.

Folds open when adding dashed list items

When adding a new row to a dashed list, the sibling folds of the current fold open. I would expect folds to stay unchanged.

Here's a demo: https://www.loom.com/share/61c7cb4af99d46bf991322bd202db109. In the demo I'm just adding a new row (starting with o to add a new line, then just typing - hi).

Does anyone else have this problem or know how I can address it? Possibly it's interference with something else in my vimrc.

Here's the sample text from that demo:

# Level 0

## level 1

### level 2

lorem ipsum
- asdf
- hi

### more stuff

lorem ipsum

### more stuff

lorem ipsum

Clarify that `foldmethod` must be `expr`

Perhaps this is just obvious to others, but I wasted a bunch of time trying to get this plugin to work with foldmethod=syntax. Setting foldmethod=expr fixed my issue. I'm not deeply familiar with the inner workings/best practices of vimscript, but it might help other noobs like me :-)