Maxwell Flynn

This is a Static Site. But why?

I hadn't updated my website design since sometime in 2018. Back then, my goal was just to create a really barebones website that I could throw links to my projects on. With that in mind, I just put everything into a single index.html file, threw together some CSS and bam, that was my website. I thought this was incredible in the simplicity department. Any time I needed to update the site, I could just fire up an editor and add the new markup for whatever I wanted to show off.

But it was nowhere as smooth as this. I'd dread adding anything to my previous site because it was tedious. Find the location of where I want to insert the new content. Write all new elements for that content, or copy and paste old ones. On top of that, if I was adding a project to the site, I would want to describe what the project was. This would mean that I was doing any kind of writing all in an HTML file, which for me is honestly very painful. I don't want to have to think about markup and flow when I am writing, I just want to write.

An old screenshot of some markup for my previous site design Here's an example of some of the HTML for my previous site iteration. It's not too bad but still could be far better.

Need for Speed(y editing)

The design I used previously for my website was getting stale. On top of that, I didn't really have anything that made it fun for me. It was just an index for work I've done. If I didn't have some new project that I put out, I had nothing to put on my website. In fact, the last commit to my website repository for that iteration was June 8, 2020. With that, I set out to try and make something fresh to put up that would replace the old design.

Right after that last commit, I created a new branch on my website repository and got to work on a redesign. I decided that I wanted to use The Coolest Web Techâ„¢. So I chose to build my site with React. I wanted to have something that really popped out at a person that looked at the site, so I added a dynamic background with a canvas element that would show different visualizations when you navigate to the page. Like the previous one, it would show off what projects I've made, as well as what languages/tech I am familiar with.

Landing page of this React design Project section of this React design Technologies section of this React design

I liked this design at the time. It had a bit of a pop to it with the colors and dynamic background. I improved on the editability factor on the backend by making any dynamic content (such as projects or languages/tech) backed by a JSON file that would be fetched on page load. However, something about this design and overall edit flow still seemed off. I never got this design to a finished stage or published it. One of the things that I was meaning to do was add some kind of functionality where if you clicked on a project it would open a view with screenshots and a description, but I never got around to implementing that.

Second Time Isn't the Charm

This React-based redesign sat dormant in a branch on my website's git repository for over a year. I revisited it after that year passed and realized that the design that I once thought was going to be a really good change of pace for my site was actually way too bloated for what I needed.

  1. I did not need to use React. For a website that was just supposed to be a collection of known items, I did not need a stack that would give me a single page app.
  2. I still would need to edit JSON files to add new projects. Which isn't exactly the most intuitive way to add content.
  3. Instead of having to edit an HTML file to add a new section of my website, I would now have to edit a JS file, create a component, add that component to the app page, etc. In trying to simplify the design I actually made it a bit harder to use.

I found myself starting to drift away from the idea that I just wanted my website to be a place where I just link to code repositories and what not. I wanted a place that I could share the thoughts I have about tech or anything, or tiny projects that aren't exactly fully fleshed out. But above all I wanted something that I could iterate quickly on.

Generate the Problem Away

After a bit of thought, I decided that I wanted a site with three distinct sections:

  1. A quick landing page as an "about me" that also links to my other accounts
  2. A blog of sorts that would be easy for me to just get my thoughts on a webpage
  3. A place that I can prototype quick ideas, whether they're games or mini-websites of sorts

If that sounds familiar, it's because that is what this site is. The index is the about landing page, you're reading the blog section right now, and "sketches" are the prototype section. I decided to approach it with a static site generator. There are a bunch out there, Jekyll, Hugo, Gatsby, etc. In this case I just decided to roll my own.

In my website repository, there is a generate_site.py script at the root, as well as a site directory next to it. Inside of that site directory is any html, JS, CSS, image, anything that will go into the final generated site. In particular, most of these HTML files are template files. For this purpose I use the Jinja2 template engine. Mostly because I am used to it from using Flask for many years.

For generating blog posts, I have two templates, an index template and a post template. The script checks a directory named posts for other directories nested within. If any directory is found, the script pulls the blog post content from a content.md file. On top of that, the script copies any CSS, JS, or images to the output assets directory. Typically for the posttitle and slug, it is derived from the directory name. So if the directory is named this-is-a-post, that will be the slug, and the title will be converted to This is a Post. Though, for titles that need special characters (such as this post), then there's a special title.txt that you can add to the directory that it will read from. Once that has been done, then the post page is generated using the aformentioned post template. Finally, once individual pages for each post are generated, an index page for the blog is generated with the array of posts that we've gathered.

Sketches are a bit different, in that I didn't want to be limited with what I could do for them. Whether I wanted to make a game or a mini-site, I didn't want to be limited by my generator. That means that the sketch generation step is largely the same as the blog post path, with two templates for an index and for an individual sketch. It differs in that you can specify a content.html, which will just be included into the sketch template. That sketch template also automatically loads any CSS or JS in the directory of the sketch. Eventually it might be better to just take all of those files, combine and minify them. For now, it just keeps them all individual in the output. Sketches also have a special preview image that can be associated by just adding a preview.png file to the root of the sketch directory. This preview image will be displayed along with the sketch title and last modified date in the sketch index.

Once the script has copied over any actual static content, constructed the blog and sketches sections, the site is finished generating! From there, all I have to do to serve the site is to point the content root for the server config to be at the output directory. With that, for deployment all I have to do is pull down the latest changes from the git remote, and then run the python script. This script also has a debug mode for local development that will automatically regenerate the output directory on modification. At some point I may expand the debug functionality to also run the built-in Python web server for debug, as well as live reload the site when something changes. For now, I am happy with this flow.

I put the generator to the test writing the Golf sketch, which was a breeze to work on. No fiddling with routes, no ensuring that I am serving static content from my Flask server, no request/response handling, just writing the code for the content I want to produce. All that adds up to what I feel is probably the most proud of a site design, both frontend and backend, I've felt in awhile.