Statically Generated Site

Summary

A research website should be rendered to plain files ahead of time and served with no application running behind it. This pattern is for HASS research software engineers and researcher-coders who need a project site, documentation set, methods guide, data catalogue, or exhibition to stay alive and trustworthy for years on a small budget.

Recommendation	Why?
Generate the entire site to static files during a build, and serve those files with no runtime application or database in the request path.	Removes the running server, the database, the burden of security patching, and shrinks the security attack surface to a set of files on a host. This supposed simple and portable hosting options beyond the life of a project.
Treat any dynamic behaviour as a deliberate, bounded addition rather than the default.	Stops a single interactive feature from dragging a server, and its whole maintenance burden, back into the foundations. Keeps the sustainable core sustainable.

Context

The content this suits can be known at build time: project and group sites, documentation, methods and data guides, data catalogues rebuilt on a schedule, and digital exhibitions. It suits small teams with little or no operational capacity, short funding horizons, and the common research reality that the person who built the site will eventually move on. Sustainability and maintenance, repeatedly named in the sector as the hardest problem, are the forces this pattern exists to address.

It does not suit sites whose core is per-request server logic, such as authenticated dashboards over live data, large-scale user-generated content, transactional systems, or data so volatile that no acceptable rebuild cadence can keep the published site honest. Where only a small part of a site needs live behaviour, the pattern still applies to the rest; isolate the dynamic part rather than abandoning the static core.

The structural prerequisites are modest. Content must be expressible as files or fetchable at build time, and a build step must be able to run somewhere, whether on a maintainer’s machine or in automation.

Usage

Render every page during a build. Derive the published HTML, styles, and assets from sources (content files, data, and templates) in a build step that runs to completion and emits a tree of static files. Nothing about serving a page should require computing it again.

Keep the runtime a plain file server. Serving a request means returning a file that already exists. Hold no application process and no database in the request path, so that there is nothing to crash, patch under pressure, or exploit at runtime.

Treat the build output as disposable and the sources as the truth. The generated site is an artefact that can be reproduced at any time from version-controlled sources, which means a lost or corrupted deployment is a rebuild rather than a recovery. This decoupling of content from presentation is developed further in the sibling design pattern on structured content.

Keep the host interchangeable. Because the output is just files, depend on nothing that a particular host alone provides. Portability answers the common institutional reality that a given hosting platform may be blocked, deprecated, or disallowed by IT policy: the same artefact can be served from another host without change. The mechanics of building and deploying are developed in the sibling implementation pattern on git-native continuous deployment.

Add dynamism at the edges, on purpose. Where interactivity is genuinely needed, push it to the client through progressive enhancement, confine it to small islands of interactivity that hydrate independently, or call a clearly bounded external service from the browser. Keep the substrate static so that the dynamic feature is a contained exception rather than a return to a server-rendered application. This approach reinforces FAIR reuse and longevity, since the durable record stays in plain, portable files.

Rebuild when sources change, and check before publishing. Trigger a rebuild on change rather than editing the live site, and use the existence of a build step to validate content, catching broken links, schema violations, and accessibility regressions before anything reaches a user. That quality gate is developed in the sibling process pattern on build-time validation.

Implementations

Australian exemplars can be found in Tim Sherratt’s GLAM (galleries, libraries, archives, museums) projects, which between them cover the content types this pattern names. The GLAM Workbench, focused on Australian and New Zealand collections, is itself a static site built with Material for MkDocs and archived under a citable DOI. Its companion Trove Data Guide is a static methods guide built the same way. For exhibitions, Sherratt’s collectionbuilder-gh-trove is a customised CollectionBuilder-GH template: CollectionBuilder is a Jekyll-based framework from the University of Idaho Library that turns a metadata spreadsheet and a folder of objects into a site, and his adaptation feeds it from a Trove list via a GLAM Workbench notebook. It also shows this pattern’s “dynamism at the edges” in action with search, sortable tables, and Leaflet maps all run client-side over the pre-rendered data.

The highest-volume, most proven application is documentation. Much of the open-source ecosystem’s docs are built from source with a static-site generator’s such as Sphinx, MkDocs, Docusaurus and mdBook. The files are then through Read the Docs or GitHub Pages, exercising the full pattern (version-controlled content, rebuild-on-change, build-time checks) across countless projects and maintainer handovers.

This is the mainstream of the Jamstack model: pre-render to static assets at build time, serve them directly, and meet any dynamic need through bounded client-side calls. Exhibitions, docs, lab and group sites, project microsites, all share the constraint that makes the pattern work: a small team, a long expected life, and content that changes at human pace.

References

Models

The Jamstack architectural model is a useful reference for the pre-render-and-serve approach and its decoupling of content, build, and delivery. See What is Jamstack?.

Other resources

• Tim Sherratt’s GLAM Workbench is a long-running Australian/NZ example of a research toolkit and catalogue published as a static site. See GLAM Workbench (archived at https://doi.org/10.5281/zenodo.5603059) and the static Trove Data Guide.
• CollectionBuilder is a Jekyll-based framework for metadata-driven digital collection and exhibition sites. See CollectionBuilder and the CollectionBuilder-GH template.
• Sherratt’s Trove-fed adaptation is documented in the Trove Data Guide CollectionBuilder pathway.
• The RSE-CEP web site (this site) is an Astro-based implementation of this pattern.

Acknowledgments

This pattern draws on the sustainability and maintenance concerns raised by participants in the HASS and Indigenous RDC Community Data Lab co-design workshop, who repeatedly identified the long-term upkeep of research software, and the loss of systems when their builders move on, as the sector’s central challenge.