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.
Unzip the most recent ZIP archive file inside your Vim profile
directory (usually this is ~/.vim on UNIX and %USERPROFILE%\vimfiles on
Windows). 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 execute it in Vim by typing :source
~/publish_test.vim and pressing Enter↵. 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.vim 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 www.vim.org.
This software is licensed under the MIT license.
© 2010 Peter Odding <peter@peterodding.com>.