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
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
/blog.html. I'm now settling consistently on
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.