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.
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
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:
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.
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.
If you'd like to see how the entire site fits together, take a look at the website source on GitHub.