Launch of MakeStaticSite.sh Website

November 2022: A website dedicated to MakeStaticSite is now available at https://makestaticsite.sh/. It provides the latest version of the software, released under AGPL, along with various documentation to help getting started.

Motivation

The process of developing this website has evolved considerably. On setting it up a few years ago in the conventional manner using WordPress, I duly familiarised myself with routines for maintaining security and improving performance on a hosted platform. However, there were several aspects that weren’t ideal: the live content was hosted remotely, albeit with backups; updating the site in situ, particularly for major redesigns, was inconvenient; and performance wasn’t always as good as expected. Observing that most of the content was not dynamic in nature, I resolved to develop the site locally and then, as a separate process, deliver it as a largely static site.

The rationale for generating static sites has been around a long-time; I first tackled this more than 20 years ago, when I needed to generate a CD ROM from a CGI/Perl multimedia website. Nowadays, the field is mature; a Netlify blog post (Netlify is a cloud-based service where many static outputs end up) gives many valid reasons, rooted in the need for more responsive work processes. Typically underpinned by a simple language called markdown, there has been a surge in solutions; hence, options for Jamstack abound. However, the processes tend to be heavily oriented to developers at the expense of content authors, issues I know first-hand from enabling web access to museum collections.

I wanted instead to support existing content management processes, i.e. to continue with creating and managing content in WordPress, and then ‘at the press of a button’ generate and publish a static copy online. There are already some solutions, including dedicated plugins such as Simply Static. Tim Nash, having observed increasingly complexity with the Jamstack options, has described how he used WP2Static via WP-CLI, the WordPress command-line interface, for a (relatively) simple and compact solution. But I hesitate over the use of a WordPress plugin to generate the static site. Apart from the ongoing issue of maintenance and compatibility with WP Core, plugins are not really necessary since a public-facing website should be de facto crawlable by a web spider and not require internal system information.

And so I turned to general-purpose tools I could run from the command line. Enter Wget, a ubiquitous utility for retrieving and packaging any number of web pages for subsequent viewing. I needed to configure it, add a few additional inputs, and then choose where to store the outputs. This led naturally to delving into (Bash) shell scripting to bring it all together and I continued the process, adding deployment options and invoking more commands, particularly WP-CLI to prep the WordPress output (and to include a version of the plugin, WP Static Search, revised to work offline). If you examine the source code of this page, you will see the result.

Pipeline

Shell scripting became a means to orchestrate the overall process, which is readily seen as a pipeline comprising a sequence of phases. For example, one phases runs wget for the initial capture, whilst another re-runs wget to more completely capture a site. In fact, many core web development processes can be incorporated, such as replacing certain internal-facing pages or sections with alternative content; and invoking command-line tools for validation and streamlining output. As of version 0.21, there are ten phases altogether; and command-line options allow you to control the start phase and end phase.

The flowchart below illustrates an emerging pipeline (for the latest perspective, please refer to pages on workflow and phases).

Setup

Configuration dialogue

The first step is to run the setup.sh script, which guides the user in an interactive dialogue to specify a series of options.

Initialisation

Configure

The system reads and processes configuration options

• read runtime options
• read configuration file options
• prepare output layout

Prep the CMS

CMS-specific streamlining

Optionally use wp-cli to

• ensure nice permalinks
• remove query strings
• remote shortlinks
• replace with static search

(Currently WordPress-only, but modules could be developed for other CMS.)

Generate static site

Generate wget mirror (first run)

Run wget with the supplied configuration options

• optionally incorporate further input files
• optionally set up a zip files
• store the mirror in its own directory with timestamp

Augment static site

Further processing with wget

Run wget with the supplied configuration options to fill in gaps

• optionally crawl static files for further URLs
• Filter the URLs to retrieve only assets (multimedia files, etc.)
• Re-run wget on the additional URLs

Optimise static site

Further post-processing for deployment

Further post-wget processing

• convert feeds to be XML files and modify references accordingly
• Apply HTML Tidy to make more standards-compliant and use pretty-print (dependent on options)

An accessibility validator could be added here.

Create an offline zip archive

Create a custom zip based on the mirror

The mirror acts as the basis for a zip archive, ready for uploading with the site or other distribution channels.

Augment

Further additions

Optionally augment the static mirror with snippets, substituting chunks of HTML in particular places according to the use of snippet tags. These will augment the zip file also.
Additionally, allow the inclusion of further files that might not necessarily be static files.

Deploy

Finalise and deploy locally or remote

Optionally copy over additional

• Optionally copy over additional files, which might be scripts to provide missing interactivity
• Finally deploy on local or remote server using rsync

Extending the usefulness

MakeStaticSite is a prototype that was initially developed for individuals who are creating and maintaining websites on a personal computer. However, the question soon arose: how might a team of content authors and editors be supported? (The answer is: yes!)

For example, what if this site is to have multiple contributors? In this case, the most straightforward approach is to set up or continue hosting with a third-party hosting provider, in the usual way. This means those who are creating and managing content carry on as normal through the dashboard. The main change is to separate the editing environment from the public site, which can be achieved by restricting access by some means of web authentication. Then, run MakeStaticSite to deploy the static site to the public, whether on the server or remotely. This approach ensures continuity; the only additional consideration is how to initiate MakeStaticSite once changes have been made — from within the CMS or external to it?

An initial test has shown that once set up, the process of maintenance and deployment can be carried out entirely from within WordPress. This can be achieved by running the script under the terminal emulator WPTerm (MakeStaticSite has an option to run ‘unattended’, which makes default selections). This depends on appropriate support for MakeStaticSite on the server; for shared hosting, the versions of required components, particularly Wget, may be somewhat old and, of course, for any serious use with a third party, access to WPTerm should be properly secured as instructed. It’s preferable to keep the running of MakeStaticSite on a personal computer, an arrangement that has been used for fuengsin.org.

However, hosting with a third party means that the data is no longer immediately under our control; although a mixture of database replication and file synchronization can compensate, there’s some loss of independence. Perhaps a better solution lies in p2p networks, but that’s an area I have yet to explore …

For now, this tool serves my needs well and I hope it is helpful to others. Please refer to the MakeStaticSite project site for further information.

Foreword

The issues of Website security and performance continue to loom large, with organisations large and small continuing to suffer severe loss of service following a compromise — whether a site gets defaced, Google results become hijacked, or, more seriously, personal data is breached.

As will be described below, MakeStaticSite already offers a freely available solution (which has been implemented for this site), but it requires a certain level of technical knowledge. However, further development is on the way to provide a Web-based service that will be simple and easy to use. A proof of concept has already been implemented and been successfully tested, which should pave the way for business investment.

What’s the problem?

Security issues arise largely from the way the content is generated and delivered to site visitors using server-side processing, which typically involves scripts and databases to select and deliver specific text, multimedia, and so on. For example, content management systems (such as WordPress and Drupal) are based on PHP and MySQL, which, if misconfigured, might yield not only the desired pages but be open to requests crafted to subvert the setup and yield unintended access. Thus, maintaining the security of such a setup is an ongoing process that requires continual vigilance, responding promptly to security notices with the installation of updates, but it’s a race against time and there’s no guarantee that all vulnerabilities will be spotted.

MakeStaticSite belongs to the class of software known as static site generators, which removes all the dynamic components from public exposure, replacing them with a set of web pages (plain HTML, CSS, JavaScript) that require no server-side processing. The pages are prepared beforehand in a safer environment, such as an individual’s laptop or a shared space behind a firewall, protected by strict access controls. This simplifies the delivery process as well as helping with security. Shell scripting is used, making available various tools to handle different aspects of the task. An introductory post provides an overview of the processes involved.

For developers and system administrators, MakeStaticSite provides a convenient means to set up and manage the automatic creation and deployment of static versions of websites. Such sites can be administered locally and then deployed remotely to some other hosting provider. Strictly speaking, this is not an archival tool as the output is not an exact mirror, but a version of the site that preserves content whilst aiming to remain current. For example, RSS feeds are saved and then renamed with .xml extensions, and further files may be added.

Anyone who has some familiarity with the command line should be able to use the tool to assist in maintaining their sites, though such an interface is off-putting to some. Further, a scripting-based approach has been chosen to make this tool widely accessible for developers to further fine-tune; a number of refinements are already included that augment the standard use of Wget, such as support for arbitrary attributes and, in the case of WordPress, the use of WP-CLI to prepare sites beforehand.

MakeStaticSite has been released as open source software, available under the GNU Affero General Public License version 3 . For further details, please refer to the project site, makestaticsite.sh. Many thanks to various developers for sharing their knowledge on shell scripting, particularly on blogs and Q&A websites such as Stack Exchange and to those who have tested, commented on and otherwise supported MakeStaticSite.

Hosted Web Service

In its present form, it is technical in nature, aimed at developers and system administrators. However, as a further development, a hosted Web service is being developed, with a simple user interface.

The user logs in to a central dashboard to maintain their projects. By following a link or clicking a button, they can launch their CMS editor, build a static version of the site and browse the output.

How you can help!

At this stage, we are looking for investment. Please get in touch to try out the demo and to arrange for a presentation.

The generous ethos is admirable. Indeed, whereas the spotlight has recently been shone on software developers to become more aware of certain ethical issues, along with pressure to change their practices, there is in fact much to be learnt from that community. I have tried to intimate this in Open Sources: A Higher Consciousness in Software Development, a paper I gave at an unusual conference on the theme of wisdom.

As a developer myself, I am largely self-taught since the 1980s. It may explain why, when solving programming problems, I can be somewhat unconventional and occasionally original.

Open Source contributions

I’m not a prolific or fluent coder, but have contributed to a few open source projects and am currently working on two.

• MakeStaticSite, a static site generator and deployer, is a Bash script that I already use to generate static versions of locally-developed WordPress sites (like this one and research.siga.la). It is release as free/open source software under AGPL v.3 and is available for download.
• WP Offline Search is a further refinement of my fork of WP Static Search by Gergely Szerovay, who developed a WordPress plugin based on Lunr.js. As I’ve not received any response to my pull requests and have reworked quite a lot of the code, I changed the name and intend to set up a new repository.
• epubcheck-web (contributor) – enabling standards-based checking of ePub documents to help self-publishing, motivated by my experiences of self-publishing a Kindle book (see especially the EPUB conversion report slides).

I hope to share the Sigala code likewise, once it has reached a certain level of maturity.

For my work using other people’s software, take a look at the portfolio.

Legacy software, but enduring paradigms

At the turn of the millennium, there was no universal means for authors to edit and maintain their content through their web browser. The technical solutions that existed tended to work only on specific platforms, carried a fee, or else require a Java plugin.

In response, I devised one, NetWedit, possibly the world’s first cross-platform JavaScript-based solution, released under GNU LGPL, in the days when I still thought that the first ‘L’ stood for ‘library’ rather than ‘lesser’. It was experimental and used a crafty method, but it worked well enough for members of Oxford University’s Theology Faculty to maintain their profiles for a teach and learning resources database.

As browser DOM support improved, I subsequently enhanced the functionality, but kept the same basic user interface, to produce RTWedit, which was incorporated into early versions of WebLearn, Oxford University’s centrally-hosted virtual learning environment.

Standards have moved on and browsers only maintain limited backwards compatibility, so my tools don’t work in a standard desktop today, but the approach of working from first principles is ever-relevant. I’ve recorded some notes in a retrospective piece, Adventures in the Read/Write Web.

Nowadays, we take for granted the fact that we can write content in systems such as WordPress and Drupal using a rich text editor with an experience similar to that in a word processor. Such editors, based on packages such as TinyMCE and CK Editor are still written in JavaScript.