How do I turn on vim syntax highlighting via modeline?

Question

In my .vimrc file I have

syntax off

Suppose I want to turn on syntax highlighting on a case-by-case basis via vim's modeline? I've tried many combinations, like:

# vim: syntax on:

but I still can't get it to work. What do I need to do in the modeline?

Answer 1

According to :help syntax, using syntax enable or syntax on loads syntax files at runtime. But there's also apparently syntax manual which turns it on based on the syntax type you specify. Looking at the source vimscript, it says:

It installs the Syntax autocommands, but not the FileType autocommands.

You can therefore use syntax= to set the type, and that works in a modeline to either set a specific type or set none which effectively turns it off.

# vimrc
syntax manual

# In your files
# Turn it on for this yaml file
# vim: syntax=yaml:

# Or this PHP file
# vim: syntax=php:

If you want to be explicit about disabling it in a file:

# In your files
# No syntax highlighting for this file (default if omitted)
# vim: syntax=none:

Answer 2

Vim is a multi-buffer/window/tab editor. Changing global state (syntax, colorscheme, loading plugin etc.) per current file is a wrong habit. Luckily, modeline does not allow this.

What you can do in the modeline is to set :h local-options. Accidentally, there's an option also named :h 'syntax'. And it has the same syntax as any other option.

# vim: syntax=OFF

You don't need to set :syntax manual for this to work, as modeline has preference over filetype detection. However, if FileType event is fired manually (e.g. :setf xyz) while :syntax on then buffer's syntax could be redefined to match new filetype. Not a problem though.