So while everyone is sort of in the process of rediscovering the way this World Wide Web works before we were all on the big platforms hating everything, I want to share how I make my own websites because I use a really cool tool called a static site generator that requires a bit more effort on my part, but gives me complete control over everything and lets me automate away some of the tedium of running a static site (I'll explain what that is in the next section).
It lets me focus on my content, only having to add the bare minimum of JavaScript and CSS that I need to make things interactive and look pretty. It's the closest I've felt to my high school days of slapping stuff on Geocities with nothing more than notepad and the copious amount of time an introverted high school nerd has. While there is some code involved, I don't think there's so much that it requires a professional-level dev like me to figure out, and a lot of work has already been done for you.
It's not the only way to make a website or even really the most popular way these days (I'm going to talk about that too), but I think it's a very accessible way that lets you have full control and seems to be generally unknown outside a circle of programmer weirdoes like me, so I am writing up this series of posts talking about it.
And just to reassure you that you can make a nice, modern site that can have a lot of content I suggest you take a look at my sites for my upcoming text adventure Quoll and The Fantabulous Season of '40, a TTRPG campaign I mean to run some day. I'll keep pulling examples from these as I explain. Any way, let's get started by talking about what a static (web)site and static site generator are, starting by comparing them to "dynamic" web applications (like Cohost!) that tend to be more common online. This is mostly going to be a bunch of introductory fluff that I will expand on with some practical details in future posts, so feel free to skip over stuff you're already familiar with.
The New and Busted: Dynamic Web Applications
(Aside: dynamic web applications aren't really "busted", but I liked the joke.)
Rather than starting with a static site, I actually think it's helpful to start with the more popular dynamic web applications, because I think it will make it clearer the advantages and disadvantages of a static site. While I don't actually know how Cohost works exactly behind the scenes, I feel like I can make some reasonable guesses, so I will use it as an example.
Most modern websites are more accurately described in my mind as "dynamic web applications". There's a few basic parts of these, divided into "frontend" and "backend":
- Backend: The backend is usually made up of two parts. The data is stored in a database, and the data in that database is accessed and updated by an Application Programming Interface (an API).
- Database: This is a database of all the data necessary for the website. For the example of Cohost, this will include all the data of the various users, all the posts they made, all the comments other users make on posts, information about who shared what posts, what images were uploaded and likely many more things. The database is usually the "source of truth", everything else is about working with that database.
- API: The API of Cohost is (most likely) a set of "endpoints" that take HTTP requests that can be used to get and update data from the database. For example, when you click the "post" button, the button will cause a call to the API to add a new post for that user to the database. When your timeline is loaded, it will make an API call to get the current timeline for that user, loading up all the posts that user follows.
- Frontend: The frontend is all the code that handles the user interface (UI) of Cohost, taking the data, accessed through the API to generate HTML and CSS (and possibly JS too) that is sent to your browser and rendered. The Frontend for Cohost is likely a combination of existing HTML, CSS, and JavaScript that is combined together with say, the CSS crimes you added to your post to get a final page the browser renders. There may be multiple parts of the frontend, but that part of web applications tend to have a lot of different ways to be organized, so I'm less eager to assume what parts are there.
As I said, I'm completely guessing here how Cohost is set up, it's completely possible that there's more "static" parts that I'm not accounting for. But we can consider this "dynamic" because the idea is that there is probably not some HTML file on Cohost's server for say, this completely terrible shitpost I made a few days ago. Instead when I type in the URL, it is passed to the API, which gets the data of my post, passes it to the frontend code, which then renders my shitpost for everyone to see.
This may feel a bit of complicated, but it is definitely how most "web sites", especially big ones work. It's what an application framework like WordPress is meant to provide for you. There are serious benefits to this way of doing things, especially if the data is constantly changing from a lot of different sources, such as all of us making our bad posts.
But let's go back to the past and talk about static sites, which are much simpler.
The Old Hotness: Static Websites
So back in the early days of the web, these type of dynamic applications were just an idea that required a lot work using technologies like Perl, CGI, and PHP to implement in a way that was much more fragile and labor-intensive. All of these types of technologies were not part of the World Wide Web, per se, but sort of extra technologies that worked within the confines of HTML and CSS and JavaScript and the World Wide Web. (The same could be said for the modern dynamic web application design...)
Instead of doing that, many sites, especially small personal ones were instead static. That is, there was some folder on an HTTP server that had the various HTML, CSS, and JavaScript files that were available. Moving around the website essentially caused the browser to send requests to the HTTP server saying "please give me the file at this URL".
This is similar to how the backend of a web application responds to HTTP requests for certain URLs, but rather than this being something the backend code generates on the fly, the HTTP server was less sophisticated. It would go look what unchanging files it had on its file system and return those files without any extra processing. If it couldn't find one, it instead returned the dreaded 404.
The fact that the files were "unchanging" and "pre-existing" is why this is called a static site. Perhaps this may be clearer if I show you the file structure for the Quoll website, which you can see in the first attached image.
Don't get lost in the details, especially since this is a dev version on my machine with a lot of unreleased changes, but note that for example, there's an "index.html" file in the root "Release" directory. That "index.html" is the same index page you see when you first land at the website.
On that index page, if you click the "Dev Diaries" link, you're taken to this Dev Diary index page, which corresponds to the "index.html" file in the "DevDiaries" folder. On that Dev Diary index page, if you click the link to a particular diary, you are taken to the page for that diary entry, which are the other HTML files in the "DevDiaries" folder. For example, you can go to this dev diary entry on pronouns. This also includes the images and CSS and JavaScript that would be loaded up for particular dev diary entries, though I don't have any of those on the release site, as of time of writing (I'm working on it!).
Note that this isn't really different from how the dynamic web application feels to use, the difference is all behind the scenes. Just rather than a backend server generating the responses to the URLs on the fly, there's just static files that the HTTP server loads up. This used to be how most sites were on the WWW but we began to expect more, and that's why web applications like Cohost dominate. But the old ways still work... but there's a downside...
Updating Static Sites by Hand
The wonderful @itsnero actually has a great guide on making static websites with lots more practical detail of working with static sites like this! What I will write here does not invalidate anything he wrote there! It's great stuff, you should go read it! But for right now I want to draw attention to what he mentions about the process of updating a static site for a webcomic:
For ongoing updates to a webcomic you could:
- Make the most recent comic on home.html into its own page (ex. the image on home.html is moved to 004.html)
- Update the NEXT link on 003.html to link to 004.html
- Change the image on home.html from 004 png to 005.png
- OPTIONAL: Update your RSS feed!
(There are ways to do this automatically as well, but that’s something out of my scope of knowledge unfortunately.)
This isn't too much work, but note that with these files all being static, you have to go and manually edit each file to make an update. This isn't too hard in this case, but what if you want to add tags to a blog post? You would need to add/update each tag page that collects all the posts with the particular tags. Or sticking with the webcomic example, if you have years of archives, every new comic would have to have all the various archive pages that the comic would appear on updated too. Back in the Geocities day, this is also how I updated my website, going through and updating every relevant page based on the new material.
It's not a lot of work, but a little work like that on each update can add up fast, and I no longer have the copious amounts of free time I had in high school. But as he mentions, there are ways to do this automatically! And one of those ways are static site generators!
The Point: Static Site Generators
At its heart, a static site generator is exactly that automatic program that @itsnero was hinting at. I point a program to an input folder of files. That program runs through all the files, using them to generate the final static HTML. I get the exact same folder that you can see in the first attached image. I literally just take that folder, drop it onto Netlify's servers and then it puts it up for everyone to access.
That's it.
For the Dev diaries in Quoll, I don't actually write them in HTML, but instead I write them in Markdown (just like how posts on Cohost are written!). In a different folder, I have all of these input Markdown files (with the ".md" extension) as you can see in the second attached image. I also have a handful of Handlebars templates (with the ".hbs" extension).
I'll get to the details of these files in later posts, as this one is already way too fucking long, but basically, I point my static site generator, Statiq, to my input folder of files. It runs through the Markdown files and templates to generate all the static HTML pages you see in the output folder.
The fact that it can know of every file in that folder allows it to be able to generate the dev diary index page. I can use metadata written at the top of each Markdown file to do things like add tags or specify the release date. Then Statiq can use that metadata to know where to add the right links for tag pages or archive pages.
It took some effort to write up the bootstrapper that does this work, but now that I'm done, all adding a new dev diary takes is putting a new file in the folder, and re-running the program.
And that's why I think static site generators are cool. You don't have to necessarily use Statiq, it's kind of... low-level as far as these things go, and requires a bit of C# code. There are other alternatives for other programming languages. That being said, the dev behind Statiq has already done a lot of work of providing a nice set of modules that can be chained together out of the box, so your bootstrapper code may be as straightforward as chaining together the right modules.
What Are the Downsides?
Though I much prefer this level of control over everything compared to running a web application like say, WordPress, there are some downsides. The first is that static sites, even with a generator aren't great if you want people to be able to leave comments or other user content (like the posts on Cohost!). They're static. It's not meant to account for that dynamism. The files are generated once, and then they stay the same until they are generated again. There are services you can use here like Disqus, but that's going to take extra work.
This also applies to doing things like authentication and authorization. There are services you can use to help with this, but if you wanted to have part of your website be only accessible to a small subgroup of visitors, say your Patreon patrons, that is going to take extra work.
That being said, I think a lot of people don't always need or want those features, and if that's you then static sites and static site generators can be very good!
The other downside, particularly with Statiq, is that it requires some initial effort and possibly coding to get this all working, and while I didn't find it tough, you may. But once again, it's mostly a one-time effort. Once you have your bootstrapper running, it really is just dropping new and updated files and re-running the program.
I Wish to Know More
That's all I got for this post. Later, I'm going to make some follow-up posts talking in more detail about how I use Statiq exactly. If you would like to preview some of the way I write this, you can look at the Github repository for the Fantabulous Season of '40.
The Quoll Repository is private for now as I am working on the game, and has a lot of extra stuff around the game itself that would muddy the waters, but my posts will pull some examples.
