Appearance
When you adopt minimal computing, most problems come from three sources: broken base paths on deployment, dependency drift that breaks old builds, and "scope creep" that quietly reintroduces the heavyweight stack you were trying to avoid. The fast diagnosis is to check the failing layer in order — local build, deploy path, then asset weight — and the durable fixes are pinning versions, enforcing a page-weight budget, and pushing heavy media off the static site entirely.
What problem is minimal computing actually solving?
Minimal computing chooses the lowest-resource approach that still meets the scholarly need, prioritising longevity, access on poor connections, and maintainability over features. Trouble starts when teams treat "minimal" as a vibe rather than a measurable constraint. Define it numerically: a page-weight budget, a maximum dependency count, and a "must still build in five years" rule. Once it is measurable, every problem below has a clear pass/fail test.
Why does my static site break only after deployment?
This is the single most common error, and the root cause is nearly always a base-path mismatch. The generator builds links assuming the site root is /, but a project page lives at /repo-name/.
yaml
# Jekyll _config.yml for a GitHub Pages project site
baseurl: "/my-archive" # the repo name, with leading slash
url: "https://user.github.io"js
// Eleventy / Vite equivalent
export default { base: "/my-archive/" }Diagnose it by opening the browser console: a wall of 404s on CSS and JS that point at the domain root confirms it. Always reference assets through the generator's link filter, never with a hand-written absolute /css/... path.
Why did a build that worked last year suddenly fail?
Dependency drift. An unpinned gem, npm package or base Docker image updated and broke compatibility. The fix is to make the build reproducible:
- Commit the lockfile (
Gemfile.lock,package-lock.json,poetry.lock). - For containers, pin by digest, not tag:
python:3.11-slim@sha256:...rather thanpython:3.11-slim. - Record the generator version in your README and CI config.
bash
# reproduce the exact environment that built the site
bundle install --frozen # fails if Gemfile.lock is out of date
# or
npm ci # installs strictly from package-lock.jsonnpm ci (not npm install) is the troubleshooting command: it refuses to silently upgrade anything.
How do I keep a minimal site from quietly becoming heavy?
Scope creep is a slow failure, not a crash. A "small" map widget pulls in a tiling library, an analytics snippet, a web font, and suddenly each page is 4 MB. Enforce a budget in CI so the regression fails the build:
bash
# fail if any built HTML page plus its assets exceeds 1 MB
find _site -name '*.html' -printf '%s %p\n' | awk '$1 > 1000000 {print; e=1} END{exit e}'| Symptom | Likely cause | Durable fix |
|---|---|---|
| Page weight creeping up | added framework/fonts | page-weight budget in CI |
| Slow on mobile networks | unoptimised images | responsive srcset, AVIF/WebP |
| Build time ballooning | thousands of media files in repo | move media off-site |
| One widget needs a big library | feature overreach | vanilla JS or progressive enhancement |
Can minimal computing scale to a large collection?
Yes — the trick is separating the lightweight site from heavy media. Keep the static site as metadata, descriptions and links; serve the 50,000 images through a IIIF endpoint or object storage. The page stays under a megabyte whether the collection holds 500 items or 500,000, because the images load on demand from a service built for them.
A repeatable troubleshooting order
- Does it build locally with the frozen lockfile? If not, fix dependencies first.
- Do assets 404 after deploy? Fix the base path.
- Is any page over budget? Find the new heavy asset and remove or defer it.
- Is the repo bloated with media? Move it to IIIF/object storage.
- Re-run CI; a green build with the budget check is your definition of "fixed".
Key Takeaways
- Define "minimal" numerically — page-weight budget, dependency cap, five-year build rule — so problems have pass/fail tests.
- The number-one post-deploy failure is a base-path mismatch; set the generator's
base/baseurlto the subfolder. - Pin versions in lockfiles and pin container images by digest to defeat dependency drift.
- Use
npm ci/bundle --frozento reproduce the exact build that once worked. - Enforce a page-weight budget in CI so scope creep fails the build automatically.
- Scale by hosting heavy media via IIIF or object storage, keeping the static site light.
Frequently Asked Questions
What counts as 'minimal computing' in digital humanities?
Minimal computing means choosing the lowest-resource approach that meets your scholarly need — typically static sites, plain-text formats and few dependencies — to maximise longevity, access and maintainability rather than features.
Why does my static site work locally but break when deployed?
Almost always a base-path mismatch. Static-site generators assume the site lives at the domain root; on GitHub Pages project sites it lives in a subfolder, so set the baseurl/base option to your repo name.
Is minimal computing the same as 'no JavaScript'?
No. It means minimal dependencies and resource use, not zero interactivity. A small amount of vanilla JavaScript or a tiny library can be perfectly minimal; pulling in a 300 KB framework for one widget is not.
How do I stop a minimal site from growing into a heavy one?
Set an explicit page-weight budget (for example under 1 MB per page) and add a CI check that fails the build when assets exceed it. A budget you enforce automatically is the only one that holds.
My build worked last year and now fails — what changed?
Usually an unpinned dependency updated underneath you. Pin exact versions in a lockfile (Gemfile.lock, package-lock.json or a container image digest) so the build is reproducible years later.
Can minimal computing handle a 50,000-image collection?
Yes, by separating heavy media from the site. Host images via a IIIF server or object storage and keep the static site as lightweight metadata and links, so the page weight stays low regardless of collection size.