---
title: Literate Vim
teaser: Vim commands are terse and arcane, but very expressive. See a complex command
  broken down by clause.
tags: vim
author: Caleb Hearth
published_on: 2016-07-28
---

Vim normal mode commands are made up of verbs, adverbs, and nouns. Many of them
are mnemonic such as **v**isual, **c**hange, **y**ank and **d**elete. Others
like **\`** are less obviously "go to" in context of a **m**ark.

Some Vim plugins add additional commands. In this example, we rely on
functionality from [vim-unimpaired] and [vim-surround] which add the `[ ` and
`ya]`/`vi>` functionality, respectively.

[vim-surround]: <https://github.com/tpope/vim-surround>
[vim-unimpaired]: <https://github.com/tpope/vim-unimpaired>

Let's break down a relatively verbose Vim normal mode command:

```viml
"wya]}[ "wpa: <https://example.com><Esc>vi>
```

1. `"w` Apply the next command to a register named "w". "w" happened to be an
   unused register in my Vim setup.
2. `ya]` **Y**ank the text **a**round the brackets.
3. `}` Move the cursor to the first line after the current paragraph.
4. `[ ` Insert a blank line above the cursor, but don't move the cursor and stay
   in normal mode. The space is "<Space>" in :help files.
5. `"w` Again, do something with the "w" register.
6. `p` **P**aste its contents.
7. `a` Open insert mode to **a**ppend after the character under the cursor.
8. `: <https://example.com>` Insert that literal text.
9. `<Esc>` Press escape, bringing us back to normal mode from insert mode.
10. `vi>` **V**isually select **i**nside angle brackets.

So what does this do?

    With your cursor inside [brackets] as on this line

Insert the text `[brackets]: <https://example.com>` after the paragraph, leaving
a blank line above. Visually select the link text and leave it to me to make
changes if desired.

![See it in action](https://images.thoughtbot.com/blog-vellum-image-uploads/DvSoxM1SzaiY2J3sOm3n_Screen%2520Recording%25202016-07-22%2520at%252002.28%2520PM.gif)

This is great when authoring a post in Markdown when you'd like to add a link to
some text. I have it mapped to `<Leader>e` in Markdown files with:

```viml
autocmd filetype markdown nnoremap <Leader>e :normal "wya]}[ "wpa: <https://example.com><Esc>vi>
```

Combine it with `ysa2w]` for even more fun. What does it do?

Unfortunately, it doesn't play nicely if the current paragraph is followed by an
EOF, as the `}` motion moves to the end of the paragraph and does not create a
new line.
<span title="&quot;wya]}h2] 2j&quot;wpa: &lt;https://example.com&gt;&lt;Esc&gt;vi&gt;">
Can you fix this? (hover for the answer.)</span> You might need to open up the
`:help` files and **j**ump around a bit until you **h**ave about **2** more
commands under your belt.