FAQ – MakeStaticSite

(Or what might become ‘frequently asked questions’)

Q. Is MakeStaticSite really free?
Yes! You are free to use, re-use, modify and share. And this site doesn’t impose any financial charge.
Q. Does MakeStaticSite follow the Jamstack approach?
Whilst MakeStaticSite generates static output with an emphasis on workflow, it does not really follow the Jamstack architectural approach to site development. In the original styling of JAMStack, the ‘A’ stands for API, where the process of building the site typically uses APIs such as REST, JSON, and React, to retrieve data to assemble HTML files. Accordingly, Jamstack systems typically include code for working with APIs, particularly evident in headless CMS.
MakeStaticSite does not (directly) use APIs to generate such files, though the original source might do so, whilst the output can include JavaScript also utilising APIs. Nevertheless, MakeStaticSite might be included in the Jamstack list of static site generators. For more detailed discussion, see the page describing alternatives.
One further distinction: MakeStaticSite focuses more on portability, as explained in the online and offline discussion.
Q. Does it run on Microsoft Windows?
Not ‘out of the box’, but it can work if you install additional software that supports Bash, the shell command language on which MakeStaticSite depends. There are various ways to do this, probably the most convenient being the Windows Subsystem for Linux (WSL), which enables integration of GNU/Linux utilities with the Windows kernel. Other options include Cygwin and the use of a virtualization platform such as VirtualBox (numerous tutorials available online).
Q. Can MakeStaticSite be run from within a CMS?
There are no plugins or modules to support this directly. However, it may be possible to run the script through a plugin that provides some kind of terminal emulation. For WordPress, this may be achieved using the terminal emulator WPTerm; to support non-interactive shell commands, MakeStaticSite has an option to run ‘unattended’, making default selections. Of course, for any serious use with a third party, access to WPTerm should be properly secured as instructed.
Q. Can MakeStaticSite be used with a CDN?
Support for Netlify was introduced in version 0.22; this site is currently hosted there. As the standard output is entirely static, it should be amenable to being deployed to any Content Distribution Network (CDN) with some additional custom scripting.
If you wish to only serve certain assets, such as multimedia, from a CDN, then at present this needs to be implemented by the source site (web application). For WordPress, a few plugins are available. However, this shouldn’t be necessary for a totally static site.
Q. Does MakeStaticSite make a snapshot of the original layout?
MakeStaticSite uses Wget with several runtime options defined in wget_core_options: --mirror ensures that the static copy replicates the original folder structure, whilst further options, --convert-links and --adjust-extension, ensure close correspondence to the original filenames.
Q. For a Web CMS, does the output include administration folders?
MakeStaticSite will attempt to capture whatever pages and assets it can reach, subject to the constraints defined. Limiting factors include the server’s robots.txt file, which Wget will respect by default, and the site’s configuration setting, wget_extra_options.
You can define login credentials, whence Wget will capture pages visible once logged in, including any administrative dashboards. That’s not usually appropriate for public-facing sites, but note that it is useful to define a guest account with minimal privileges to grant access when a site requires a login for access; it can usually be configured to hide any admin pages.
Q. Does MakeStatic fetch copies of multimedia (MP3 and video files, etc.)? Can this be turned off?
As stated above, by default, the tool downloads everything that is reachable, including multimedia assets. To avoid (repeated) downloads of large files, you can exclude directories from being followed by including in the configuration setting, wget_extra_options, exclude_directories= (or -X) followed by a list of directories to omit from the crawl.
Alternatively, you choose to not have the files stored in the first place, but leave it to MakeStaticSite to copy them (once) from the extras/ folder. With the options supplied, rsync will leave alone any files that are already in place.
Q. Can MakeStaticSite be configured to control the depth of hierarchy?
MakeStaticSite can leverage a couple of different ways that Wget uses to control the extent that it crawls a site.
(1) In constants.sh, the default setting for wget_core_options specifies --mirror, a recursive retrieval option that specifies inter alia -r -l inf, i.e. recursive and an infinite depth level. This means it will attempt to retrieve content from as many subdirectories as it can find. To limit the depth, you can start by replacing --mirror, with the same set of options, except use -l 4, say, to go down four subdirectory levels.
(2)The second approach is to specify a crawl of a particular directory (and subdirectories). In a recently introduced (and hence experimental) addition, this can be done by supplying the full path to the configuration setting, url, e.g. https://example.com/research/
(note the trailing slash). Then, to ensure that parent directories are not crawled, you need to add -np (no parent) to wget_extra_options.
This is particularly useful when updating sites, using makestaticsite.sh -i somesite.cfg -m mirror_id.
Q. Is it possible to control the rate at which files are downloaded (to prevent denial-of-service)?
It’s good practice to moderate data requests when running makestaticsite.sh on a remote source. There are two wget options in particular that you can add to wget_extra_options: to limit the download rate to N kilobytes/second, specify --limit-rate=Nk (or -Nk); to restrain wget to retrieval requests at timed intervals, specify --wait N (or -w N) seconds.
Q. Is it possible to add a search tool?
Yes. With the growth of static site generators, there have emerged solutions that generate a search index and user interface that can be used offline. In particular, Pagefind is a command-line tool, which should make it amenable to integration in a MakeStaticSite workflow.