The Vim text editor includes the script 2html.vim which can be used to convert a syntax highlighted buffer in Vim to an HTML document that, when viewed in a web browser, should look exactly the same. After using that script for a while and discovering the excellent Exuberant Ctags I wondered “Wouldn’t it be nice to have those tags converted to hyperlinks when I publish source code as HTML?”.
After several attempts I managed a working prototype, but it was quite rough around the edges and I didn’t really have the time or interest to clean it up. Several months later I found myself with some free time and a renewed interest in Vim scripting so I decided to clean up my code and release it. If you’re wondering what the result looks like, I’ve published the plug-in source code as a demonstration.
Please note that the vim-publish plug-in requires my vim-misc plug-in which is separately distributed.
Unzip the most recent ZIP archives of the vim-publish and vim-misc plug-ins inside your Vim profile directory (usually this is ~/.vim on UNIX and %USERPROFILE%\vimfiles on Windows), restart Vim and execute the command :helptags ~/.vim/doc (use :helptags ~\vimfiles\doc instead on Windows). If you prefer you can also use Pathogen, Vundle or a similar tool to install & update the vim-publish and vim-misc plug-ins using a local clone of the git repository.
As an example we’ll publish the plug-in using itself. First create a tags file that contains entries for the files you want to publish using a shell command such as:
$ ctags -Rf ~/.publish_tags ~/.vim/
If this doesn’t work because ctags isn’t installed you can download it from the Exuberant Ctags homepage, or if you’re running Debian/Ubuntu you can install it by executing the following shell command:
$ sudo apt-get install exuberant-ctags
The plug-in needs an up-to-date tags file so that it can create hyperlinks between the published files. Now start Vim and write a script that registers the tags file you just created and calls the function Publish() as follows:
:set tags=~/.publish_tags :let sources = '/home/peter/.vim' :let target = 'sftp://peterodding.com/code/vim/profile' :call Publish(sources, target, [ \ 'autoload/xolox/escape.vim', \ 'autoload/xolox/path.vim', \ 'autoload/publish.vim', \ 'plugin/publish.vim', \ ])
Change the sources and target variables to reflect your situation, save the script as ~/publish_test.vim and try it in Vim by executing the command :source ~/publish_test.vim. If everything goes well Vim will be busy for a moment and after that you will find a bunch of syntax highlighted, interlinked HTML documents in the target directory!
As you can see from the example above it’s possible to publish files directly to your web server using the netrw plug-in that’s bundled with Vim, simply by starting the target path with sftp://. All you need for this to work is the ability to establish SCP connections to your server. There are however two disadvantages to remote publishing over SFTP:
The publish.vim plug-in can’t automatically create directories on the remote side, which means you’ll have to do so by hand — very bothersome.
It can take a while to publish a dozen files because a new connection is established for every file that’s uploaded to the remote location.
As a workaround to both of these issues the publish.vim plug-in will automatically use rsync when both the local and remote system have it installed. This cuts the time to publish to a remote location in half and enables the plug-in to automatically create directories on the remote side.
If you have questions, bug reports, suggestions, etc. the author can be contacted at peter@peterodding.com. The latest version is available at http://peterodding.com/code/vim/publish/ and http://github.com/xolox/vim-publish. If you like the script please vote for it on Vim Online.
This software is licensed under the MIT license.
© 2013 Peter Odding <peter@peterodding.com>.
Last updated Mon Aug 19 20:08:28 UTC 2013.