This ought to be some kind of tutorial on how to write your own syntax highlighting rules for vim and how to activate them. Actually, the sites I found on the web, were either too superficial or much too complicated – like the vim documentation itself. I used them all to learn the art of syntax highlighting. Still, I am no master. Anyhow, there is a bit of pride about my success.

What is syntax highlighting?

Assume you have some random text – pure text without any formatting. Now, you want to have certain parts, phrases, words highlighted – specific background, font color, font decoration. Stick to a limited number of classes. Example: Every word beginning with “anti”. Label your classes. All the text segments that shall be highlighted have to be assigned a label which then defines how your text is highlighted.

Syntax highlighting makes your text easily readable. On a very low level syntax highlighting can even help to avoid errors. Originally, I got to know syntax highlighting from coding. You have different colors for variables, function names, comments and so on. In preparing this tutorial I aimed for something very different. In my new job I work a lot with text – as an editor I have to refine text handed in by authors in a way that it fits our standards. I’m working for a german journal. For instance, passive voice is considered bad style. Also words like “for instance” (zum Beispiel) or “also” (auch) are not well liked. Syntax highlighting shall help to make such mistakes visible.

Defining syntax rules

The simplest case is the appearance of a single word. The following example, which is valid for vim syntax files, assigns the word Foo to the class Foo:

syntax keyword Foo Foo

You might wonder where this piece of code shall be written to. It is a vim command so you can simply enter in vim but a more appropriate place is a new file in the syntax folder under your vim configuration path. My Kubuntu and my Debian installation place it under ~/.vim/syntax. For the purpose of this tutorial we create highlighting for the Filetype bar. Hence, the syntax file is ~/.vim/syntax/bar.vim.

The next step is to define how the class Foo is highlighted. This can be achieved by the following line:

highlight Foo cterm=bold,underline

In a more understandable language this means: “Dear computer, please highlight every piece of my text which is classified as Foo by using bold font and underlining it, as long as we’re on a color terminal!” By adding “term=bold,underline” a similar rule is defined for a monochrome terminal and, eventually, we can define rules for “gui” in a similar way.

The syntax so far should look like:


if exists("b:current_syntax")
finish
endif

syntax keyword Foo Foo
highlight Foo cterm=bold,underline

let b:current_syntax=bar

There is some yet unexplained decoration. They prevent several multiple syntax files to be loaded at the same time and are not required – but nice to have.

Activating the style file

Since you most likely created the style file within VIM you can now directly switch to your new highlighting by using the command: set syntax=bar. The result should look something like:

All Foo are set in bold font and underlined

All “Foo”s are set in bold font and underlined

Instead of defining every highlighting class on your own one cal also revert to predefined classes like: Todo, Comment, Statement, Type, Constant, PreProc. Instead of the above our syntax file could contain the line

hi link Foo Error

In that case the example looks different:

All Foo have a red background

All Foo have a red background

More about the highlight command

We saw how to link a new highlighting class against an existing one and now let me tell you a bit more about defining your own style – this tutorial won’t go any deeper. We have three relevant terminals: gui – which you encounter for instance when using gvim, cterm – probably used most often on modern computers; it belongs to the normal shell version of vim on a terminal with colored output, and term – the monochrome variant of cterm; of course, no color options are possible with this term. A situation where the latter becomes relevant is printing on a grayscale printer.

For all terminals you can define (note the the abilities of the frontends differ):

  • font appearance: term|cterm|gui={list} — any (comma-separated) combination from: bold, underline, undercurl, reverse, inverse, italic, standout, NONE, where NONE resets previosly defined settings
  • font color: ctermfg|guifg={color} — in cterm the color is an integer or a color name, for the gui you can additionally use HTML color codes
  • background color: ctermbg|guibg={color} — same as above

Example:

hi Foo ctermbg=Green ctermfg=White cterm=bold,underline

Sidenote: vim-commands may be abbreviated. Just strip letters from the end of the command. This is fine as long as the remainder is still unique. So just type hi instead of highlight or syn instead of syntax.

Defining syntax elements

We started with a simple keyword. But that’s not the power of syntax hightlight — although it is important. Since this tutorial is not aiming at explaing how to use regexps within vim-files or even in general, I encourage to make sure you know enough.

The rules are simple enough:

syn region textregion start="pattern1" end="pattern2"
syn match textpattern "pattern"

hi textregion ctermbg=white ctermfg=green
hi textpattern ctermbg=green ctermfg=white

One picture cann tell more than a hundred words, so just have look:
example_pattern

More about patterns can be found here: Vim documentation # patterns

Finalization

I assume you are now able to build at least a small, complete syntax file. On Linux you place it unter ~/.vim/syntax. Now you want vim to automatically load your syntax definitions when the corresponding file is loaded. To this end make sure that syntax highlight is enabled. Your .vimrc (~/.vimrc in Linux) should contain a line syntax on.

For automatic loading I used the filetype command. In ~/.vimrc it activates filetype checking through the command filetype on. The actual attributing is done in the the file ~/.vim/ftdetect/bar.cim. It contains one line which enables our previously defined syntax highlighting for all files ending with .bar


au BufRead,BufNewFile *.bar set filetype=bar

This command sets filetype to bar for every new or opened file with a .bar suffix.

Note that you can have more complicated criteria which are sensitive for file content. I haven’t gone through these rules. With the things presented here you are able to write your own syntax files. Later refinements are easy.

  1. mark says:

    Thank you so much for this great tutorial. I really appreciate it.