Web site


Years ago, someone told me about a program called WML, Website Meta Language. It's how a programmer would put a site together -- out of source files that get compiled into .html files. I thought that would be an excellent way to build my web site.

The problem is that it's hard to understand how to put a site together with WML. There's plenty of documentation on how to use WML, but in true UNIX fashion, it's made up of small, reuseable tools, which on their own aren't incredibly useful to me in building a web site. And the documentation is a very detailed instruction manual on these small tools. Most of the examples for using a feature are terribly trivial -- unless the purpose of your site is to perform transformations on the words foo, bar, and quux, then you're going to have a hard time understanding how to use WML to build your site.

Luckily, the folks at Debian use WML to manage their site. They've got a page about using WML (which even says that it's hard to learn from the documentation), and better yet, the source code for their web site is available. Finally, there was something I could learn from.

WML Features

There are tons and tons of WML features, and I'm only using a handful of them. But I've listed them here both to show how useful WML is and to serve as a guide in case you'd like to use WML.

Include pre-processor. Much like cpp, WML understands the #include directive. You can even pass arguments to it. At the top of this page is the directive: #include <template.wml> topic="software" This puts the image at the top of the page, and setting the topic variable tells the template that the navigation pane should highlight the software section. This eliminates typing redundant HTML on every page. Not to mention saving tons of time if you want to give the site a facelift.

Create your own tags. I've defined a couple of tags to make writing pages easier. For example, when I want to show something that's a piece of code or something like you'd see on a terminal, I put it in a yellow box. To save myself all the HTML associated with the box and the fixed-width font, I can just write: <screen>Stuff you'd see on a screen</screen> Not only do these tags save time when writing the pages, they make it trivial to change the look of the site. All these tags are defined in tags.wml, if you'd like to have a look.

Auto-adjusted pathnames. I like to put all my images in one directory, even though they're referenced by pages in several directories. Depending on where the image is referenced from, there might be several different pathnames for the same image. I could just use the absolute path /images, but then the site won't work in a subdirectory (useful for testing out changes). And I can't use relative paths everywhere because there are templates that reference images that get included from different directories. The solution -- WML lets me put this in my .wmlrc at the top-level directory: -D IMAGES~images This means that the variable IMAGES gets assigned the pathname of images directory, auto-adjusted from whatever directory WML is in when it finds a reference to $(IMAGES). So I can safely refer to the images directory from any place in the site, and I don't have to use an absolute URL.

Building the Site

So now that I've got a tree full of .wml files, how do I turn them all into .html files? I could just use make, but then I'd need a Makefile in every directory (this is what Debian does). Instead, I use wmk, part of WML. It's a make-like tool that can descend recursively through a directory structure and invoke wml on every .wml file it encounters (or just those that have been updated) to turn them into .html files. I build my site with the following command: wmk -a -F include -I $PWD/webroot/include The -a tells wmk to descend recursively, -F include tells it not to process the include directory, and -I $PWD/webroot/include adds a path to the search path for included files, similar to the -I option for C compilers.

To automate this, I've written a script that checks the latest version of the web site out from CVS, builds the .html files with wmk, and publishes all this to a directory on one of my home systems. This happens every hour unattended. Since my web site is hosted at an ISP and I need to get the files there somehow, I'm running rsync every hour on their system to transfer any changes from the home system to the web server. My ISP is UNIX-friendly and lets me have a shell account with SSH access, and allows me to compile and run anything I want on their systems.

Source code

If you'd like to see how the entire site fits together, take a look at the website source on GitHub.