Implementation

Requirements

Use of the File System

A static web site that is structured hierarchically can use the file system as storage. There is no need to store the site in a data base system.

My approach is to store the site locally on a PC and then synchronise with the web server's file system using standard protocols and tools.

To fulfil the requirement that a site should also be usable locally, I always use relative links (=relative paths) within a site. The relative links for navigation are generated automatically.

How to Organise Files?

To ease maintenance, I keep all files of a web page in one file system directory and I do not store multiple pages in one directory, i.e. one web page = one directory. This organisation leads to storing other material pertaining to this web page in this directory as well, like pictures, graphics or other media files. In my view this greatly simplifies administration.

Conventions

I use the following conventions for file names:

File name Description
body.htm Page content files
trWNav.xml Auxiliary files with navigation information
index.htm Final web page files
trWSite.xsl Central XSLT style sheet file
client.css Central CSS style sheet file

Please find here further details about these files. The file names of these files can be changed in the central Python include file trwlib.py. For example, you might prefer the extension html over htm. If you change trwlib.py, you also need to adapt corresponding settings at the top of the XSLT style sheet trWSite.xsl.

Scripting

Python

I implemented the trgensit scripts in Python. I chose Python because it is available on many platforms and comes with a lot of powerful libraries. I have tested the code with Python 3.7 under Windows 10 and Python 3.5 under Debian 9 "Stretch" Linux.

XSLT

Ever since HTML can be fully XML compliant, XML tools can be used to manipulate web pages. For the generation of the final web pages, I chose XSLT. The XSLT transformation

Nota bene: the XSLT transformation is done locally and not on the web server.

As I wrote this, Python 3.7 does not come with a built in XSLT processor. Hence I chose the xsltproc executable which is available for many platforms.

I am aware of the lxml Python package, which provides XSLT functionality. A future version of trgensit might use lxml instead of xsltproc.

Choice

Another implementation option would be to store the navigation information in JSON format. You would generate trWNav.js files instead of trWNav.xml with analogous content.

The generation of the final index.htm files could then be done using Javascript or any other programming language and related libraries that support manipulating HTML/XML and JSON files. Functionally it would not make any difference though.

Uploading to the Web Server

trgensit can be used with any tool that uploads or synchronises content between a local PC and a web server. I recommend sitecopy.

Example: Using "sitecopy" to Upload to a Web Server

To automatically upload from the local file system to the web server, I use sitecopy. sitecopy allows to exclude files from uploading. I use this feature to avoid uploading the site building meta data files to the web server.

sitecopy is readily available on *nix operating systems. On Windows I use sitecopy under Debian run in the Windows Subsystem for Linux (WSL).