This post describes how to write a plugin for Vim using VimScript. The example plugin created here will detect custom file types (.riley) and do some simple syntax highlighting to serve as an introduction/reference.

• Vim Plugin Directories
• Defining runtime paths using Pathogen
• Enabling Pathogen
• Adding Functionality
• Detecting File Types
• Syntax Highlighting

Vim Plugin Directories
A Vim plugin may contain the following directories which are useful for plugin development within ~/.vim/plugin/.

Files in:

• ~/.vim/colors/ define color schemes used by Vim.
• ~/.vim/plugin/ are run each time Vim starts.
• ~/.vim/ftdetect/ are run each time Vim starts. Files here are used for filetype detection derived by autocommands.
• ~/.vim/ftplugin/ are run when the buffer filetype is set; Vim looks in this directory for a subdirectory name matching the buffer filetype (for example: ~/.vim/ftplugin/java/ for .java files.
• ~/.vim/indent/ are loaded similarly to ~/.vim/ftplugin but placed in this directory to specify their use case of indent definition.
• ~/.vim/after are run everytime Vim starts but after the files in ~/.vim/plugin/ are loaded.
• ~/.vim/autoload/ can be used to delay the loading of plugin code until necessary.
• ~/.vim/doc define documentation to be loaded using the :help command.

Pathogen
Since files for Vim plugins are defined in several directories it can become tricky to manage. Using Pathogen you can easily set the runtimepath for your plugin files. The Pathogen plugin looks for files in ~/.vim/bundle/ and automatically adds them to the runtime.

For example your plugin directory tree might look like this:

riley/
  README
  LICENSE
  doc/
    riley.txt
  ftdetect/
    riley.vim
  ftplugin/
    riley.vim
  riley.vim

Enabling Pathogen
The Pathogen documentation instructs users to enable Pathogen by invoking execute pathogen#infect() in your ~/.vimrc file. Since I manage my ~/.vimrc file using Git and consume it across various machines I wanted to check for a Pathogen installation before executing it:

1
2
3
4

" Ensure Pathogen is installed before enabling it
if (!empty(glob("/home/user/.vim/autoload/pathogen.vim")))
  execute pathogen#infect()
endif

Adding Functionality
I started by adding a simple echo call to ensure the plugin is being executed correctly.

~/.vim/plugin/riley/riley.vim:

1

echo "Riley plugin initialized

When entering Vim I’m now prompted with my echo message:

user ~/.vim/plugin/riley_plugin(master) $ vim riley.vim 
the riley plugin is initialized
Press ENTER or type command to continue

Detecting .riley Filetypes
Now that the plugin is loaded and verified we can add the File Type detection:

~/.vim/plugin/riley/ftdetect/riley.vim:

1

au BufNewFile,BufRead *.riley set filetype=riley

Give Vim and run to ensure no errors are thrown at startup. If no errors are thrown the functionality can be tested. Create a new .riley file somewhere:

# Bash
vim ~/test.riley
 
# VIM
:set filetype?
 
# Observe
filetype=riley

The .riley file type has been detected! Write the file for later.

Basic syntax highlighting
Now let’s add some basic syntax highlighting. Add the following file to the plugin:

~/.vim/plugin/riley/syntax/riley.vim:

1
2
3
4
5
6
7
8
9
10
11

" Finish if syntax is already set
if (exists("b:current_syntax"))
    finish
endif
 
" Set the words to be highlighted and highlight them
syntax keyword rileyKeyword riley 
highlight link rileyKeyword Keyword
 
" Set the current syntax to the one defined in `syntax`
let b:current_syntax = "riley"

Open the .riley file (created above) some text including “riley”. Any instance of “riley” should be highlighted! This plugin boilerplate can be extended to do some real work… once I figure out what that’s going to be.