This site is built using a Jamstack architecture. In March 2021 I hadn’t even heard of Jamstack, but then I began investigating current approaches to delivering online documentation, and suddenly Jamstack was everywhere.

The “jam” in “Jamstack” stands for JavaScript, API and markup:

  • Markup refers to markup languages such as XML, HTML, Markdown, or reStructuredText in which content is created. I wanted to make use of AsciiDoc because it is easy to use and more powerful than Markdown. It’s also what the documentation site (to follow soon) will use.

  • JavaScript is used to enhance the user experience and differentiate Jamstack sites from the old-style static websites of the 1990s. JavaScript is also used together with APIs to link to back-end services.

  • APIs are used to outsource the provision of services to specialist providers. APIs are commonly employed for authentication, search, comment functionality, payments, and content management.

A key component of the Jamstack approach is the static site generator, which converts the content (markup) into HTML, adds in the CSS and JavaScript, and then generates all the site pages so that they can hosted by a service like Netlify. I chose Hugo for the following reasons:

  • I wanted to be able to use AsciiDoc to create content (specifically, blog posts) and Hugo offered support for AsciiDoc, using AsciiDoctor.

  • My limited investigation suggested that Hugo was relatively easy to work with (although Gatsby certainly had its fans).

  • Hugo promised to integrate easily with Netlify, which I had already settled on as the hosting system.

Combining all of this, we have a solution architecture that looks like this:

Diagram showing changes previewed on Hugo Server,then pushed to GitHub,triggering a build deployment on Netlify.
Figure 1. Website architecture

  1. Content can be created using any text editor. My preferred environment is IntelliJ IDEA Community edition with the AsciiDoc plugin.

  2. The Hugo server running on my laptop detects whenever changes to the site project are saved, and immediately rebuilds the local preview site.

  3. Periodically changes should be committed to the local Git. The site folder must be initiated as a Git repo.

  4. Changes are pushed to the remote Git repo. In the case of this site, that’s on GitHub.

  5. When a changes is pushed to GitHub, this is detected by Netlify. The Netlify build environment is instantiated with the necessary components (Hugo, Asciidoctor and so on) and the site is generated.

  6. The site contents are then pushed to Netlify Edge.