Learn Vim at your own pace with my self-study Core Vim Course.

Learn more

Learn Vim at your own pace with my self-study Core Vim Course.

Converting markdown to structured HTML with a macro


Run time:

Recording your keystrokes as a macro can be a great timesaver, but you have to be careful that you use commands in such a way that they can be reused. In this episode, I construct a fairly complex macro to build a structural HTML document from markdown.


The demonstration in this video uses a range of techniques to construct a macro that can be replayed reliably, including text objects, the surround plugin, using registers as a clipboard, and for storing keystrokes (macros). These are summarized below.

If you would like to try building this macro for yourself, you can download the source files:

Moving around

If you need to move around whilst recording a macro, it is best to do so in such a way that it can be replayed in another context. In this demonstration, I move the cursor by searching for a pattern that delimits each region of the document that I need to edit. In particular, I search for the heading using the command:


This matches a Markdown style h1.

To return my cursor to the navigation list, I search backwards for the closing </ol> tag:


There are a couple times when I need to add an attribute to an HTML tag. In both cases, my cursor is positioned on the opening angle-bracket, so I use the % key to jump to the closing angle-bracket before entering insert mode.

Making a selection with text-objects

When selecting a paragraph of text, I need to use a command that will work when the macro is replayed on different length paragraphs. I can do this using the text object:


A similar command comes in handy later, when I need to select the text inside an HTML tag:


Adding opening and closing tags with the surround plugin

The surround.vim plugin makes it really easy to wrap a selection with opening and closing tags. When a visual selection has been made, you can execute a command such as:


Which will prepend <li> and append </li> to the selected region. Note that if your selection was made in visual character mode, the opening and closing tags will be applied directly before and after the selection. Whereas if your selection was made in visual line mode, the surrounding tags will each get a new line of their own.

Using registers

In Vim, each of the letters a through z can be used as a register. In this demonstration I use registers in two ways:

  • as a clipboard (for copy/paste operations)
  • for capturing and replaying a sequence of commands (a macro)

Further reading


Level-up your Vim


Boost your productivity with a Vim training class. Join a public class, or book a private session for your team.

Drew hosted a private Vim session for the shopify team that was one of the best workshops I have ever attended.

John Duff, Director of Engineering at Shopify


Make yourself a faster and more efficient developer with the help of these publications, including Practical Vim (Pragmatic Bookshelf 2012), which has over 50 five-star reviews on Amazon.

After reading it, I've switched to vim as my default editor on a daily basis with no regrets. ★★★★★

Javier Collado

Learn to use Vim efficiently in your Ruby projects

In association with thoughtbot, one of the most well respected Rails consultancies in the world, I've produced a series of screencasts on how to make navigating your Ruby projects with Vim ultra-efficient. Along the way, you’ll also learn how to make Ruby blocks a first-class text object in Vim. This lets you edit Ruby code at a higher level of abstraction. Available to buy from thoughtbot..