I suppose that everyone has their own particular style for creating web sites. Let me describe some of the features that I need/want:

• I want to create a single web page template and have it used to create every future page.

• A month after the site is live, and I want to change an element that is the same across all pages, I don’t want to edit all the pages… just the original template file and have all of the pages get updated.

• I don’t want any dynamic framework or anything too runtime-intensive. I want some tool that basically creates the web site as a series of static web pages.

• I’m actually getting tired of HTML, and would like to write the content of each page as a regular text file. (I have an ulterior motive for mentioning this feature, as I would be happy writing my content in a web editor like DreamWeaver… but I won’t spoil the surprise yet.)

• While I don’t want to deal with HTML, if I want to have something special, this tool needs to let me write HTML.

• I also don’t want to edit lots of pages to manipulate navigational bars, menus and other links. I want them either relative or calculated for me automatically.

I don’t think this is too much to ask, do you? I’ve been in the web publishing business a loooong time, and I haven’t found anything that fits this bill, so I’ve been creating a tool to do this job. I now have a number of commercial web sites built using my web publishing system (including my own), and I thought it time to share it will the world.

While I am still crafting this thing, it is currently very useful, but it building a web site with this tool is a bit different… Different enough that I thought I better write a tutorial. We’ll dance through this tutorial as a series of steps … stop whenever you get the hang of it and want to take off doing your own moves.

1. Download the Gunk

To make this trivial, I’ve created a directory structure that contains everything you need. Download WebSite-Start.zip and unzip it somewhere. All of the supporting code is in the “support” directory, and while you may not need it all, it is all there (and to think the zip file is only a couple of megs).

I will assume that you have a JVM(Java Virtual Machine) installed as well as Ant. If not, get those installed before proceeding.

Add all of the Jar files in the “support” directory to your CLASSPATH. If you have an aversion to this sort of thing, I’ve created a shell script (buildsite) that you can use to do this as well as kick off the Ant build script. Feel free to modify at whim (like scp’ing the resulting web site to your web server).

2. Build the Web Site

The source as well as a default template have already been created as an example for you to use, so just build the site by typing:

cd WebSite-Start
ant

I told you it was simple. Any time you make a change to your content files or your templates, rebuild your web site by invoking ant in this directory.

3. Editing Text Files

The files in the datafiles directory contain the “content” for the web site. Each file contains the content for a single web page, but is just the text content (no graphical headers, menu bars, and that sort of stuff). These files are pretty simple, straight-forward and readable.

The are actually formatted, but in such a way that a filter can interpret them and convert them into HTML markup, but is also understandable by a human. For instance, instead of typing <em>italics</em>, you simply write *italics*.

You can read more about the formatting syntax on the Markdown web site, but I’ve had to add a couple of extra features.

If the first line is less than 50 characters, we assume that it is the title of the file (and is available to the template as such).

So, it should be very easy for you to drop into that directory and use Notepad or your favorite text editor and create a web page, like:

Testing Title

This is just a test of the emergency web publishing
system. If this had been an actual emergency, you
would have been given *actual* content.

But you weren't, so it isn't.

4. Edit the Template File

Each file in that datafiles directory will indicate a new web page to be created. Each file is the content that will be run through a template file.

It should be time to take a look at the templates/default.ftl template file. But there isn’t much there. Since all of the content will be supplied by those files, we just have to place “tags” where that data should go.

You’ll see them scattered throughout this example template as things that look like ${...}, as in ${title}. Also note that in this case, most of the stylistic formatting has been sucked off into a CSS style sheet file as well. The result is pretty spartan, but easy to work with.

By default, you have the following two tags available:

• ${title} … The title of the document

• ${content} … The entire contents of the document

• ${filename} … The name of the source text file, i.e. index. You can display a different image for each web page if the image has the same name as the web page, like <img src="/images/${filename}.gif">

• ${filedate} … The last modification date of the file (as returned by the build file system). This is typically used like ${filedate?string("EEEE, MMMM e YYYY")} … you can probably guess what that means, but if not, you can read all about it.

Right now, it is time for you to go forth and play. Manipulate the template and rebuild the site. I should mention that if you change the template, you will need to execute ant clean first … otherwise, the build process may not process all of the content files.

5. Sidebars and Meta Content

That isn’t too shabby, but a web site isn’t just about content surrounded by beautiful graphics… well, some are. Let’s suppose we have a template with two columns. The main column will contain the actual content, but the second will contain other stuff. But this other stuff is not constant across all web pages, but changes with each one.

Let’s call it a “call-out” and in our case, it will be a quote from the content, but displayed outside of the regular content area. Yes, it is time to introduce some new features.

In one of your text files, add the following to the end of the file:

sidetext=The lazy dog jumped over the cow.

This line is actually not included in the ${content}, but is available to the template engine as ${sidetext} (or whatever the initial text before the equal sign is).

Go ahead and try it. Add that line to the bottom of the datafiles/index.txtpage and rebuild your site. Now look at the web/index.html page and you’ll notice that phrase on the right side of the page.

You can create and use as many of these lines as you want. It is generally a good idea to make their use conditional in your template engine. For instance, you would do something like ${sidetext?if_exists}

For instance, my template file allows you to have the text file contain a footer=blah line, but if it doesn’t, it creates a default line.

6. I Don’t Like Text

You may or may not like text files as the basis of your web site, but even if you do, there are times that it isn’t enough. Granted, you can type any HTML content you want in these text files and they come across unharmed.

But you can create simple HTML pages in DreamWeaver or your favorite web editor and save them off in that directory with an extension of .htm and they will get merged with the template just fine.

How do I do the sidebars? You simply add the content for sidebars as <meta...> tags, as in:

<meta name="sidetext" content="That old dog..."/>

And any of these are now accessible in your template.

6. I Don’t Like XXXX

While I won’t get into it in much detail, if you aren’t fond of Markdown, you can use Textile instead. You just change the extension of your files from .txt to .text. If you want to use a Wiki-oriented formatting system, you can, but you’ll have to create a plugin for my Ant task.

If you aren’t fond of using FreeMarker for the template system, you use either Velocity or StringTemplate. You just need to edit the build.xml file, and change the engine="FreeMarker" line… and then create or change the template file.

If you have another template engine you’d rather use, you can, once again, create a plugin for my Ant task. It isn’t that involved, but if programming isn’t your thing, you could drop me a line and see if you can talk me into adding it.

If you don’t like my naming convention (like my choice of datafiles or web), you can edit the build.xml file and muck about to your heart’s content.

6. What’s Next?

I haven’t finished illustrating all of my initial requirements, so the next step would be for you to read Part 2 of this tutorial. For in my sequels, I will describe creating dynamic navigational bars and whatnot.

However, what I have described should be sufficient for a lot of web sites, but I will leave you with one final, and quite boring, step…

7. Investigating the Directory Structure

Let me explain a bit about the directory structure you see.

build.xml

This is the Ant build script and is used to “do the work” described above. This build script is really just an example, but it just might be fine enough as it is. If you want to use a different template engine or something like that, however, you’ll need to modify it.

datafiles

This directory contains all of the “source” text files. The contents of these files will be used to create each web page. You’ll notice index.txt will be used to create index.html.

templates/default.ftl

This is the default template that all the text files will be “run through” in order to create each web page. It uses the FreeMarker template format, but should be pretty easy to figure out.

templates

The templates directory also includes other supporting files and directories, like the styles directory (containing the CSS file) and an images directory. Any other supporting file can be drop in this directory and it will be copied over to the final web site directory.

support

Jar library files needed to build the web site are in here as well as a couple of Perl scripts from John Gruber. Markdown is used to convert text files into simple HTML content, and SmartyPants is used to introduce curly quotes and other typographical features to HTML files.

The org-howardism-ant-1_3_1.jar is actually my code that binds all of this together. This Jar file contains a number of Ant “task” extensions that marshall these libraries together. Yeah, it’s not rocket-science, but pretty useful.

All of the files in this directory are open source and freely available… including my own.

Once you have built the web site, you see a couple of other directories that are created:

tmp/htmldata

Text files from the datafiles directory are converted into simple HTML files and dropped into this directory.

tmp/web

Each file from the tmp/htmldata directory is run through the SmartyPants script filter and dropped into this directory. The conversion changes all " and ' characters into their curly version.

web

Each of the simple web pages in tmp/web are merged with the default.ftl template page and the resulting “complete” web page is dropped into this directory. This directory is the complete web site, and can be copied directly to your web server for display.