Wiki-related vim setup

created: 2020-06-26 · modified: 2020-09-02

Markdown

The entire wiki is meant to be written in Markdown, and only Markdown.

External Plugins

  • Vim-markdown
  • Wiki.vim
  • Bullets.vim

Formatting

  • Default formatting options
  • Autoindent
  • Filetype indent
  • Comment definition
  • Hard line breaks

Reformatting

  • Basic gq and formatoptions to preserve two way reformatting
  • Bullets.vim reformatting of lists

Shortcuts

  • Fzf link completion
  • Snippets link and image completion (clipboard)

Indentation

How automatic indentation is handled for various text objects is a constant problem when working with markdown files and different plugins. The following describes base behaviour with different plugins applied:

  • No plugins applied: using fixed textwidth to break lines, autoindent is on, and the n options of formatoptions is set. Numbered lists are properly indented when broken by textwidth:

    1. A test line continues on until reaching textwidth
   and automatically brings the new line to a nice
   position. This is the work of autoindent and the
   `n` option of `formatoptions`.

    Of course, no new list item is created when hitting <cr>; when hitting <cr> after two lines of the list item has been written, autoindent will place the cursor as the properly indented location, since it’s taking from the previous line’s indent. When hitting <cr> with only one line written, the cursor is place back at the beginning of the line with no indent, as autoindent does not see any indentation to replicate. For bulleted lists, the indentation is not quite correct; it indents the same amount that number lists do, which is off:

    - A list item that overflows to next line
    with `autoindent` appears to indent by
    4 spaces instead of only 2.

    Additionally, after hitting <cr> at any point will extend the previous line’s indentation due to autoindent. This is expected, but worth that it will simply continue regardless of how many times <cr> is pressed (without anything else). Another important point: while hitting <cr> after a single line number list item will keep the next line without any indent (since there’s no indent to match), hitting <cr> after a single line bullet point puts the cursor on the next line with an standard 4 space indent.

  • With vim-markdown only installed: from what I can tell, everything behaves exactly the same. No autocompleted list items, no unexpected indentations after list items (since they are expected and match the behaviour above).

  • With both vim-markdown and bullets.vim installed: Numbered lists now behave as expected with the bullets.vim plugin. Lines are properly broken when extending beyond textwidth (as they have previously). However, now when I manually hit <cr>, a proper new number will appear instead of autoindent extending my cursor forward. When I hit <cr> again after creating a new list item (that I don’t want), it removes the blank numbered item, moves me to the next line, and de-indents my cursor to prevent autoindent from continuing to extend it. This is the perfect, ideal functionality. This appears to work properly for nested numbered lists as well (however it does not de-indent my list number on <cr> when in a nested list back to an outer list like Vimwiki does, unfortunately). However, this functionality breaks down for regular bulleted lists. bullet.vim does its job properly by allowing me automatically get new list items, but the indent is still broken the way it was previously. This isn’t bullet.vim’s fault (although they actually claim to make this functionality work); it’s the same problem from earlier propagating through.

Here the main takeaways are that Vim’s autoindent and formatoptions only appear to take the list indent as far as numbered lists, dropping the ball on regular bulleted lists of other types. Additionally, there is a mysterious tab being entered after each bulleted list…wait. I found out why this is happening. It was due to a stray indent file in my .vim directory, whose entire purpose was to add this indentation. Terrible. Removing this, along with the bullet indent option in Vim-markdown, has restored the expected functionality to all list types.

Note that the comment definitions that make the list indentation possible are defined by default in Vim’s including markdown filetype plugin. However, Vim-roam also defines a number of other list bullets (they were part of the fork). Additionally, the n option in formatoptions also the proper functionality of numbered lists.