make-ing a Static Website

G. Wade Johnson has been maintaining the Houston.pm website for years. The original hosting for the site was located at pm.org and was maintained by volunteers. To reduce their work, they required all hosted sites to be static.

Wade had experience a couple of decades back generating static shells for small amounts of dynamic content. He applied similar techniques to the Houston.pm website to make it easier to maintain.

A Little History

• He took over maintenance in December 2004
• Originally hosted on the pm.org servers
• The pm.org servers only supported static content
• Recently began hosting it on servers he controlled
• Nov 2002 - mostly empty placeholder
• Aug 2003 - meeting schedule announced
• Dec 2005 - the first generated version

The site was maintained manually between December 2004 and December 2005.

Why a Static Site?

Many people have asked why the site is maintained as static HTML, instead of using a more modern framework or tool.

When he first took over the site maintenace, he did not know how long it would last. He did not want to start paying for hosting on something that he might not maintain for long. He figured it would pass to someone else after a few years. Additionally, the site itself had no compelling need for dynamic features. He also was only willing to spend a limited amount of time maintaining it.

At different times in the past, people have recommended converting to a CMS or Wiki to maintain the site. Both of these approaches would require work to convert the content that currently exists and on-going maintenance and security monitoring to keep them functional. Wade is not really interested in generating extra work for himself for dubious benefits.

Why Generate a Static Site

The first major rewrite of the site (2005) moved to the first version of the generating code.

The main reasons for generating the site are:

• Consistent look/style (such as it is)
• Code for creating new pages
• Site is under version control
• Based loosely on the results of his Masters Thesis

Since all of the generating code is in relatively straight-forward Perl 5 code, it should be easy for another maintainer to pick up. If anyone wants to make changes, they are free to send a pull request on github. If a change does not make his life harder, Wade says he will probably accept it.

The Code

At this point, Wade went to the source on GitHub and began walking through some of the core features.

There are a number generic templates in the templates/ directory. Some of these are fragments used by other templates. Others are more or less standalone templates. A number of templates are wrappers defining the general structure of certain pages:

templates/index_wrap.tt2

the main index page of the site

templates/main_wrap.tt2

any main page besides the index

templates/talks_wrap.tt2

the recent talks and year talks pages

templates/writeup_wrap.tt2

the talk write-up pages

Other core templates include:

templates/copyright.tt2

specifies the copyright notice on each page, handling appropriate year information and licensing

templates/main_menu.tt2

specifies the left-hand menu for the site

templates/recenttalks.tt2

page listing the most recent talks

templates/yeartalks.tt2

page listing all of the talks for a given year

The whole system is driven by a Makefile. The Makefile contains quite a bit of redundant information. This turns out not to be a big maintenance problem, because the Makefile is generated from a template (templates/Makefile.tt2).

Scripts

In the bin/ directory are a set of scripts that Wade uses to build the site. The bin/talks.pl script is used to convert the information from the talks.xml document into all of the yearly and recent pages. The bin/announce.pl script updates the atom.xml file which supports feed readers (if anyone still uses them). It also provides the message used to update the mailing list and such when announcing a new meeting. The bin/writeup.pl script helps in the construction of the write-ups for each meeting. Among other things, it

• asks the maintainer for information about the talk
• creates the appropriate directory structure
• leads through writing up the talk
• builds a TT file for the write-up

Legacies

Wade explained that there are some legacy bits due to the length of time this project has run. The talks.xml document is basically a database of the talks through time. Since the information is basically a series of short documents, it hasn't been worth any effort to turn it into a more traditional database. Some of the transformation work done to extract data from the talks file is performed through XSL files. This approach has mostly been abandoned, but was a viable system at the turn of the century.

Conclusion

The audience had a number of questions about particular design decisions. Some of the comments made valid suggestions of other design trade-offs. In the end, many of the decisions made on this system were simply what was easiest at the time.

We had 7 people attending this month. As always, we'd like to thank cPanel, L.L.C for providing the meeting space and food for the group.