How to develop a vim plugin which is compatible with vim-plug

Question

I'm writing a simple plugin that consists of various files which I'm storing in the standard places: .vim/ftplugin, .vim/plugin, .vim/systax, etc. It's growing and I'd like to have all this sorted in a single repository, and eventually let it be handled by vim-plug.

This might be a dumb question, but how do I have to organise my files in a single folder and what line do I have to use to let vim plug handle my plugin and eventually make installable? I could not find this documented anywhere.

So far I have created the following file structure:

> tree ~/.vim/bundle/vim-sbatch
/home/sp4e/.vim/bundle/vim-sbatch
├── doc
├── ftplugin
│   └── sbatch.vim
├── plugin
│   └── sbatch.vim
└── syntax
    └── sbatch.vim

But this alone does not work. The commands defined in .vim/plugin/sbatch do not exist. This kind of makes sense, because I have been exploring the 'rtp' variable and indeed there is no reference to .vim/budle/vim-sbatch. How do I let know vim-plug that it must look at this directory?

Answer 1

Vim has two "runtime directories": one at the system level, in /usr/share/vim/ (or some other place depending on your system), and one at the user level, in ~/.vim/ (or some other place, depending on your system).

Both directories are meant to have a similar structure: autoload/, doc/, ftplugin/, plugin/, etc. What we call a "plugin" can be a single file under plugin/ or any number of files in any number of those standard directories. Hell, it could even handle its own directory structure.

Vim-plug and all the other plugin managers work the same way: they add more runtime directories, one for each "plugin", to Vim's default :help 'runtimepath'. Therefore, in order to make your plugin work with every current plugin management solution, all you need to do is bundle the directories/files that make up your plugin together in their own runtime directory.

The following procedure use the native :help packages feature. You should read that help section before going further.

Let's assume your plugin foo is currently scattered around your ~/.vim/ directory:

~/.vim/autoload/foo.vim
~/.vim/doc/foo.txt
~/.vim/ftplugin/foo.vim
~/.vim/syntax/foo.vim

1. create the necessary infrastructure for "packages":

   ~/.vim/pack/<arbitrary name>/start/
   

2. create a directory for your plugin:

   ~/.vim/pack/<arbitrary name>/start/foo/
   

3. replicate the desired structure:

   ~/.vim/pack/<arbitrary name>/start/foo/autoload/
   ~/.vim/pack/<arbitrary name>/start/foo/doc/
   ~/.vim/pack/<arbitrary name>/start/foo/ftplugin/
   ~/.vim/pack/<arbitrary name>/start/foo/syntax/
   

4. and, finally, move your files:

   ~/.vim/pack/<arbitrary name>/start/foo/autoload/foo.vim
   ~/.vim/pack/<arbitrary name>/start/foo/doc/foo.txt
   ~/.vim/pack/<arbitrary name>/start/foo/ftplugin/foo.vim
   ~/.vim/pack/<arbitrary name>/start/foo/syntax/foo.vim
   

The end result is a single directory foo/ containing all your plugin's files, that can be put under version control and zipped for distribution.

See :help usr_51.

--- EDIT ---

Your question is really two questions: "How to package a custom Vim plugin?" and "How to load a custom Vim plugin with vim-plug?".

How to package a custom Vim plugin?

The plugin management solution you or your would-be users use is irrelevant when it comes to packaging. You don't package a plugin in one way for vim-plug and in another way for $OTHER_PLUGIN_MANAGER. All plugin managers work the same and the expected structure is always the same. In your case, this is the structure of your plugin:

vim-sbatch/ftplugin/sbatch.vim
vim-sbatch/plugin/sbatch.vim
vim-sbatch/syntax/sbatch.vim

How to load a custom Vim plugin with vim-plug?

If you use vim-plug, which I don't, then that directory can be literally anywhere on your machine:

~/Documents/MyProjects/sbatch/vim-sbatch

and either added to vim-plug with the following directive:

Plug '~/Documents/MyProjects/sbatch/vim-sbatch'

as instructed in vim-plug's documentation, or put under version control and hosted on GitHub, which lets you add it just like any other plugin:

Plug 'Pythonist/vim-sbatch'

again, as instructed in vim-plug's documentation.