shushcat / vim-minimd

A fast, folding Markdown outliner for Vim

minimd

Minimd is a Vim plugin that helps with writing long Markdown documents by folding sections and showing outlines of their contents.

The basic idea is that pressing spacebar on an unfolded level 1 header will fold that header, while pressing spacebar on a folded level 1 header will both unfold it and fold all the level 2 headers it contains. If you fold then unfold a level 3 header, any level 4 headers are folded, and so on. Pressing a number followed by the spacebar folds all headers of that number, which is an outline.

Minimd also has a few other features to make working with long documents easier:

• Header motion command that ignore code blocks (so don't mistake # comments for headers);
• Minimal syntax highlighting (headers, code blocks, square brackets, checkboxes, and the task markers ACTV, TODO, WAIT, CNCL, and DONE) so as not to be too distracting and to speed up the folding a bit
• Shortcuts to simultaneously change the levels of all headers within a fold

Demonstration

Usage

Normal Mode Key	Action
Space	Fold or unfold the current header.
nSpace	Fold all headers of level n.
Tab or ]h	Jump to next header.
nTab or n]h	Jump to next header of level n.
Shift-Tab or [h	Jump to previous header.
nShift-Tab or n[h	Jump to previous header of level n.
=	Promote header (# → ##).
-	Demote header (## → #).
Enter	Add and toggle checkboxes in lists
	(- → - [ ] → - [x] → - [ ]).

The header promotion and demotion commands act on all enclosed headers when invoked on a fold.

As always in Vim, you can execute any command from Insert mode by prefixing it with Ctrl-o; so, for example, you would toggle a checkbox without leaving Insert mode by typing Ctrl-o followed by Enter. For more on executing Normal mode commands from Insert mode, consult :help i_CTRL-o.

Customization

This plugin can be used with Vim's default Markdown syntax by adding the line let g:default_markdown_syntax = 1 to your vimrc.

The default mappings for this plugin's folding, motion, header promotion and demotion, and task toggling commands are as follows.

nmap <silent><buffer> <Space> :<C-u>MiniMDToggleFold<CR>
nmap <silent><buffer> <Tab> :<C-u>MiniMDNext<CR>
nmap <silent><buffer> <S-Tab> :<C-u>MiniMDPrev<CR>
nmap <silent><buffer> ]h :<C-u>MiniMDNext<CR>
nmap <silent><buffer> [h :<C-u>MiniMDPrev<CR>
nnoremap <silent><buffer> = :MiniMDPromote<CR>
nnoremap <silent><buffer> - :MiniMDDemote<CR>
nmap <silent><buffer> <CR> :MiniMDTaskToggle<CR>
vmap <silent><buffer> <CR> :MiniMDTaskToggle<CR>

Note that, according to :help v:count, the mappings for MiniMDToggleFold, MiniMDNext, and MiniMDPrev must be prefixed with <C-u> in order for the functions wrapped by those commands to accept numeric arguments. So if, e.g., you wanted to map the folding command to z, you would add a line like the following to your .vimrc:

nmap z :<C-u>MiniMDToggleFold<CR>

Exporting Files

Exports to other file types are best done with Pandoc since Minimd strictly adheres to a subset of the overlap between Pandoc's Markdown syntax and the Commonmark specification.

You can easily set keybindings to facilitate repeated exports. For instance, the sequence <Leader>ep could be set to export a PDF of the current Markdown file by adding the line autocmd FileType minimd nmap <Leader>ep :!pandoc -f markdown -o example.pdf '%' to your vimrc. See the Pandoc manual for an overview of its many options.

Related Projects

Minimd started out as an implementation of the header visibility cycling idea from Org Mode (and of Outline Mode before that) for Emacs. If you use Emacs, you should probably use one of those, and it should probably be Org Mode.

vim-minimd's Issues

Move or disable wordcount

I wonder if it would be a good idea to implement some kind of guard to prevent your fabulous plugin from changing the statusbar for markdown files.

I use lualine to display the statusbar, but whenever I edit a markdown file minimd takes over and all the fancy stuff is gone :)

I'm thinking of something like setting a variable like let g:minimd_leave_statusbar_untouched = 1 which will be evaluated wherever necessary.

Header Bindings [] Mess with Spell Checking

If you enable spell checking and then try to use [s or ]s to jump between spelling errors, it doesn't work due to minimd overriding the default mapping. Is there an option to disable this? Thanks

[Feature Request] Fenced Code Block Syntax Highlighting

Hi,

I'm not sure how easy it would be to add this but tpope's vim-markdown plugin has support for this which is very nice :)

Word count bug

I am using vim-minimd latest from github, on archlinux:
VIM - Vi IMproved 8.2 (2019 Dec 12, compiled Sep 17 2020 21:54:53)
Zadane łaty: 1-1704

And I found a bug in word counting function about too many arguments.

Wykryto błąd podczas przetwarzania BufEnter Autokomend dla "*"..function minimd#UpdateWordCount:
wiersz    7:
E684: Indeks listy poza zakresem: 11
E116: Zbyt wiele argumentów dla funkcji str2nr(split(v:statusmsg)[11])

It is present no matter which file I open, even with new empty markdown buffer.

Jump to earlier header when invoking minimd#HeaderMotion('B') from character position > 0

When minimd#HeaderMotion('B') is called with the cursor at any position other than column 0, the cursor moves to column 0, requiring an additional invocation of minimd#HeaderMotion('B') to move to the previous header.

Space to Close Section No Longer Works

After upgrading to the latest version (d3846c0), the space key no longer works to close the section I am in. So if I am in the middle of a section and want to close it, I now have to move to the header of the section and then press the space key to close the section. Prior to the latest updates, I could simply press space and it would close the section for me, regardless of where in the section I was. Thanks

[Feature Request] Fold All Items at Given Heading Level

First of all, I'd like to thank you for developing this fantastic plugin. I just installed it today and I can't believe I hadn't run into it before.

I had a small feature request. Would it be possible to have add some type of option to fold all the sections. For example, if I have a document with several Heading 1 items and I wanted to close all of them so I only saw them and nothing else, would that be possible? Or to tell it to show me Heading 2 and Heading 1 level entries only? Thanks