vimvim-plugin

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


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?


Solution

  • 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.