Options Management

MakeStaticSite supports working on concurrent projects, the number only limited by available resources (storage, memory, and so on). Each run of the main script, makestaticsite.sh, is governed by a set of options specified in two files: first in constants.sh and then the respective .cfg file. This two-tier mechanism follows the standard convention of assuming ‘global’ settings by default that can in many cases be overridden by ‘local’ choices, the user-specific options.

The settings are basically of two kinds: system-related, i.e. concerning MakeStaticSite and the system environment in which it is running; and site-related, concerning how the site is to be captured and processed. System settings can usually be left unmodified. The constants file contains both kinds, but the .cfg file contains only site-related options.

There are well over one hundred options and settings will differ from site to site; they might even vary between runs for a given site, which gives rise to potentially numerous permutations. To manage the complexity, in constants.sh, options have been grouped according to task, which we summarise below.

Task Groups

Options are loosely grouped together in constants.sh under subheadings.

  • MakeStaticSite info
    These are system variables, not user options, describing the software release.
  • Setup-specific settings
    These settings apply to the setup script, setup.sh. Again, there should be no need to change these.
  • Network settings
    All these system settings, apart from the last one, are regular expressions that approximate to IP addresses or domain names. They are used mainly for validation.
  • File and Layout settings
    These system settings are generally concerned with output, particularly file formats and permissions.
  • Credentials processing and storage
    This set of options relates only to sites that require authentication, as might be the case when generating static versions of content management systems, for which access restrictions are needed.
  • Wget settings
    Wget lies at the heart of the MakeStaticSite engine. As indicated in the subheading, these settings apply to phases 2 and 3, i.e., to multiple runs of Wget.
  • Capture and processing of asset URLS and paths
    These settings help determine the extent to which MakeStaticSite captures and incorporates external assets. To optimise the output of sites that make use of CDNs and generally more complex, some of these options may usefully be modified.
  • Directory management of downloaded assets
    These options are mainly to do with the resulting layout. By default, MakeStaticSite will try to make the output self-contained and portable, trimming excess directories.
  • Robot and site map settings
    These settings are geared towards publication or deployment as live sites. They can be ignored for archival only.
  • Wayback Machine settings
    These settings apply only to the case that the target is a Wayback Machine, as hosted on the Internet Archive at web.archive.org.
  • CMS-specific constants
    Largely a placeholder for more general CMS support.
  • WordPress-specific settings
    This section refers to a WordPress-specific module and lists various options designed to clean up the output before it is mirrored.
  • HTML Tidy settings
    These specify how HTML Tidy is to be applied to clean up the HTML markup in the output.
  • Display settings
    These system settings generate coloured output on terminals.
  • Cleanup settings
    This small section is for cleaning up the final output.
  • Other runtime settings
    This is a miscellaneous section of mainly system-related settings.
  • Site options
    These are user options, which provide the series of questions in setup, stored in the allOptions array. Each option has three components: a default value, a brief description, and a full description. (The slightly long-winded format is to support Bash 3, which doesn’t have associative arrays as a feature.)

Following the site options are various arrays that option dependencies and which ones can be overridden in .cfg files, which we discuss next.

Option overrides

When running setup.sh, the questions presented flow sequentially according to allOptions, and result in a configuration, stored in.cfg file. This file can be subsequently modified manually.

All the values specified in the .cfg file supersede those specified in constants.sh and additional runtime options may be set there, as listed in the array, options_nodeps_load. So, for example, whereas in constants.sh the default value of add_search is ‘yes’, you may decide for certain .cfg files to set add_search=no.

Furthermore, options_nodeps_load is itself editable, so options can be added and removed, as needed, with the caveat that in makestaticsite.sh, there are some options whose values depend on others, so that script ought to be checked first. Hence the label indicates ‘no dependencies’. Also, options that have yes/no values should also be listed in the array, options_check_yesno.

When maintaining a number of sites, the settings in constants.sh should converge to be more or less what is common to all, with variations mainly evident in the .cfg files, making for optimal management. In practice, most settings can probably be left as-is with just a few tweaks.

This page was published on 21 May 2024 and last updated on 21 May 2024.