The configuration process involves defining a number of parameters for turning a specific source website into a static version — it’s location, whether it requires a login, and so on; and how the static version is to be created, refined and deployed. To complement these settings, there are more general runtime options; the settings as a whole come under options management.

Parameters are generally of the following type

• yes/no — it suffices to enter y or n
• a command line option, which generally starts with a hyphen (-)
• a file name, folder name or URL
• other strings, such as usernames and port numbers

Validation is carried out for each parameter depending on type.

List of Options

(as at version 0.30.12)

url

Example: https://example.com
The URL (web address) of the website being snapped. MakeStaticSite originally expected the site to be served from the web root, but more recently support has been added for a general URL such as https://example.com/research/. Redirects are supported, which will update the value of url accordingly

require_login

Example: no
Does the site require a login (y/n)? If your website requires you to log in with a username and password (typically, via a web form), then enter ‘y’ otherwise ‘n’.

login_path

Example: /wp-login.php
Path to login page with respect to the web root, i.e. omitting host and starting with a slash. The default setting is for WordPress.

logout_path

Example: /wp-login.php?action=logout
Path to logout page with respect to the web root, i.e. omitting host and starting with a slash. The default setting is for WordPress.

login_user_field

Example: log
This is the username field, not the username itself, in the web form used for submitting login credentials. It can usually be gleaned by viewing the HTML source of the login page. The default setting is for WordPress.

login_pwd_field

Example: pwd
This is the password field, not the password itself, in the web form used for submitting login credentials. It can usually be gleaned by viewing the HTML source of the login page. The default setting is for WordPress.

cookie_session_string

Example: wordpress_logged_in,wordpress_test_cookie
Comma-separated list, typically comprising name-attribute substrings, denoting a valid login session. The default setting is for WordPress.

site_user

Example: username
The password for the username just supplied. If preferred, a dummy value can be entered and then the configuration file edited manually after the setup is complete and before running makestaticsite.sh.

site_password

Example: password
The URL (web address) of the website being snapped. Currently, it is expected that the site is served from the web root. A port may optionally be given.

ssl_checks

Example: no
Validate certificate in encrypted (SSL/TLS) connections (y/n)? If you trust the SSL certificate of the site for which you are making a static version, then enter n. Otherwise, enter y and when asked below about wget_extra_options, provide the path to the certificate: --ca-certificate={the_cert_file_path}.

asset_domains

Example: cdn1.example.com,cdn2.example.com
Additional domains for asset retrieval and offline access. Please provide a comma-separated list of domains or subdomains, typically hosted on CDNs, for static assets stored external to the main domain. MakeStaticSite can retrieve these and incorporate in the mirror output. Leave empty when there are no extra domains.

page_element_domains

Example: auto
Additional domains for assets that contain embedded content and/or contribute to the styling of a page. These typically include fonts, CSS, images and other multimedia, provided by 3rd-party services. MakeStaticSite can retrieve these and incorporate in the mirror output. Enter ‘auto’ (without quotes) to generate this list automatically, in which case exceptions may be specified using the --exclude-domains option in wget_extra_options. Leave empty if all these elements are located under your primary domain.

wget_extra_options

Example: -X/wp-json,/wp-admin --reject xmlrpc*,'index.html?'*
This means /wp-json and /wp-admin directories are excluded from download, whilst links with suffix xmlrpc and containing index.html? are not followed.
To add further options, write them as you would usually for wget. For example, if page_element_domains=auto, then to prevent recursive downloads from foo.com and bar.net, use --exclude-domains foo.com,bar.net; when url includes one or more directories, use --no-parent to prevent the download of pages from parent directories. To limit the download rate to N kilobytes/second, add --limit-rate=Nk; to specify path to a certificate file: --ca-certificate={cert_file_path}. Otherwise leave empty.
Additional command line options for wget in addition to those specified in constants.sh are currently:
--mirror --convert-links --adjust-extension --no-check-certificate.

input_urls_file

Example:
Name of Wget input file (or file path) for custom crawl URLs. This might include sitemaps (XML files) or custom CSS or JavaScript files that are not linked directly from a page. List their URLs in this file so that Wget can capture them. Otherwise leave empty.

wget_extra_urls

Example: no
Use Wget to retrieve additional assets from domain (y/n)? This option will attempt to retrieve further assets by searching each downloaded file for further URLs and then re-running wget, using the same options except that existing files will not be overwritten (no clobber).

site_post_processing

Example: yes
This option will attempt to further refine the output generated by Wget, i.e.: convert further absolute paths for url_base to relative paths; replace remaining occurrences of the source domain with deploy domain; and convert feed files and references from index.html to index.xml. Note that the method of search and replace is blunt — all occurrences will be replaced!

archive

Example: yes
Add the mirror site to an archive (y/n)? If selected, this option means that each snapshot with Wget is saved in its own date/time-stamped directory.

local_sitename

Example: examplewebsite
Directory name for the mirror site and stem of zip file. If not already existing, a new directory with this name will be created inside the mirror/ directory. It will also provide the stem of the name of the zip file. This is actually a placeholder as a suggestion based on the URL’s host portion will be generated during setup.

wp_cli

Example: yes
Use WP-CLI to carry out tweaks on WordPress database (y/n)? Use WP-CLI to update the WordPress database configuration so that it generates pages amenable to Wget. WARNING: these changes happen immediately and currently cannot be reversed by MakeStaticSite. Choose no for updating WordPress some other way (e.g. manually through the dashboard) or if the site is not using WordPress.

wp_cli_remote

Example: no
Use WP-CLI also on a remote server (through ssh) (y/n)? WP-CLI supports remote connections over ssh, though this depends on the remote version and the remote shell.

source_host

Example: examplehost.net
The server hosting your WordPress site — ip address or domain.

source_protocol

Example:
Internet protocol (if any) to interact with the source (server) hosting the WordPress site. If the site is local to your machine, then leave this empty. If on a remote hosting provider, in the Cloud, then this is typically ssh.

source_port

Example: 22
The ssh port for the source, which is usually 22, but will likely need changing if port forwarding is used.

source_user

Example:
The user account on the remote host (assumes the use of ssh private-public key pair). Leave blank if accessing locally.

site_path

Example: /var/www/mywpdirectory
Full path to WordPress directory, which is commonly inside the Web root, e.g. /var/www/somedirectory.

wp_helper_plugins

Example: yes
Try to install WordPress plugins to configure site snapshot (y/n)? For Wget to properly create a static snapshot of WordPress, a few options need to be configured. These can be carried out by plugins. Otherwise, they can be configured manually.

add_search

Example: yes
Add a static search function (y/n)? Adds the WP Search Offline plugin (beta), a drop-in replacement for WordPress search that works offline (no Internet needed).

wp_restore_settings

Example: no
Restore WordPress settings to those before makestaticsite was run (y/n)? N.B. Not yet implemented.

use_snippets

Example: no
Use snippets to create page variants (y/n)? After Wget has created the mirror, use snippets to create variants of selected pages. They will be included in the zip file and/or deployed site, depending on the respective options. See separate documentation for instructions on their creation.

upload_zip

Example: yes
Create a zip file for distribution with the static website (y/n)? If selected, a zip file of the static snapshot will be created and added to a folder for distribution. It is suitable for offline browsing.

zip_filename

Example: website.zip
Zip filename for static snapshot. This can be named for specific distribution purposes. This is actually a placeholder as a suggestion based on the URL’s host portion will be generated during setup.

zip_download_folder

Example: download
Storage location for zip download relative to the website root. For WordPress, this might be where it usually stores files, i.e., wp-content/uploads.

deploy

Example: no,yes,yes
Deploy the output on a server (yes or no)? Deployment can be on a remote server (rsync over ssh) or on a local server, e.g. on your development machine. Since the introduction of setup run levels in version 0.24, this is a triple, one for each level.

deploy_domain

Example: mydomain.com
Domain name for the static web site that you are deploying, which will be used to help ensure that non-static and non-HTML elements are properly delivered. This is usually distinct from the domain of the host server.

deploy_remote

Example: yes
Deploy to a server on a remote host (y/n)? Indicate ‘yes’ for deployment on a remote server (as with a hosting provider) or ‘no’ for locally, e.g. on a file system on or shared with your development machine. Currently, if you wish to deploy both locally and remotely, then you can set up separate configuration files.

deploy_remote_rsync

Example: yes
Do you wish to deploy using rsync over ssh (y/n)? Indicate ‘yes’ for deployment to a remote server using rsync over ssh.

deploy_host

Example: examplehosting.net
Host (IP address or domain) for deploying the static site remotely. Leave empty for deployment on local filesystem. This is not generally the domain name for your site (which you can enter later).

deploy_port

Example: 22
For use with rsync, the ssh port on the deployment server, which is usually 22, but will likely need changing if port forwarding is used.

deploy_user

Example: username
For use with rsync, account username on remote host, where the static site is being deployed. Leave empty for deployment on local filesystem.

deploy_path

Example: ~/webs/staticwebsite
Path for deploying the static site on the hosting provider.

deploy_netlify

Example: yes
Deploy the output on Netlify (y/n)? Indicate ‘yes’ for deployment on Netlify using its command-line interface. This assumes you have a Netlify account and have set up a site (and logged in).

deploy_netlify_name

Example: netlify-name-12abc3
Netlify site name — when first issued, the default format comprises an alphanumeric sequence that includes a couple of human-readable words. The name can be changed in Netlify’s site administration panel.

htmltidy

Example: yes
Clean up mirror output using HTML Tidy (y/n)? Option to clean up HTML output for better conformance to W3C standards with further cosmetic options such as ‘pretty print’. This will may require installing the application first.

add_extras

Example: no
Add additional files to the static output (y/n)? Option to supplement the static snapshot with further files sourced from elsewhere. They may include non-static files such as scripts to reinstate essential functionality. Please place them in the $extras_dir/ directory.

Process

When you run setup.sh (without specifying the -l argument), you will first be asked to choose the run level. This determines the level of questioning (and thus customisation). Currently there are three levels:

0 — Minimal setup, suitable for sampling or archival. Currently, this only requires a URL to be entered, will all other options being generated automatically.
1 — standard customisation options, including basic deployment.
2 — full customisation for fine-tuning options, including Wget parameters.

The first option enables a quick impression of what MakeStaticSite offers, from which it should be easier to explore successively greater customisation in levels 1 and 2. The actual sequences of questions will depend on answers given previously. For example, if you opt not to deploy, then you won’t be asked about deployment host or port.

Once you have completed the set of questions, the setup will echo your settings to the terminal for you to review. It will look something like:

################################################
# Configuration file for makestaticsite.sh
# generated by setup.sh
# Created: 2023-01-20 14:46:56 UTC
# Last modified:
################################################

url_base=https://example.com           # url of website being snapped
require_login=n                        # Does the site require a login (y/n)?
ssl_checks=n                           # Validate certificate in encrypted (SSL/tls) connections (y/n)?
wget_extra_options=-X/wp-json          # Additional command line options for wget
input_urls_file=                       # Name of wget input file for custom crawl URLs
wget_extra_urls=y                      # Use wget to retrieve additional assets from domain (y/n)?
wget_post_processing=y                 # Make additional asset URLs relative (y/n)?
archive=y                              # Add the mirror site to an archive (y/n)?
local_sitename=examplewebsite          # Directory name for the mirror site and stem of zip file
wp_cli=y                               # Use WP-cli to carry out tweaks on WordPress database (y/n)?
wp_cli_remote=n                        # Use WP-cli also on a remote server (through ssh) (y/n)?
site_path=/var/www/mywpdirectory       # Full path to WordPress directory
wp_helper_plugins=y                    # Try to install WordPress plugins to configure site snapshot (y/n)?
add_search=y                           # Add a static search function (y/n)?
use_snippets=y                         # Use snippets to create page variants (y/n)?
upload_zip=n                           # Create a zip file for distribution with the static website (y/n)?
deploy=y                               # Deploy the output on a server (y/n)?
deploy_remote=y                        # Is the server on a remote host accessible via ssh (y/n)?
deploy_host=examplehosting.net         # Host (ip or domain) for deploying the static site
deploy_port=22                         # ssh port on deployment server
deploy_user=username                   # Username (for remote host)
deploy_path=~/webs/staticwebsite       # Path for deploying the static site
deploy_domain=example2.com             # Host (ip or domain) for deploying the static site
htmltidy=y                             # Clean up mirror output using HTML Tidy (y/n)?
add_extras=y                           # Add additional files to the static output (y/n)?


Do you wish to write this configuration to a file (y/n)? 

You can then confirm whether or not you are happy to save these settings. If you agree, then the output is stored in the config/ folder as a file with .cfg extension. You can subsequently edit this manually for each run (currently, the setup script does not support editing, though it might do in a future release).

Next, we review the runtime options.