A Fancy New Website Redesign

Justin Wernick <>
Curly Tail, Curly Braces
2020-09-06

Abstract

I've done a redesign on this website. It has a new fancy stylesheet, a new fancy static site generator, and a new fancy URL scheme. In this article, I talk about what's new. I tried to make this transition seamless for RSS readers, but it's hard to know exactly how all readers will respond. If you subscribe to this site using RSS, and have just been notified about the whole site being new, I'm sorry.

A New Design

Today I'm unveiling my new website design. If you remember what it used to look like, you'll immediately notice the difference to the design, but the redesign goes deeper than the stylesheet. I've ripped the whole lot up and rebuilt it.

A Fancy New Stylesheet

I've heard many times that my previous design was ugly. It looked good to me, but nobody else seemed to agree. My new stylesheet is heavily based on LaTeX.css, a stylesheet that's meant to make a website look like it was typeset as a LaTeX article.

I discovered a few nifty CSS features that I didn't know about from this. The CSS property scroll-behavior can be used to animate scrolling when you click a link to later in the document. The CSS property hyphens can be set to auto to allow the browser to break words in paragraphs using hyphens. I'm often impressed by how much you can achieve with CSS alone.

A Fancy New Static Website Generator

Previously, I was using Jekyll for this site. Jekyll is great, but I decided to move away from it for a few reasons. The first is that keeping the Ruby environment to run it in was taking more time than I felt was reasonable. There are solutions to this, like using Docker to build the website in a reproducible environment, but there are other considerations. The second reason is that Jekyll is focused primarily around writing Markdown files, that have Jekyll-specific annotations. I wanted to rather write Org-mode files, and set things like the title of blog posts in the way that Org-mode expects. I partly solved this problem by using a plugin, but it still required the Jekyll-specific annotations.

The solution I went with was to write my own static site generator, that caters specifically for exporting only my website. It's written in Rust, and makes use of an Org-mode parsing (and HTML-exporting) library called Orgize.

Using code instead of a prebuilt generator means that I can do some things that wouldn't usually make sense in a 'generic' static site generator. For example, I have a special block element for an abstract, that I put at the beginning of each article.

I also automatically detect and links to other Org-mode files on the site, and update their URLs to point at the .html file I'm going to be exporting. For example, in my source code I'm pointing at some-other-post.org, but when I export it will update it to some-other-post.html. This makes it very convenient to work with, because the link works both in the source code, linking to other source code files, and after I've exported it, linking to other exported HTML files.

I'd like to take a close look at what I've written for this static site generator, and publish it as open source. Some of it can be contributed back to my upstream dependencies like Orgize, but some parts could be useful as a library that makes it easier for others to make their own static site generator.

A Fancy New URL Scheme

My export process mostly takes Org-mode files and produces an HTML file for each one. My new URL scheme is the same sort of thing. There's a file called blog.org. When it's exported, its URL is blog.html. This is different from Jekyll, which encouraged you to put markdown files in a directory named _posts, which is then mapped into a production URL with many nested folders.

My previous site also had a confusion built in, where I never really settled on if URLs should be something like /blog/ or if it should be /blog.html. I'm now settling consistently on /blog.html. The thing that settled it for me is that I'm considering adding more formats to my export in future. If I ever include PDF exports for blog posts, you'll be able to see /blog.html for the HTML page, and /blog.pdf for the PDF of the same page. I don't know if PDFs are really necessary for the site at this point, but I use printable PDFs for proofreading on paper, so I want them even if nobody else does.

This change is a bit tricky for RSS feed readers. It's a common pattern in RSS feeds is to use the URL of the thing in the feed as a unique ID, so that feed readers know when they've seen something before. By changing my URL scheme to something that works well with the new way I want to work with my site, I've changed the ID scheme in these feeds. I'm manually overriding the id in existing posts to match their previous URL, so it should be fine. It worked on the feed reader I tested with, but RSS is an old standard and there might be readers that don't follow the rules in the same way that I understand them. Sorry if I've messed up and your RSS reader didn't like this change.

The other thing that I had to consider was being compatible with the old URLs. My blog has been around for a while, and there are links to specific posts floating all over the web. I kept those links valid by having my web server return a redirect response pointing to the new URL.

I Hope You Like It

I think that the site looks much better than it did before, and in the backend I really like my new static site generator. I hope it didn't accidentally make RSS spam.


If you'd like to share this article on social media, please use this link: https://www.worthe-it.co.za/blog/2020-09-06-a-fancy-new-website-redesign.html

Tag: blog


Related Articles

A Quick Introduction to Graphviz

Graphviz is an awesome tool for software documentation and visualizing graphs. In this post I explain the core concepts that you need to get started with Graphviz, with examples.

Literate Programming

Literate Programming is a way of writing software by embedding code blocks into normal written documents (like this article itself). In this article, I explain what Literate Programming is in an abstract sense, and then introduce my preferred Literate Programming environment: Emacs Org-Mode.