Earlier this week I watched a video by Sylvan Franklin on YouTube on useful Vim commands for writers. Writing documentation is something I happen to do often, so I gave it a watch. Sylvan explains how long lines can be difficult to manage in Vim. Even with :set wrap, as that only makes it easier to read the long lines, not so much on navigating those lines (gj/gk help a smidgen there).

Sylvan suggests using selecting the line (S-v) and then gq - which formats text - to wrap everything on separate lines, or for paragraphs gqap. He struggles a bit with joining formatted lines again. I think gq is great for cleaning up changes in Markdown documents when combined with joining lines, which I’ll address below. However, some configuration may be required to get this to function, and there are some small optimizations I would add.

Configuration

First, some configuration as gq relies on a couple of things. Meaning, q has to be set in formatoptions, and gq will wrap the words within the set textwidth. I have something like this in Neovim which continues comments, joins comments, and recognizes lists as well:

vim.opt.textwidth = 100
vim.opt.formatoptions = vim.opt.formatoptions + "qnjr"

Optimization

I’d like to point out the small changes I would make to Sylvan’s suggestions:

  • Format line: gqq instead of S-v followed by gq. The extra q will apply the operation to the line, so S-v to select the line is no longer needed.
  • A bit pedantic, but I would format paragraphs with gqip instead of gqap. Using ip instead of ap makes the intention clearer to me and leaves the cursor inside the paragraph, and aligns better with how I join lines.

Joining lines with J repeatedly works, but is suboptimal as for documentation this should usually be a paragraph. Joining a paragraph with vipJ will set everything back to one line, inside paragraph so it doesn’t accidentally join the paragraph with the next paragraph.

Markdown docs examples

Let’s assume there is a README.md that describes the feature of a product in short

# Introduction

This is a great project written in a terrific programming language and supports many cool features like: an extensive feature, and a simple feature, plus some useless things.

# Usage

...

Jumping to the long line and pressing gqq:

# Introduction

This is a great project written in a terrific programming language and supports
many cool features like: an extensive feature, and a simple feature, plus some
useless things.

# Usage

...

Then edit the paragraph a bit:

# Introduction

This project is written in a language and has
many cool features like: an extensive feature, and a simple feature, plus some other things that people find
useful.

# Usage

...

Fixing this by hand can be tedious, but with vipJ and gqip it is cleaned up in no time.

# Introduction

This project is written in a language and has many cool features like: an
extensive feature, and a simple feature, plus some other things that people
find useful.

# Usage

...

Happy Vimming!