Why I keep my portfolio in static HTML

The reader's task sets the scope

My portfolio has a straightforward job: help someone read about my work, inspect a project, find a repository, and contact me. The article body does not need a user account, a private database, or a personalized dashboard. I can deliver that reading experience as documents with shared styles and ordinary links.

This is not an argument against React or server-side applications. I use different tools for different project needs. The Book Buddy React and API workflow has a different interaction model from a page explaining that workflow. The project and its case study do not need identical infrastructure.

What is actually in this repository

My portfolio repository contains individual HTML pages, a shared styles.css, an images directory, robots.txt, sitemap.xml, and netlify.toml. Its Netlify configuration publishes the repository root. There is no package manifest that needs to install a front-end framework before these pages can be served. The repository is private; this article describes the implementation, while the deployed HTML, stylesheet, and public pages are available to inspect.

That makes a content change relatively easy to locate. The article text, headings, links, and page metadata live in the article's HTML file. The visual rules live in the stylesheet. Routing and response headers live in the hosting configuration. I can inspect each responsibility without first tracing it through a component framework.

The site still has integrations and browser behavior. Static does not mean that every resource is local or that nothing can fail. It means the core documents are already written before a reader requests them, rather than being assembled from account-specific data for that request. MDN's client-server overview explains that distinction.

A simple deployment still has a routing contract

A file name and a public address are not always the same thing. My public article URLs are extensionless, while the source files end in .html. The Netlify configuration uses redirects and rewrites to connect those forms.

A redirect sends the visitor to a different URL. A rewrite can serve a file while retaining the requested address. That difference matters when an old link is shared or someone bookmarks a page. I want one public destination, not several competing addresses that drift apart. The Netlify routing documentation describes the configuration behind this behavior.

Moving the HTML to another host would therefore be only part of a migration. I would also need to reproduce the important redirects, response headers, and domain behavior. Portable files reduce one dependency; they do not make the hosting configuration disappear.

Repeated markup is the real maintenance cost

The tradeoff becomes visible as the site grows. Navigation, footer content, author information, and parts of the metadata repeat across pages. Shared CSS can change their appearance centrally, but it cannot update the words inside every HTML document.

Adding an article also means maintaining its entry on the Blog page and in the sitemap. Forgetting one of those steps can leave a valid page harder to discover through the site's own navigation. This is a coordination problem, even without a complex build system.

I do not describe this approach as maintenance-free. I accept the explicit files while their responsibilities remain understandable. If repeated edits become the dominant task, a small templating or static-generation step would be a reasonable improvement. That is a possible next architecture, not something I claim this repository already uses.

Validation belongs outside the reading path

The repository already includes scripts/audit-images.mjs. It checks image references, descriptive alternative text, numeric dimensions, responsive-image candidates, and image sitemap entries. That script helps review content without adding a framework to the reader's page.

This separation is useful: I can use development tools to check an output while keeping the output itself straightforward. A local script can catch a missing file, but it cannot prove that the production server returns the right response. I still need to check the deployed page, the image, and the final URL.

I also avoid claiming that static HTML automatically guarantees speed, accessibility, or indexing. Large images can slow a small page. Poor navigation can make a simple document difficult to use. A successful HTTP response does not establish that a search engine has indexed it. Those outcomes need their own evidence.

What would justify changing the architecture?

I would reconsider the current structure if several people needed a publishing interface, repeated page edits became error-prone, or the portfolio gained substantial account-specific behavior. Those are requirements that could justify new tools. A desire to list another framework would not be enough by itself.

The smallest useful change might be generating shared navigation and metadata at build time while retaining static output. A more interactive application might need a different approach entirely. I would first identify the repeated failure or missing capability, then choose a tool that addresses it.

For now, this repository gives me a concrete architecture lesson: simplicity is a set of boundaries I maintain, not the absence of engineering. Clear files, deliberate links, explicit hosting rules, and verifiable public output can serve a professional portfolio well.