---
pattern_id: A-001
slug: a-static-websites
title: Static websites
pattern_type: architectural
problem: Research websites need to keep working after project funding ends, staff move on, and web software becomes unusable
applies_when:
  - a site comprises a document, image, or other content edited by humans
  - content changes at editorial pace, rather than being generated dynamically
  - the site does not require server-side processing to serve pages
cluster: static-site
cluster_refs:
  - I-001
  - I-002
  - D-001
diagrams:
  - slot: architecture
    caption: "A C4-style container view of the build-time architecture, naming who acts: a content author and a developer feed the build, the author reviews the generated artefact, and a reader requests plain files from a host with no server or database in the request path."
keywords:
  - sustainability
  - static-site-generation
authors:
  - Mat Bettinson (ANU)
contributors:
  - name: Peter Sefton (ANU / UQ)
    roles: [reviewer]
  - name: James Smithies (ANU)
    roles: [technical_editor]
---

## Summary

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 remain live for years on a small budget. It describes how to build research websites that render to plain HTML at build time, rather than being generated dynamically when users access them. 

| Recommendation | Why? |
|----------------|------|
| When building a project website, generate the entire site to static files, and serve those files using a standard web server, with no runtime application or database. | Does not require a database or server-side code, removes the burden of security patching, and shrinks the security attack surface to a set of files on a host. This supports simple and portable hosting options beyond the life of a project. |
| Avoid dynamic behaviour that requires custom code unless necessary. When there is a clear case for dynamic code, implement it in a way that does not compromise the core of the site. | Prevents a single interactive feature from introducing server infrastructure and its maintenance burden to an otherwise sustainable architecture. |
| For dynamic features such as search, adopt client-side solutions via well-supported libraries and ensure the site still functions without them. | Well-tested libraries reduce the risk of JavaScript-based features. Treating them as optional ensures the site still works without them. |
| Adopt established static site generator tools rather than custom built tooling. | Well-supported and well-documented tools are easier to maintain, migrate, and hand over. |
| Implement a Data Management Plan for the site content, tooling, and the web published site itself. | Fulfils institutional requirements and ensures the persistence of assets beyond the end of a project. Even if the source content and code cannot be rebuilt into a site, static websites are easy to preserve and to deposit in archives. |

## Context

This pattern suits:

- Project and group sites, documentation, methods and data guides, data catalogues rebuilt on a schedule, and digital exhibitions. 
- Small teams with little or no operational capacity, short funding horizons, and high staff turnover.

It does not suit use cases that require computation, such as authenticated dashboards over live data, large-scale user-generated content, transactional systems, or frequently changing data.

It can be used in circumstances where a small part of a site needs live behaviour, if the dynamic part(s) of the site are isolated from the static core and designed to gracefully degrade.

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

## Usage

This pattern requires three components:
- A file-based workspace for content editing. This is usually a git repository backed by a git server such as GitHub, but could also be a file-sharing service such as OneDrive or Dropbox. Files are commonly plain text or markdown files, with images and other media, but could be structured markup languages or data.
- A static site generator tool to build the static website from the raw assets. There is a wide range of such tools available under open source licences, specialised for different kinds of website.
- A web server to host the site.


It also requires two processes:
- A way to trigger the build, ideally using an automated process triggered by changes in the content.
- A way for humans to review the build before publishing, ideally with additional automated checks such as continuous integration tests.

Consider the balance of static and dynamic elements carefully:
- Render every page during a build. Derive the published HTML, styles, and assets from sources (content files, data, and templates) to emit a tree of static files. Nothing about serving a page should require computing it again.
- The generated site should be considered an artefact you can reproduce at any time from version-controlled sources.
- Add dynamic features carefully, if at all. Where interactivity is genuinely needed confine it to small islands that hydrate independently, or call a bounded external service from the browser (see [Islands Architecture](#models) below). 
- 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 design pattern [Schema-Validated Structured Content].
- The mechanics of building and deploying are developed in the sibling implementation pattern [Git-Native Continuous Deployment].

::diagram[architecture]

## Implementations
Much of the open-source ecosystem builds its docs from source and serves them through [Read the Docs](https://about.readthedocs.com/) or [GitHub Pages](https://docs.github.com/en/pages). 

The pattern is also proven for TEI-based digital editions (common in the digital humanities), where XML sources transform to static HTML at build time. [Digital Humanities Quarterly (DHQ)](https://dhq.digitalhumanities.org/) has published TEI-encoded articles as static HTML since 2007, giving every article a permanent URL and demonstrating the sustainability argument across nearly two decades of continuous scholarly publishing.

In the commercial world the pattern is often referred to as [Jamstack (Wikipedia)](https://en.wikipedia.org/wiki/JAMstack). The Jamstack ecosystem includes [hundreds of implementations](https://jamstack.org/generators/) of static site generators and the tooling around them. Generators group into a three-way typology by what each assumes your content is:

- Prose-first (documentation generators): content is a navigable hierarchy of markdown/rST, supporting link integrity, cross-references, and API autodoc. Examples: [Sphinx](https://www.sphinx-doc.org/en/master/), [MkDocs](https://www.mkdocs.org/).
- Data-first (collection generators): input is structured metadata and data plus files. The sibling architectural pattern Collection-centred static website covers this approach in detail. Examples: [CollectionBuilder](https://collectionbuilder.github.io/), [RO-Crate-HTML](https://github.com/Language-Research-Technology/ro-crate-html-lite).
- Template-first (general-purpose generators): content shaped by author-controlled templates; full layout control. Examples: [Jekyll](https://jekyllrb.com/), [Hugo](https://gohugo.io/), [Astro](https://astro.build/).

Astro’s content collections blur this typology by validating structured content against a schema at build time.

The data-first route is proven in Australian HASS research. The [Precarious Oral Histories Catalogue](https://precariousoralhistories.com/project-database/) surveys at-risk oral history collections held by community organisations, libraries, museums, archives, and individuals, and was built by oral historians in the Australian National University team of the Language Data Commons of Australia. It is an RO-Crate rendered to a single self-contained HTML file, so the published survey is a plain file with no application behind it, and the structured metadata behind it remains the citable record.

## References

### Models

- The Jamstack architectural model describes the pre-render-and-serve approach and its decoupling of content, build, and delivery. See [Jamstack (Wikipedia)](https://en.wikipedia.org/wiki/JAMstack).
- Islands Architecture serves a primarily static HTML document while embedding isolated interactive widgets ("islands") that hydrate independently on the client. See [Jason Miller's blog post](https://jasonformat.com/islands-architecture/) and [Astro's elaboration](https://docs.astro.build/en/concepts/islands/).

### 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](https://glam-workbench.net/) (archived at https://doi.org/10.5281/zenodo.5603059) and the static [Trove Data Guide](https://tdg.glam-workbench.net/).
- CollectionBuilder is a Jekyll-based framework for metadata-driven digital collection and exhibition sites. See [CollectionBuilder](https://collectionbuilder.github.io/) and the [CollectionBuilder-GH template](https://github.com/CollectionBuilder/collectionbuilder-gh). Sherratt’s Trove-fed adaptation is documented in the [Trove Data Guide CollectionBuilder pathway](https://tdg.glam-workbench.net/pathways/collections/collectionbuilder.html).
- [The Victorian Web](https://www.victorianweb.org/) has served hand-authored static HTML since 1994, making it one of the longest-running humanities web resources and a canonical, if basic, example of the sustainable affordances of static sites.
- The RSE-CEP web site is an Astro-based implementation of this pattern.

## Acknowledgments

This pattern draws on sustainability and maintenance concerns raised by participants in the HASS and Indigenous RDC Community Data Lab co-design workshop. Participants 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.

<!-- References -->
[Git-Native Continuous Deployment]: /patterns/i-git-native-continuous-deployment/
[Schema-Validated Structured Content]: /patterns/d-schema-validated-structured-content/