I've been maintaining my personal website as plain HTML for five years now. I must say, I quite like this method. There's no substitute for practice when it comes to maintaining your skills at editing HTML and CSS.
Yes, you must copy and paste content and not having layout page is annoying at times. But the overhead of just doing it yourself is surprisingly small in terms of the time commitment.
Typically, I'll draft a post in MS Word then open the git repo for my site, hosted on github pages, duplicate and rename the template.html page that includes the CSS, footer, and header for my site and then copy my content into it. When I'm happy with everything, I'll make my commit and then a minute later it's live at my custom domain. Seeing that it takes only 11KBs and 26ms to load my landing page strangely delightful.
There's a lot you can do with just plain html these days if you just need a clean site. Here's an example from my recipe site (https://xilic.com/recipia/sauces/pesto_traditional.html), mostly for my personal use or sharing with friends, with only html/css. It has expandable boxes, a menu system, etc. A simple script converts a directory structure of .csv files to these recipe cards with a template, and this way you can edit the sources in a spreadsheet and then the publish script just takes whatever is new and re-does the whole lot of html as necessary. Just like we used to do with Apache Forest!
What a beautiful website ! Feels carefully crafted, full of nice moments like the > turning the a - when sections are open in the TOC. Would love to hear more detail on how you went about making it. Did you ever consider sharing parts of the source code ?
Hugo worked for me. And as part of the GitHub pipeline that builds the site and deploys it I can grab some ‘dynamic’ content (from a Notion DB) and render it. Subsequently I added Zapier so that when the Notion DB changes it triggers the pipeline to update my website. The only thing I pay for is the web hosting with dreamhost.
https://www.planetjones.net/blog/03-05-2023/relaunching-my-p...
Did he reinvent a static-site generator? Markdown, pandoc, makefile... Sounds like a job for hugo/eleventy/jekyll/whatever.
I don't maintain a blog so my opinion may not count for much, but I feel like if what you are trying to do doesn't fit neatly into an SSG's existing templates/themes, it may in fact be easier just to use pandoc and some simple tooling around it. Certainly when I looked into a few SSGs for the purpose of making a simple personal website (without a blog) I found I would spend more time trying to bend them to my will than just writing what I want in markdown and running pandoc on it.
Its the the first time someone has reinvented a static site generator...
Looks around sheepishly
Yeah, obviously this is literally what something like Jekyll or Hugo does. It's just (at least to me) a simpler version of that where you can fully see what's happening. Also I didn't want all the theme-ing overhead that comes with those - just something I could inject into my existing site.
Good on ya! HTML+JS is plenty performant for a blog and I'm always happy to see more people eschewing frameworks when they're not necessary.
I've been writing a progressive web app that is, itself, a "web component" (custom element), built entirely with custom elements, so I feel like I've got a pretty good idea of how you can tackle that header reuse bullet point. Happy to give pointers if you're interested in that at all.
Anyway, great job on simplifying things! I hope it gets easier from here!
I started a portfolio website with Netlify (iirc), then I moved to Vue + Gridsome (on GitHub pages), then Next.js with Tailwind CSS, and was about to move to Vite.js over winter break.
That's 4 stacks over the course of 5-6 years. Not worth it.
Decided to do the sensible thing and use GitHub's README functionality. I prefer this approach and wish more folks in the tech community adopted it: https://github.com/SuboptimalEng
This is an interesting idea! Honestly I didn't even know Github had a per-user readme until you mentioned it
I hate the UI layer, for this reason. Nothing is ever stable. I'm looking for "Boring" and "Googleable in the age of AI slop". The other alternative are frameworks small enough to easily comprehend.
The UI is often tangential to the heavy lifting done by the back end. It often needs to be "just good enough".
GitHub was just down the other day. Why would you want your personal website/portfolio to be tied to GitHub? Crazy "modern web dev" stacks are likely overkill, but that's not an argument against self-hosting.
Because it's free and convenient, and other hosting providers don't magically have 100% uptime either. Not even necessarily more uptime than GitHub.
Personal websites can be down a few days a month without a problem.
+1. Not like my $5 hosting plan has less downtime than Github. Well... maybe? Fewer moving parts perhaps. But it's not immune.
sounds like a self-inflicted problem really. Why do you even change stack that much if what you want is a simple functionality?
I'm surprised to not see Astro mentioned, its whole schtick is providing very similar DX to frameworks like SvelteKit except in a way that's geared towards generating plain HTML/CSS with zero JS by default. You get things like components with scoped styles but they are compiled down to nothing. It's really a breath of fresh air.
Once I randomly discovered Astro, I couldn't go back.
I love that you can even drop in Svelte and React blocks right next to each other, so you basically the power of all the advanced frameworks, and the choice to pare it down to a barebones html static site
Yep -- I rewrote my blog over new year's with Astro and am pretty happy w easy markdown and a bundle size of zero bytes.
Astro is my favorite tool for static sites these days. It's wonderful.
Why on earth would you use something like sveltekit in the first place for such a simple website?
I know people will say for the learning experience but learning what? How to basically "hello, world" in sveltekit?
why wouldn't one use sveltekit if they only have html and css? sveltekit compiles to a static site with a nice client-side router.
sveltekit is basically html + css in a .svelte file if you don't use javascript.
I write my website and blog directly and entirely in HTML using BBEdit. For me, this is just much easier than any other method. I don't have to rely on any external system.
Same here. Any text editor would work, of course, but I like BBEdit because of all the customization options. I’ve set up a bunch of shortcuts for frequently used tags; after some practice, I’ve become able to write prose in HTML almost as smoothly as in a word processor.
When I redid my ancient personal site—started in the late 1990s—to make it mobile-friendly a few years ago, BBEdit was also useful when making changes across dozens of files at once.
Writing your own static site generator is good for you. I'm using raw Jinja2 templates and a tiny python script to do my shared header/styles etc. Outside of that it's all shell scripts and raw HTML/CSS.
I also decided to develop my personal website in plain HTML. I looked into a bunch of static site generators and found that direction to be too complicated and slow for me.
I still wanted the ability to have a common headers and footers and unique sections without repeating myself in every file. So I created a very small PHP application (just 5 files) and each page or blog post is a single PHP file in a directory. These PHP files have a small bit of metadata code at the top but are otherwise just plain HTML files. In each directory is layout file that wraps the content and these nest up the directory structure. So my site has a common header and footer and each section has their own subheader.
With the ability to publish by git push to the server, writing a blog post is as easy as creating a new file, git commit, and git push.
If you OK using a tiny tad JavaScript, it should be able to re-write that portion of the DOM to have HEADER and FOOTER common. Nonetheless, if you are also OK using Github, it has built-in setup where you blog in Plain-text (MarkDown) and things just works. You don't even need to build it on your local machine.
I wrote about it when I moved from WordPress to Jekyll. https://brajeshwar.com/2021/brajeshwar.com-2021/
Hugo is also nice for this, and allows for markdown, embedding Mathjax or LaTeX, etc. Your minimal approach mirrors some of what I've seen in Hugo or Astro, and I'm all for it. I wish we had truly minimalist SSGs, I think the idea has a lot of purchase.
I think PhpStorm/WebStorm has LiveReload built into it. It's been years since I've used it since I don't usually write plain HTML/CSS. But it was just a button click away IIRC. You shouldn't need to restart any servers no matter what you do anyway, just press F5. Still not hard.
I use PHP+Twig on my simple websites just so I don't have to copy-paste the header/footer/nav. It's still incredibly simple, very close to HTML+CSS and no build times. You can FTP upload your files if you want it works.
What I like to do:
- have HTML files for the individual pages/posts (I like the freedom that custom HTML provides)
- have a script file consisting just of a single array of meta data blocks for the individual posts (headline, description, preview image(s), date, tags, additional assets to load, like additional CSS or JS, if required, restricted visibility, etc. – most of this is optional) and content for the preview
- a server-side template script that generates the chrome around an individual page view and a paginated list view from the feed data (this allows for things like pagination, cross-links, filters per tag, we can generate multiple views), and we can also generate a RRS feed from the feed-index. Moreover, as there is also no external input other than fragments from the request URI, which can be laundered easily (e.g., by discarding all non alpha-numeric characters) and checked for resolving to existing file paths in given constraints, this should be also considerably secure. (This is actually a rather short script.)
- a server config (`.htaccess` or similar) that parses parts of the request URL to parameters to be used by the template script.
(So, adding a post is as simple as adding a new HTML file, copying an entry in the feed file and modifying it accordingly for the new page. And it can be done all in a text editor. The only thing missing may be a full-text search, as there is no DB involved and no representation of the content as normalized plain text. On the other hand, this also keeps the server load low.)
I decided to do write from scratch for my own site, and found that a real burden was maintaining lists of pages: there was no framework helping me out, and every time I added a new page I had to remember to go update my list of blog posts in the 2 or 3 pages I could access it from.
To solve that and other issues, like adding an rss feed and letting pages specify their own publish date, I did what anyone would do: write a custom web server. It's up at https://github.com/playtechnique/andrew/, if anyone wants to give it a whirl.
A few lines of PHP can solve that. The difference to other solutions is you don't have to compile/build/CI-CD it, just copy the PHP files in a folder, change a few things in the ini and you are ready to go.
For sure! PHP's a great language and tool! You'll still need a web server and modphp or something, and that web server was still probably compiled, but of course with bigger projects you can often get them from your distribution's package manager.
A little project like mine isn't the right answer for everyone; right now its only user is me. How it solves the problem fits my own little brain : )
Lots of people saying they did something similar, so I'll add that I also did something similar for learning / fun(?) with the added wrinkle that it runs on a raspberry pi at my house. I used golang's Fiber to serve the html/css. Fiber comes with some built-in templating as well to help with the layout. https://www.ianmyjer.com/content/homelab.md
When I used to do interviews to frontend developers I often had them write a form with validation...in plain HTML and a sprinkle of js for some of the final validation touches.
Was kinda surprised at how many senior leetcode blackbelts didn't know HTML had built in validation :)
JS was required for some of the more complex validation logic and mounting few dom nodes (and again, surprisingly, many didn't know how to create an element and mount it!).
On the other hand I got to learn lots of nice tricks to complete some of the features (elements had to appear with conditional logic) with CSS only which was nice.
HTML has built in validation, but the behavior and control over it is not great. I am using it in my projects to some extent, but it does not cover 100% of the needs. Because of that, some people skip it completely and almost forget it does exist.
As others have said, you are reinventing the Static Site Generator. I would strongly urge you to look into those.
If you know Python well enough, my recommendation is Pelican.[1] You can author your posts in Markdown. You specify the desired HTML/CSS. It will then do all the boring work for you. Then just upload the static files to a webserver.
> spending too much time on Hacker News gave me the misconception that writing a website using plain HTML and CSS would be a relatively well-paved path in 2025. I spent some time looking around for guides or a “canonical” way of doing this and found that there isn’t really one.
I had this exact same surprise last year! For whatever reason, there really isn't any sort of standard way of creating a vanilla site in 2025!
To contribute to the authors open questions at the bottom: for reusability, use web components [1] and for hot reload use a file watcher with a websocket, or just lean on your ide if possible (e.g. jetbrains).
[1]: https://developer.mozilla.org/en-US/docs/Web/API/Web_compone...
You might find Teeny (https://github.com/yakkomajuri/teeny) interesting for this.
Something I built to have my own site in static HTML and CSS.
Nice job! If only HTML had a serious templating system(no the template tag isn’t enough) that could be used without JavaScript, we won’t need any 3rd party system for assembling static sites. For example a mechanism for including partials with the <link> tag and refer them inside a <template> or directly into current html
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/if...
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/po...
https://en.wikipedia.org/wiki/Server_Side_Includes
Also, other than to satisfy a purist desire, why do you need this?
You can pre-render HTML quickly using a variety of template systems, and it would outperform what you are suggesting every time (from a client's perspective). I mean, think about the potential CSS resolution complexity, FOUC, etc.
In the 90s, we used Server Side Includes (SSI) for this. Probably still works.
One modern approach would be Caddy Server's templates, using Golang templating:
https://caddyserver.com/docs/modules/http.handlers.templates
The "include" function should do the job:
{{include "path/to/file.html"}}
httpd, nginx, a number of other servers support SSI
https://nginx.org/en/docs/http/ngx_http_ssi_module.html
Caddy chose not to, I guess?
https://caddy.community/t/caddy-update-on-ssi-server-side-in...
(Chiming in because other people replying to you kept on the "iframe-like" part of the argument)
Or serializing `<template>`s without needing JS. Like in lists (`<ol>`, `<ul>`, `<dl>`...). All in all `<template>`s are a nice thing to have, and I do use them a lot (like in my own portfolio), but it feels really lacking without JS.
We've got frames and iframes...
You could use HTMX.org ;)
Does HTMX work without Javascript?
They wrote the javascript so you don't have to.
I mentioned the object tag elsewhere: https://news.ycombinator.com/item?id=42706227
The best thing about this post to me was the screenshot of the directory organization. It’s the little things like this that making thinking “how to start” a matter of “where could I start”.
I do mostly the same, .md and pandoc, but also mo for templating:
https://github.com/tests-always-included/mo.
Took just a few minutes to setup. E.g. https://afarah.info/public/blog/awsv3/index.html.
Writing in Markdown with {{mustache}} templates for DRY is very satisfying, a simple bash script renders it. Looks good on my phone even.
I have a pretty elaborate Hakyll site with custom routers and all kinds of junk (https://dpitt.me), but it's an old site that started as Django, then I built it from scratch with Sinatra, and then was Jekyll for years. There really is something special about a well-organized static site. For all the rewrites of this old thing, I can't imagine moving away from static site generation.
Recently redesigned my site [1] and used nextjs app router (moved from page router).
The new paradigm of adding “use server”, “use cache”, and “use client” felt too magical by default.
Server actions are easy to forget adding validation and proper access control on. You need an external library to avoid the common pit falls.
I’ve been contemplating whether to move to something simple. The complexity creep is real.
Adding validation/access control to server actions is pretty much the same as for API endpoints though?
I'm not sure next.js is the right fit for a blog/personal site either, but that's an odd point imo.
Your site looks very nice though!
[dead]
I did kinda the same thing. Not being a backend dev didn't stop me using some PHP, basically as template language. It has a few downsides as well, but overall I am happy with it.
The CSS for this site (root.css) is beautifully simple! The colors, spacing, and fonts are very comfy - this is exactly the look I'd want for my blog.
> It took me hours of Googling and trying out different options to come up with this awful piece of code that worked to load the contents of a file and give them to my page [CODE]
Do I have Stockholm syndrome or is the code here completely fine?
This whole piece kind of feels like the author just doesn't understand Svelte, so they threw it out and used something they do understand.
Yes, it probably is a good idea to use technologies you understand. But you not understanding Svelte isn't a Svelte problem.
FWIW I just import a canned CSS theme (Terminal CSS), MathJax, and the roll the rest in raw HTML;
it’s simple and maintainable.
Love this. Building a website this way really teaches you why we started having all the complexities in web frameworks today. For certain simple websites like this one, the tradeoffs are worth it. I rebuilt our company website this way too. (Sescollc.com)
pandoc for the win. I use to convert my md resume into doc/pdf whatever.
There is a tool called entr, it kill and restart command when any file changes are detected, you could check it out.
Plain HTML and CSS personal site experience can be vastly improved by using server side includes. Your webserver's SSI module is likely just the right amount of templating power so you don't have to re-write the same HTML in $x spots with a minimal attack surface and maintenance burden. SSI hasn't changed in 20 years and the nginx module at least hasn't even ever had a cve.
<!--# include file="/menu.html" -->
...
<!--# include file="/footer.html" -->
SSI's were my first foray into "backend," if you can even call it that, sometime around the year 2000. Some benevolent commenter on Slashdot gave me the tipoff, and my growing frustration with copy-pasting HTML snippets between pages was henceforth a thing of the past. Then came PHP, Python, et cetera, and the rest is history.
Amazing how such a simple mechanism can remain useful even decades later.
we need more of this. Thanks for sharing!!
This is exactly how I generate my site[^1]. Except I use a simple Node script to handle hosting a tiny HTTP server.
Node calls pandoc, which converts my markdown into HTML, ESBuild to convert the few JS snippets I run on my site (which I write in TS), and SASS to convert my scss stylesheet into a bundled CSS sheet.
It's super lightweight and I like that I can bend it to do whatever weird shit I want my site to have without relying on a 3rd party static site generator.
[^1]: https://pfy.ch
text is not json.
Here's some of my tips for a handwritten HTML site, since the author wished more tips existed:
- consider using an HTML boilerplate template like this one if you don't know where to start: https://www.matuzo.at/blog/html-boilerplate/
- consider using a CSS template, or a CSS reset, if you don't know where to start with styling. Pico CSS is a good drop-in: https://picocss.com/. Frontend devs always blog about their CSS resets, like this one: https://piccalil.li/blog/a-more-modern-css-reset/. But if you're someone inclined to write their own HTML, then you'll probably also want to write your own CSS. This takes time to learn. Especially learning how to design the page without looking crappy
- I copy my last page as a template whenever writing a new page
- I don't worry about code duplication. If I need to refactor duplicated content, I use search and replace across files in vim (like https://nithinbekal.com/posts/vim-search-replace/). Hopefully your editor/IDE has something similar, and hopefully you're comfortable with regexes
- markdown + pandoc + scripting is a common solution. Technically it's not handwriting HTML at this point -- it's hacking together your own static site generator instead of using an existing framework -- but no biggie
- frontend people have made a lot of live reload tools over time. Here's a couple: https://nitoyon.github.io/livereloadx/ and https://github.com/tapio/live-server. Personally, I've cobbled together something with entr/caddy/websockets/userscripts. I've had problems with `python -m http.server` freezing up occasionally, but YMMV
- About RSS: you can generate your own feed if you already started your own generator script. Personally, I let this tool generate a feed for me in a GitHub Action: https://feed-me-up-scotty.vincenttunru.com/, but the feed quality is meh
- Expect to do a lot of fiddling. You'll reinvent things. You'll lack common features for a while. Embrace this as minimalism. You'll begin to appreciate the tasks that frameworks automate (image optimization, compression, meta tags, validation, etc)
- You'll face growing pains after you cross certain thresholds of page counts. Personally, I'd rather be grug-brained and edit more HTML than figure out some new framework. This is fine for a personal website with a straightforward structure
> copy and paste content and not having layout page is annoying at times
HTML was envisioned as an SGML application/vocabulary, and SGML has those power features, such as type-checked shared fragments/text macros (entities, possibly with parameters), safe third-party content transclusion, markup stream processing and filtering for generating a table of content for page or site navigation, content screening for removal/rejection of undesired script in user content, expansion of custom Wiki syntax such as markdown into HTML, producing "views" for RSS or search result pages in pipelines, etc. etc. See [1] for a basic tutorial.
[1]: https://sgmljs.net/docs/producing-html-tutorial/producing-ht...
> Yes, you must copy and paste content
Many people who maintain their own sites in vanilla web technologies tend to create reusable functions to handle this for them. It can generate headers and the like dynamically so you don't have to change it on every single page. Though that does kill the "no javascript required" aspect a lot of people like
Of course you could simply add a build step to your pure HTML site instead!
I've adopted the idea that a blog post is archived when it's published; I don't want to tinker with it again. Old pages may have an old style, but that's OK, it's an archive. Copy/paste works great for this.
The only reason I use a blog engine now (Hugo) is for RSS. I kept messing up or forgetting manual RSS edits.
I really love this! I've seen it in action a couple times in the wild, and it's super cool seeing how the site's design has evolved over time.
It also has the benefit of forcing you to keep your URIs stable. Cool URIs don't change: https://www.w3.org/Provider/Style/URI.html
I recently learned the object tag can do what I wished for in the 90s... work as an include tag:
Turn your back for twenty-five years, and be amazed at what they've come up with! ;-)Should reduce a lot of boilerplate that would get out of sync on my next project, without need for templating.
Unfortunately that will require the client to make additional web requests to load the page, effectively doubling latency at a minimum.
A few extra <object> in a blog post is a worthwhile tradeoff, if you're literally using raw HTML.
- HTTP/1.1 (1997) already reuses connections, so it will not double latency. The DNS lookup and the TCP connection are a high fixed cost for the first .html request.
- HTTP/2 (2015) further reduces the cost of subsequent requests, with a bunch of techniques, like dictionary compression.
- You will likely still be 10x faster than a typical "modern" page with JavaScript, which has to load the JS first, and then execute it. The tradeoff has flipped now, where execution latency for JS / DOM reflows can be higher than network latency. So using raw HTML means you are already far ahead of the pack.
So say you have a 50 ms time for the initial .html request. Then adding some <object> might bring you to 55 ms, 60 ms, 80 ms, 100 ms.
But you would have to do something pretty bad to get to 300 ms or 1500 ms, which you can easily see on the modern web.
So yes go ahead and add those <object> tags, if it means you can get by with no toolchain. Personally I use Markdown and some custom Python scripts to generate the header and footer.
The other solutions are even easier and don’t double latency.
> be cached for subsequent access.
So now you need to setup cache control?
Isn't using React with a static site generator framework basically the same thing but better?
Yes, if you want to throw up in your mouth.
> Yes, you must copy and paste content
Manual work is almost never a good solution. Try this:
A slightly simpler version of same is:
As noted in a peer comment, the cat[0] command supports concatenating multiple files to stdout in one invocation.HTH
EDIT: if you don't want the output file to be named "a.page.html" and instead it to be "a.html", replace the above cat invocation with:
This syntax assumes use of a POSIX/bash/zsh shell.0 - https://man.freebsd.org/cgi/man.cgi?query=cat&apropos=0&sekt...
Why not use server side includes? Most web servers support it, and it dates back to one of the early features of webservers.
Because that requires a server with the proper config and this is an HTML file. So it works in every environment, like locally on your machine, or GitHub pages.
`cat` supports multiple files, no? The whole point is that it concatenates. Why use 3 commands?
Because I’m typing on my phone and the line was long. Thanks!
Oh man, cattiness use of cat!
How do you do for syntax highlighting ?