Vim Personal Documentation

Summary

What you are reading now is my personal vim documentation.

Whether this would be helpful is entirely and totally dependent on how much you use vim. If you’re a typical user, then this might work for you. If you’re more advanced, this guide is basically a children’s book to you. And if you use vim like, once a year, then go figure the usefulness of such a guide to you.

Because of extensively working in vim (to the point of using it basically exclusively), I’ve made Vim my own playground. So be prepared to find unofficial code, messy references, and so on.

However, I’m releasing this to the community in hopes that others can remix and learn vim in a more relaxed way. You’re free to do basically everything with this book. It’s under a CC0 license, which makes it effectively public domain.

I have to thank all of the awesome developers of Vim and its plugins for giving me this amazing opportunity. And the creators of mdBook for making it so easy to share my experiences with everyone.

Without further ado, let’s get into Vim! You’ll learn everything I’ve ever learnt about Vim - and hopefully gain a fair share of respect for this unassuming yet powerful editor along the way.

Quick Start

First off, I should highlight that Vim is my personal preference, not because of its endless configuration or its minimalist charm, but by its permissive and open license.

My personal point of view is that large companies such as Microsoft and Adobe

will inevitably use free and open-source as a marketting gesture, not a genuine commitement. But take a look at the Vim community, and you’ll basically be staring at Github repos all day. Vim is truly the epitome of decentralization (ok, with maybe emacs just beating it by a margin). Its plugin system and overall architecture simply exuberates community, even if “free and open-source” isn’t even on the frontpage of its website.

What to do if you struggle with vim

I understand the frustration you can get when first using vim. I felt the same way when I tried to learn vim and gave up twice. Vim just felt so unneccesary - why :q! if you can use CTRL Q in every other program? Why :w when you’ve always used CTRL S? And my least favorite command: ggVG"+y to copy the document. Every little quirk of vim can spiral onto a full-blown case of Vim frustration.

So how do you avoid the classic syndrome of “Vim depression”? I’ve generally relied on several ways to do so:

Use the GUI versions first

The Vim community has ardently resisted against a GUI for Vim for decades. That’s why most versions of Vim are pretty minimal, out of the box. It has to be launched from a command line. Copy and paste doesn’t work. And click-drag select does nothing - which can utterly break people.

That’s why I recommend installing a GUI version of Vim. For Windows and GNU/Linux, it usually means GVim. For Mac users, MacVim should also do a good job. I might recommend neovim GUIs such as Veonim and Goneovim, but these are not ready-to-download and must be compiled.

Let’s get back on topic here. If you open up GVim or MacVim, the user interface is, to put bluntly, not spectacular. Yes, you can highlight, copy, and paste, and yes, you can move the cursor with a mouse, but it just doesn’t look right. Which is why you need to beautify Vim.

Make Vim colorful

Right out of the box, Vim is practical drawing pad, not a polished work of art. However, Vim was never designed to be a plain drawing pad with no drawings on it. Vim was always intended to look how you wanted it to - and it can look pretty good - even better than many modern editors - once you begin adding themes and plugins.

First things first, the most visually altering things you’ll need to do are:

Install a new theme
Install an airline status bar
Install coding fonts

Installing a font is probably the first and easiest one of the three. And so on...

Focus on the navigation

Vim’s 4-key based navigation is arguably its strongest point. That’s how it never needs to rely on a mouse to work.

However, getting to grips with this can be difficult. And even worse are keyboard tables for Vim, which, though well-intentioned, provide little true support.

So that’s why learning visually is a great idea. Take this, for example:

	k
	^
	|
   h <-- --> l
	|
	v
	j

This is a good way to get familiar with Vim’s 4 key navigation. And once you’re done with that, try this:

   <-|------------------------------|->
     0     |   <-<- |  ->->   |     $
       <---+        *     <---+--->
       b          here    w       e
               ^ <-<-

After that, it’s just a few sparse commands that muscle memory will eventually get the hang of, such as gg to go to the top of the document, number G to go to a specific line, and G to go to the last line. Work in progress...

Now, with SPC e, I can launch a file browser (coc-explorer), make a index.html and play around with a website, and toggle a command prompt with the :CocCommand command-here. And that’s just the surface of what you can do with Coc!

Doing more advanced stuff with plugins

Now that you’ve learnt how to use vim, let’s spice it up with plugins! And don’t be worried about the learning curve! Unlike almost all other software, I’ve found that vim’s plugins actually make vim easier than plugin-less vim. The only real disadvantage is that too many plugins can clash with each other and result in horrible configurations - but that’s when you have literally hundreds of plugins! So we don’t have to worry about that for now.

Vimming with Coc

Coc is perhaps the king of all Vim plugins. Because it’s not just a plugin. It’s more like a full plugin environment integrated closely to vim that adds all sorts of cool features. It’s literally that plugin that turns Vim from a text editor to an IDE.

To get started with Coc, familiarize yourself again with the vim-plug system. As a refresher, vim-plug uses a special portion of your ~/.vimrc file to manage plugins. If you’ve forgotten, here’s how it should look like:

 
call plug#begin('~/.vim/plugged')

" put your vim plugins here 

call plug#end()

The code for coc is Plug 'neoclide/coc.nvim', {'branch': 'release'}. Just paste that in to your vim-plug code block. Like this:

 
call plug#begin('~/.vim/plugged')

" The Coc plugin 
Plug 'neoclide/coc.nvim', {'branch': 'release'}

" put your other vim plugins within this section

call plug#end()

Now, just do a source ~/.vimrc and a :PlugInstall. Wait for the plugin download screen to stop flashing, and you can begin using Coc.

First things first, you’ve got to add some basic languages to Coc. Being a web and frontend/GUI developer mostly, I usually go for the web design languages, and maybe python. That’s why I recomment you to add html, css, js, and json first, as well as the word dtatbase from the makers of VSCode, like this:

:CocInstall coc-html coc-css coc-tsserver coc-json coc-word

Now, start writing some code! You’ll see recomennded words to use within a popu menu. And just use the down and up arrow keys to choose your desired word. This can be useful in writing non-code prose as well, such as long essays with lots of long words.

To make the plugin install process less obtrusive, I recommend downloading the coc-marketplace plugin, with :CocInstall coc-marketplace. After sourcing the .vimrc and running :PlugInstall, you can simply type :CocInstall coc-marketplace to search through all your extensions.

Once you’ve downloaded them, use the command :CocList extensions to do your view an manager work. Press the tab key to toggle, enable, and control your extensions. :CocUpdate will update all extensions, if that’s your style.

And my favorite part - :CocList commands allows you to run any coc-supported feature and plugin subfeature with simper-simple input. It’s also fuzzy searched, so no worries about bad typing!

In addition, the extensions often use the vim CR key, also known as the \ character. Add nmap <space>e :CocCommand explorer<CR> to change the CR key to the , key.

Vim Personal Docs