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?
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
create the necessary infrastructure for "packages":
~/.vim/pack/<arbitrary name>/start/
create a directory for your plugin:
~/.vim/pack/<arbitrary name>/start/foo/
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/
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.